Git Submodules Integration (Basic Guide)
Git Submodule is like a subdirectory inside another directory allowing to reuse some shared modules and dependencies. Learn how to initialize, add, update and remove git submodules step by step.
A git submodule is a mechanism which allows you to add a repository inside another git repository. This mechanism is useful when you want to use a module from another project. This is also useful when you have a module in a different repository and it is used in several other repositories while maintaining a separate history of its own. In this post we will understand how to initialize and add a git submodule, how to update a git submodule and how to remove a git submodule step by step.
How to Initialize, Add, Update and Remove Git Submodules
It is important to understand the working flow of git submodule. So first thing is we need to initialize git submodules which creates a .gitmodules file. This file contains the definition of submodules like the URL to git repository and local path to module directory. Then the important thing to remember is:
- Make sure the changes in submodule are always pushed to its own repository.
- Make sure the main repository is always has the updated submodule.
We are going to cover all basics steps involved in git submodule integration. Starting with initializing submodules.
How to Add Git Submodule
First step
to add git submodule to run a command that will add submodule.
The following command will create a file .gitmodules if it does not exit or update it if it already exists. This file contains the
module definition.
git submodule add https://github.com/username/repository-name.git path-to-submodule-directory/
Where username is the username of our github account and directory is the name of directory in which we want to clone this submodule. This command will create the file .gitmodules which will contain content similar to following:
[submodule "assets"]
path = assets
url = [email protected]:username/repository-name.git
branch = master
After adding the git submodule we need to commit these changes using the following command:
git add .
git commit -m "Add submodule from github"
How to Initialize Git Submodule
So far the git submodule is added locally but our repository configuration is not aware of it. So we need to initialize submodules using the following command:
git submodule init
This command will clone the information of submodule from .gitmodules file and register them in .git/config folder.
How to Update Git Submodule
So far at this point the git submodule is properly added and initialized but it does not contain any content yet. To populate the content of submodule we need to run the following command:
git submodule update
This command will update the submodule to correct commit. The update can also be used with certain flags which will update all submodules including nested ones and initialize them at same time. This command will pull the latest commit of submodule from remote tracking branch.
git submodule update --init --recursive --remote
How to Remove Git Submodule
If we want to remove a submodule from main repository we can do so using the following command in our main repository:
git submodule deinit path-to-submodule-directory/
After removing the submodule we might need to initialize the submodule again to update main repository's configuration.
How to Clone a Repository with Submodules
When cloning a repository that contains submodules, make sure to use --recurse-submodules flag in clone command. Command to clone a repository with its submodules is as following:
git clone --recurse-submodules https://github.com/username/repository-name.git
Important things to note, we can use github repository as submodule of bitbucket repository and vice versa. However we might face issues related to authentication when pushing changes to remote git server, To solve this issue make sure we have added user credentials and we might need to change the git URL of either of repository.