JIYIK CN >

In this article, we will discuss Git submodules. We will cover what they are, the purpose of submodules, and the general workflow.

Git submodules allow us to keep one repo as a subdirectory of another repo. In short, a submodule is a reference to another repository within a specific time frame.

What are Git submodules?

If the above explanation didn't make things clear, this one should.

A Git submodule can be likened to a record in the host repository that refers to a commit in another repository. Typically, submodules are static and track a specified commit.

They do not track branches or refs, and are not updated when changes are pushed to the host repository.

Every time we create a submodule in our repo, Git creates a .gitmodulesfile. This file contains metadata about the submodule and a mapping to our repo.

Creating multiple submodules will result in multiple gitmodules.

Creating a Git submodule

The first question we must ask ourselves is when should we create a submodule?

Here are some scenarios where it's best to create Git submodules.

1. When subprojects or external components are changing rapidly, it is best to lock your code to a specific commit. The same applies if you anticipate upcoming changes that may break your API.
2. When a component is tracked as a vendor dependency. This usually happens when we don't update a particular component regularly.
3. When we want to integrate changes from a third party at a specific time. It works best when you don't have frequent updates.

Common Git commands for submodules

Let's look at some common usage options on the command line.

Adding Git submodules

We git add submodulecreate a new submodule in our host repository using the command. This is the typical workflow when creating a Git submodule.

$ git submodule add <Repo URL>

git submodule addThe command requires a URL argument pointing to a repo. Git will clone the submodule and we can run git statusthe command to see the new repo status.

Let's look at an example. Let's add a submodule to our Delftscopetechrepository.

We can now run git statusthe command as shown below.

$ git status

As shown above, we now have two new files, , .gitmodulesand Learn-Submodules. We can add the files and commit the changes.

git submodule init

We run git submodule initthe command to copy the submodule's mapping from .gitmodulesthe ./configure file to our local configuration file. It will appear when we have more than one submodule in our repository.

Listing submodules in Git

git submodule initThe command depends on .gitmodulesthe file. We can see a list of all submodules by depending on the same file.

First, we need to parse the file. We run:

$ git config --file .gitmodules --name-only --get-regexp path

Then we can run:

$ git config --file .gitmodules --get-regexp path | awk '{ print $2 }'

The above command will display the path of the submodules present in the repository.