Git Submodules Integration (Basic Guide)
Git Submodule is like a subdirectory inside another directory, allowing the reuse of some shared modules and dependencies. Learn how to initialize, add, update and remove git submodules step by step.
A git submodule is a mechanism that 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 submodules. So, the 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 the git repository and the local path to the module directory. Then the important thing to remember is:
- Make sure the changes in the submodule are always pushed to its own repository.
- Make sure the main repository 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 a Git Submodule
First step is to add a git submodule by running a command that will add a submodule.
The following command will create a file .gitmodules if it does not exists 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 the directory in which we want to clone this submodule. This command will create the file .gitmodules, which will contain content similar to the 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 has been 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 the submodule from the .gitmodules file and register it in the .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 the submodule, we need to run the following command:
git submodule update
This command will update the submodule to the latest commit. The update can also be used with certain flags, which will update all submodules, including nested ones and initialize them at the same time. This command will pull the latest commit of the submodule from the remote tracking branch.
git submodule update --init --recursive --remote
How to Remove Git Submodule
If we want to remove a submodule from the 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 the main repository's configuration.
How to Clone a Repository with Submodules
When cloning a repository that contains submodules, make sure to use the --recurse-submodules flag in the clone command. Command to clone a repository with its submodules is as follows:
git clone --recurse-submodules https://github.com/username/repository-name.git
Important things to note: we can use a github repository as a submodule of a bitbucket repository and vice versa. However, we might face issues related to authentication when pushing changes to a 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 the repositories.