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 <kbd class="highlighted">submodule</kbd> 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 <kbd class="highlighted">submodule</kbd> 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 <kbd class="highlighted">submodules</kbd>.

git create an empty repo

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 <kbd class="highlighted">git submodule add</kbd> command for adding a <kbd class="highlighted">submodule</kbd> to the newly generated repository:

git add a new submodule

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 <kbd class="highlighted">git submodule add</kbd> command is capable of taking a <kbd class="highlighted">URL</kbd> parameter, which points to the repository.

So, now, as a <kbd class="highlighted">submodule</kbd>, we have <kbd class="highlighted">awesomelibrary</kbd>. It will be cloned by <kbd class="highlighted">Git</kbd> at once.

Review the state of the repository

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

git status the state of the repository

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 <kbd class="highlighted">awesomelibrary</kbd> and <kbd class="highlighted">.gitmodules</kbd>.

The content of <kbd class="highlighted">.gitmodules</kbd> will demonstrate the mapping of the new submodule:

map new git 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, git commit

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 <kbd class="highlighted">.gitmodules</kbd> file, which is located at the root of the parent repository. The <kbd class="highlighted">.gitmodules</kbd> 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.