One of the most powerful things that most developers hold high is efficiency on the resources and the development cycle.

When it comes to git, we encounter instances where we can intergrate code and reuse code from other repositories. However, it can be challenging attempting to merge code customizations with upstream changes. This is where git submodules come into play.

What is Git Submodule?

In git, a submodule is a feature that allows us to include a separate git repository within another Git repository as a single project.

Once incorporated, a submodule will act like a subdirectory within the main project but the the code of the subdule is not directly copied into the main repo.

By using submodulel, git will create a reference to the submodule's repository and place it inside the main repo.

An example of a git submodule is the tutanota repository. In the lib directory, you will find the webassembly repo which is a submodule.

Basic Git Submodule Commands

One of the most powerful things about git version control is the exceptional CLI tools that allow us to work with various features in the vcs.

In git, we can interact with submodules by using the git submodule commands. You can also use the git su bmodule to create, update, and manage submodules.

Let us explore some common git submodule commands and how to use them.

git submodule add

The first and most common command is the git submodule add command which allows us to add a submodule to given repository.

Start by navigating into the repo in which you wish to add the repository:

cd /path/to/repository

Next, use the git submodule add command followed by the URL of the submodule you wish to add. For example, suppose we want to include cpython in our repo, we can use the command:

git submodule add

This should clone the cpython repository and include it in the repository as shown in the output:

You can also specify the path and name of the directory in which you wish to store the submodule. The command syntax is as shown:

git submodule add [url] [path]

For example, suppose we wish to store the submodule in the /deps/py directory, we can run the command as shown:

git submodule add deps/py/cpython

By default, git will use the specified repository name.

git submodule init

The second command we will look at is the git submodule init command.

When we are cloning a repository that contains submodules, we must ensure to initalize the submodules using the git submodule init command.

git submodule init

To initalize a specific module, you can specify the submodule path as shown in the syntax below:

git submodule init [path]

git submodule update

The git submodule update command allows us to update the status of the submodules in a given repository. The comamnd syntax is as shown:

git submodule update

The command will clone the missing submodules, download any new commits, and updates the repo directory tree.

We can also add the --init flag to the update command to remove the need for running the git submodule init command.

Using the --recursive option also tells the command to check the submodules for any nested submodules and download them as well.

git submodule status

Next, we have the status command which allows us to find the status of a submodule. The command syntax is as shown:

git submodule status

An example:

The command should return a SHA-1 hash and the path of each submodule within the repository.

The SHA-1 string can have three different prefixes.

  • The - prefix marks an uninitialized submodule.
  • The + sign shows that the checked-out submodule commit differs from the state of the original submodule repository.
  • The U prefix alerts to merge conflicts.

NOTE: Having no prefix in the SHA-1 denotes that teh submodule is initialized, synced with origin, and no conflicts.

git submodule deinit

The git submodule deinit command allows us to unregister a submodule. The command synyax is as shown:

git submodule deinit [path]

Git will remove the content of the submodule directory and deletes the entry in .git/config file that pertains to the specified submodule.

You can also deregister a submodule that contains local changes by using the --force option.

git submodule deinit [path] --force

Ths will discard the changes from the submodule.

git submodule foreach

This command allows us to execute a command on each submodule. The command syntax is as shown:

git submodule foreach [command]

For exmaple, suppose we wish to run the command git fetch on each submodule, we can use the command:

git submodule foreach 'git fetch'



In this comprehensive guide, we learned about the git submodules and the commands that we can use to work with submodules in a given repository.

Great! Next, complete checkout for full access to GeekBits.
Welcome back! You've successfully signed in.
You've successfully subscribed to GeekBits.
Success! Your account is fully activated, you now have access to all content.
Success! Your billing info has been updated.
Your billing was not updated.