June 07, 2021

Git Submodules Integration

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.

Git Submodules Integration

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.


Initialize, Add, Update and Remove Git Submodules

It is important to understand the working flow of git submodule. So first thing is you need to initialize git submodules which creates a file .gitmodules. 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.

 

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 your github account and directory is the name of directory in which you want to clone this submodule. This command will create the file .gitmodules which will contain content similar to following:

[submodule "assets"]
	path = assets
	url = git@github.com:username/repository-name.git
	branch = master

After adding the gitsubmodule you need to commit these changes using the following command:

git add .
git commit -m "Add submodule from github"
 

Initialize Git Submodule

So far the git submodule is added locally but your 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.

 

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

Remove Git Submodule

If you want to remove a submodule from main repository you can do so using the following command in your main repository:

git submodule deinit path-to-submodule-directory/

After removing the submodule you might need to initialize the submodule again to update main repository's configuration. 

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, you can use github repository as submodule of bitbucket repository and vice versa. However you might face issues related to authentication when pushing changes to remote git server, To solve this issue make sure you have added user credentials and you might need to change the git URL of either of repository.

Home