The other day, I was working on a project that had a Git submodule. Initially, I found it a bit tricky to make it work, so I decided to create a short tutorial on this.

What is a Git submodule#

Essentially, a Git submodule is a way to include one Git repository inside another Git repository. This creates a nested structure.

So, in simple words, a Git submodule is like a mini Git repository that you can include in your main Git repository to use and update external code or resources without actually putting all of their files directly in your project.

The crucial point to note is that, by default, the code of the submodule is not added to your Git repository when performing the initial git clone.

How to check the ulr of the git submodule#

To check the linked URLs of submodules we can use this command.

git config --file .gitmodules --get-regexp 'submodule\..*\.url'

How to clone a submodule#

There could be three situations:

  1. You want to clone the git project with all its submodules for the first time.
  2. You’ve cloned the git project but didn’t fetch the submodules.
  3. You want to update the submodules in your project.

Cloning a project with all submodules for the first time#

If you want to clone a project for the first time with all its submodules, you can run the following command.

With Git version 2.13 or newer.

git clone --recurse-submodules -j8 https://github.com/your/repo.git

-j8 is an optional performance optimization that became available in version 2.8, and fetches up to 8 submodules at a time in parallel

Before Git 2.12.

git clone --recursive https://github.com/your/repo.git

Cloning the submodules only#

If you’ve downloaded the project but forgot to fetch the submodules, you can use this command.

git submodule update --init --recursive

If you’ve cloned only the main Git repository, you’ll be missing the submodule files, potentially causing your project to fail.

Updating the submodules#

If you want to update the code of the submodules, you need to run this command.

git submodule update --recursive --remote

This will only update the branch registered in the .gitmodule, and by default, you will end up with a detached HEAD, unless –rebase or –merge is specified or the key submodule.$name.update is set to rebase, merge or none.

Adding a submodule to a git repository#

To add another remote Git repository as a submodule to your current Git repository, you can use this command.

git submodule add https://github.com/your/repo.git path/to_save/in_repo

The provided code allows you to specify the remote URL for the repository you want to use as a submodule, as well as the path within your project where you want to save the cloned code.

Delete a Git submodule from your project#

This process is common but not that straightforward, here are the steps you need to do.

The files mentioned in the following steps are located in the root directory of your project, which is the default location for the Git files.

  1. Delete the relevant line from the .gitmodules file.
  2. Delete the relevant section from .git/config.
  3. Run git rm --cached path_to_submodule (no trailing slash).
  4. Commit and delete the now untracked submodule files.

A trailing slash is the slash that can be added to the end of the path. submodules/my_submodule/ has a trailing slash while submodules/my_submodule doesn’t have one.

Conclusion#

Git submodules are a powerful feature for managing dependencies in your projects. They allow you to include external Git repositories within your main repository without cluttering it with their files. This can be especially handy when you’re working on projects that rely on external code or resources.

We’ve covered some essential aspects of working with Git submodules in this tutorial. You’ve learned what a Git submodule is and how to check the URLs of linked submodules. You also know how to clone a project with all its submodules, how to retrieve submodules if you’ve forgotten them, and how to keep them updated. Furthermore, we discussed adding and deleting a submodule from your Git repository.

With this knowledge, you’ll be better equipped to manage complex projects with Git submodules and streamline your workflow. So, don’t shy away from using them in your projects when they can help you manage external code more efficiently.

Happy coding 🚀!