How to Add and Update Git Submodules

A Submodule is a Git Repository that is a subdirectory of another Git Repository. This Git Repository is called the parent of the Submodule. A lot of times the main project will need code from some other external repository or library. We can simply copy and paste the code needed from this external repository into our main project. But this approach is not the most efficient one. Let's learn more about Submodules and how to use them in Git.

Submodule

A Submodule is a Git Repository inside another Git Repository. This embedded Git Repository can be managed independently and will have its own Git workflow. We can also use this embedded repository as a Submodule for various other repositories without creating new files from scratch for each repository.

Why are Submodules Used?

• Submodules are mostly used when we are working on a large-scale project that has a lot of different components. Some of these components may be complex enough that we need a separate Git Repository to manage them along with using them in our main project.
• We also use the concept of submodules when using external libraries for our project.
• We can always copy and paste the code between the two projects but doing this makes it very difficult to understand the project and manage the commit history. The commit history will include commits for the main project along with the code that we have pasted.
• Another issue is that the copied project or library may change over time and we have to constantly download the new code files and update our main project to make sure that everything runs smoothly.
• This is the reason why submodules are used. We can make changes to the submodule without affecting the main project. Submodules also help us to use external libraries that we want to modify and use for our main project.

Git Submodule Commands

Now that we know what Submodules are and what they are used for, let's look at how to create and use submodules in Git.

Adding a Submodule

To add a submodule we use the Git Submodule Add command. We need to pass the remote repository URL where the project that we want to embed is hosted. It is a good idea to first create a separate subdirectory in your repository and then add all the submodules to that subdirectory.

$ mkdir <subdirectory-name>

$ git submodule add <remote-repo-url> <subdirectory-name>

Alternatively, we can first navigate to the destination folder and then run the above command without adding the subdirectory name.

After running the above command Git will first start cloning the remote repository.

A hidden file is created with the name of .gitmodules in the parent repository. This is the file where Git will keep track of all our submodules.

Also, our Git configurations are altered to add the new submodule.

Cloning a Repository with Submodules

When we clone a repository Git will not download any of the submodules of that repository. There are two ways to tell Git that we also want it to clone the submodules.

We can use --recurse-submodules option with the Git Clone command to also clone the submodules.

$ git clone --recurse-submodules <remote-repo-url>

Or we can use the Git Submodule Update command with the --init and the --recursive command after cloning the repository using the Git Clone command.

$ git submodule update --init --recursive

Updating a Submodule

A repository that we are using as a submodule may be maintained by some other team of developers and they may make changes to this remote repository. To update our version of the submodule we use the Git Submodule Update command with the --remote and --merge options. We need to run this option

$ git submodule update --remote --merge

The above command fetches and merges the new commits into the submodule. To just fetch the new commits we can simply navigate to the submodule and run the Git Fetch command. If after examining the commits we want to merge them then we can use the Git Merge command.

Removing a Submodule

We may need to remove an unwanted submodule. This can be done by using the Git Submodule Deinit command. This will safely remove the submodule from all the configuration files. Then we can simply delete the submodule by using the Git Rm command.

$ git submodule deinit <submodule-name>

$ git rm <submodule-name>

Summary

Submodules are very useful when our project increases in size and we need separate repositories for different components of our project. It is also very helpful when we have to use some external libraries for our project. Instead of copying files and pasting them all into a single repository we can better maintain and manage our repository by using submodules. The Git Submodule command can be used to add and update submodules.