How to List Git Submodules in Git

1. What is a Git Submodule
2. Create a Git Submodule
3. Common Git Commands for Submodules
4. List Submodules in Git

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

Git submodules make it possible for us to keep one repo as a subdirectory of another repo. In simpler words, submodules are a reference to other repositories at certain time frames.

What is a Git Submodule

If the explanation above did not clear things up, this one should.

A Git submodule can be likened to a record in a host repo that references a commit in another repo. In general, submodules are static and track specified commits.

They do not track branches or refs and are not updated when changes are pushed into the host repo.

Git creates a .gitmodules file every time we create a submodule in our repo. The file contains the submodule’s metadata and mapping with our repo.

Creating multiple submodules will result in multiple gitmodules files.

Create a Git Submodule

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

Here are some scenarios when it is best to create a Git submodule.

1. When a subproject or external component changes rapidly, it is best to lock your code to a specific commit. The same applies if you anticipate upcoming changes that may break the API.
2. When tracking components as vendor dependencies. This usually happens when we are not updating a specific component regularly.
3. When we want to integrate changes from a third party at a specific time. It works best when you do not have frequent updates.

Common Git Commands for Submodules

Let’s look at some common usage options on our command line.

Add Git Submodule

We use the git add submodule command to create a new submodule in our host repository. Here is the typical workflow when creating Git submodules.

$ git submodule add <Repo URL>

The git submodule add command requires a URL parameter that points to a repo. Git will clone the submodule, and we can run the git status command to see the new repo state.

Let us look at an example. Let us add a submodule to our Delftscopetech repository.

We can now run the git status command as shown below.

$ git status

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

git submodule init

We run the git submodule init command to copy the mapping of our submodule from the .gitmodules file into our local config file. It comes in clutch when we have several submodules in our repository.

List Submodules in Git

The git submodule init command relies on the .gitmodules file. We can view a list of all submodules by relying on the same file.

First, we will 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 command above will display the path to the submodules present in your repository.