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.
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:
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:
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.