Git Submodules - What, how and more

Git Submodules - What, how and more

Understanding git submodules and its usage

What are Git Submodules?

Git Submodules are a way to include the contents of one Git repository within another Git repository. They allow you to keep a Git repository as a subdirectory of another Git repository, while still maintaining its separate history and version control.

When do we use it?

There are several reasons why you might want to use Git submodules:

  • To include external libraries or dependencies in your project.

  • To collaborate with other developers on a project that depends on a separate component.

  • To share code between multiple projects.

  • To keep your project's dependencies separate from the main codebase, or to use a specific version of a dependency that is not the latest release.

How does it work?

Here's how Git submodules work:

  1. When you create a submodule, you specify the URL of the external repository that you want to include in your project.

  2. Git stores the submodule as a reference to a specific commit in the external repository.

  3. When you clone your repository, Git also clones the submodule and checks out the specified commit.

  4. If you make changes to the submodule and commit them, Git records the new commit in your parent repository.

Working example

1. Adding a submodule

To use a submodule in your repository, you need to first add it using the git submodule command. For example, to add a submodule named lib located at, you would use the following command:

git submodule add <> lib

This will create a new directory in your repository called lib, and initialize it as a Git repository. It will also add a new entry to your repository's .gitmodules file, which records the URL of the submodule and its local path.

2. Joining a project using submodules

Once you have added a submodule to your repository, you can update it to the latest commit by using the git submodule update command. This will fetch the latest changes from the upstream repository and update the submodule's reference to the new commit.

If you want to make changes to a submodule, you can do so by checking out a branch and committing your changes as you would with any other repository. However, you will need to push your changes to the upstream repository separately, and then update the reference in the parent repository using git submodule update.

Using submodules can be a convenient way to manage external dependencies in your Git repository, but it's important to understand how they work and how to use them effectively. In particular, you should be aware that submodules are only updated when you explicitly run git submodule update, so it's important to stay on top of updates to ensure that your project is using the latest version of its dependencies.

Pros and cons

Using Git submodules has some advantages and disadvantages compared to other approaches for managing external dependencies. Some advantages include:

  • Git submodules are version controlled, so you can track changes to the external repository over time.

  • Git submodules are easy to set up and use.

  • Git submodules allow you to keep your repository lightweight since you only need to include the submodule reference, not the entire external repository.

However, there are also some disadvantages to using Git submodules:

  • Git submodules can be confusing for new users.

  • Git submodules can be difficult to update.

  • Git submodules can make it harder to merge changes between branches.


  1. Git official documentation

    Git - Submodules

  2. The GitHub Blog

    Working with submodules | The GitHub Blog

  3. Git Submodules Tutorial


In general, Git submodules are a useful tool for managing external dependencies in your projects. However, it's important to weigh the advantages and disadvantages before deciding to use them in your work.