Add, Update, and Remove Git Submodule

September 22, 2022


Submodules help manage complex projects in Git. They allow external repositories to exist as directories within another repository, which makes it easier to maintain separate records of changes for each feature, module, or microservice.

This tutorial will teach you how to perform basic submodule management operations - adding, updating, and removing Git submodules.

Add, update, and remove Git submodule.


Add Git Submodule

A Git submodule is a record in a repository that points to a specific commit in another external repository. When a user adds a submodule, Git creates a .gitmodules file in which it stores the mapping between the URL of the original repository and the local subdirectory hosting its contents.

To add a submodule to a repository, type the following command:

git submodule add [repository-url]

The command output shows that Git cloned the contents of the external repository into a subdirectory of the same name:

Adding a submodule to a Git repository.

Check the records by opening the .gitmodules file in a text editor:

nano .gitmodules

The submodule's path and URL are successfully registered in the file.

The contents of the .gitmodules file.

Specify Target Directory

To create a submodule with a name that differs from the original repository's name, add the custom path to the git submodule add command:

git submodule add [repository-url] [custom-directory-path]

In the example below, Git clones the contents of the external repository into a subdirectory named custom-name.

Adding a submodule with a custom path to a repository in Git.

Commit Submodule

As with any changes made to a repository, you must commit and push the submodule addition to remote before the changes become available to everyone working in the repository.

1. Commit the changes with git commit.

git commit -m [message-text]

The output displays the submodule creation action as a committed change.

Committing the changes in Git.

2. Push the commit to remote.

git push
Pushing the changes to remote in Git.

Updating Submodules

As the project progresses, the contents of a submodule repository may change. Since submodules point to a particular commit in the original repository, using git fetch to check for remote changes does not reflect the changes made to a submodule repository.

Use the git submodule update command to check if a submodule directory is up-to-date.

Submodule directories are initially empty in cloned repositories. When performing the first update, use the --init flag to initialize submodules and the --recursive flag to ensure that the command checks for nested submodules too.

git submodule update --init --recursive

The command registers the submodules, clones their content into the respective subdirectories, and checks out the submodule paths.

Updating and initializing submodules in Git.

If you are updating already initialized submodules, use the --remote flag to tell Git to enter each submodule directory and fetch any available changes, and the --merge option to merge local and remote changes.

git submodule update --remote --merge

The command output shows the changes made.

Updating submodules in Git.

Removing Submodules

Removing a submodule in Git involves the following actions:

  • Deleting the contents of the subdirectory.
  • Removing the subdirectory path registration.
  • Deleting the subdirectory.
  • Committing and pushing the changes.

Follow the procedure below to remove a submodule from a project.

1. Use the git submodule deinit command to clear the directory and unregister the submodule path.

git submodule deinit [submodule-path]
Deinitializing a submodule in Git.

2. Remove the submodule with the git rm subcommand.

git rm [submodule-path]
Removing a submodule in Git.

3. Commit the changes made.

git commit -m "[message]"
Committing submodule removal in Git.

4. Push the changes to remote.

git push
Pushing the submodule removal changes to remote in Git.

The submodule is now completely removed from the project, but the original repository still exists. It can be added again at a later time or maintained separately.


This article explained how to perform the most common submodule management operations in Git. After reading it, you should know how to add a submodule to your Git project, update its contents, and remove it if necessary.

For a more comprehensive submodule tutorial, read Git Submodule Guide & Basic Commands to Get Started.

Was this article helpful?
Marko Aleksic
Marko Aleksić is a Technical Writer at phoenixNAP. His innate curiosity regarding all things IT, combined with over a decade long background in writing, teaching and working in IT-related fields, led him to technical writing, where he has an opportunity to employ his skills and make technology less daunting to everyone.
Next you should read
Git Commands Cheat Sheet
March 10, 2020

Git commands are an essential lesson that every developer needs to master at some point. To use the full potential of Git...
Read more
How To Pull The Latest Git Submodule
August 17, 2022

Pull the latest Git submodule to your local machine and Fix the "Fatal: Needed a Single Revision" error by following this tutorial.
Read more
How to Perform Git Submodule Checkout
September 7, 2022

Learn how to obtain the contents of a submodule using the command line and how to automate the checkout process with GitHub actions.
Read more
How to Restore a Git Repository
August 1, 2022

Accidentally deleted a critical Git repository when cleaning up? Forcefully pushed a new commit before fetching the latest version...
Read more