How to Add a Submodule in Git
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¶
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.