How to Add a Submodule in Git

While working in Git, it is often necessary to use submodules. They allow tracking changes in several repositories via a single repository.

A submodule is considered a record inside a host repository. It points to a particular commit within another external repository.

Steps to Adding a submodule

Here, we will outline the main commands used for adding a submodule to your host repository.

Create an empty repository

Let’s start at creating an empty repository.

The command below creates an empty repository, then explores the submodules.

mkdir git-submodule-demo
cd git-submodule-demo/
git init

  Initialized empty Git repository in /Users/example/git-submodule-demo/.git/

Add a submodule to an empty repository

You should run the git submodule add command for adding a submodule to the newly generated repository:

git submodule add https://bitbucket.org/jaredw/awesomelibrary
Cloning into '/Users/atlassian/git-submodule-demo/awesomelibrary'...
remote: Counting objects: 8, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 8 (delta 1), reused 0 (delta 0)
Unpacking objects: 100% (8/8), done.

The git submodule add command is capable of taking a URL parameter, which points to the repository.

So, now, as a submodule, we have awesomelibrary. It will be cloned by Git at once.

Review the state of the repository

For reviewing the state of the repository, you should run the git status command:

git status
On branch master
No commits yet
Changes to be committed:
(use "git rm --cached <file>..." to unstage)
new file:   .gitmodules
new file:   awesomelibrary

It will show two new files in the repository: the awesomelibrary and .gitmodules.

The content of .gitmodules will demonstrate the mapping of the new submodule:

[submodule "awesomelibrary"]
path = awesomelibrary
url = https://bitbucket.org/jaredw/awesomelibrary

Commit the changes to the repository

Finally, you can commit your changes to the host repository by running the git add and git commit commands in the following way:

git add .gitmodules awesomelibrary/
git commit -m "added submodule"
[master (root-commit) d5002d0] added submodule
 2 files changed, 4 insertions(+)
 create mode 100644 .gitmodules
 create mode 160000 awesomelibrary

What is a Submodule

Very often, the code repository depends on the external code from other repositories. You can directly copy and paste the external code into the main repository, or you can use the method of language's package management system. But these two methods have the downside of not tracking changes to the external repository. Git allows including other git repositories called submodules into a single repository. Submodules allow tracking changes in several repositories via one repository. Submodules are repositories included in the parent repository at a specific path in the working directory of the parent repository. They can be located anywhere in the working directory and are configured via the .gitmodules file, which is located at the root of the parent repository. The .gitmodules file contains metadata about the mapping between the submodule project's URL and local directory. Submodule supports adding, synchronizing, updating, and cloning submodules. Submodules track only specific commits, not the git references and branches.