Git submodules are a way of including one Git repository as a subdirectory of another repository. This kind of source code nesting can be very useful for projects that want finer control over their dependencies and build process, and it’s easy to set up.

Why Use Submodules?

When you add a submodule to a Git repository, you’re essentially creating a link between the two repositories. The main repository and the submodule repository can be updated independently of one another. The parent repository will contain a remote URL as well as a reference to the checked-out commit ID in the submodule’s history. When you clone the parent repository, it will clone the submodules as well.

This can be useful if you have a project that depends on code from another project, and you want to keep the two projects (and their version histories) separate, but still be able to easily work with both of them.

The primary alternative to submodules is using package managers like NPM, NuGet, or Maven. Package managers provide a centralized repository of packages and libraries that can be easily installed and updated. However, you must publish a specific version of each package you want to consume. And if your code is private, you must use your own private package registry.

Git submodules allow you to manage dependencies more closely than most package managers. With submodules, you’re able to choose exactly which versions of each dependency you want to include in your project, and it’s easier to update the commit ID of the submodule than it is to publish a new package.

Submodules also make it easier to maintain and use forks of common libraries, which is something that many companies opt for when additional features or customization is necessary. Ultimately, if you’re maintaining a repository for the module, and need fine-grained control over your dependencies, you may want to consider using submodules instead of package managers.

How to Use Git Submodules

If you’re cloning a repository that already uses submodules, most of the work has been done for you already. Your git client should automatically clone and download the submodule repository, and it should update whenever other maintainers push changes to the submodule.

If it doesn’t, you may need to run git clone with the –recursive flag, which will scan and update all submodules.

git clone –recurse-submodules URL

Adding a new submodule is fairly straightforward. If you’re adding a brand new submodule from a source repository, you’ll just have to rungit submodule add:

This will download the submodule repository from the URL and clone it into thesubmodule_directoryfolder.

However, if you want to convert an existing folder, the process is a bit more complicated. You canread our guide to converting a directory into a submodule here, but the process involves cloning your main repo again, filtering the commit history to only include the module directory, and then pushing the submodule to a new repository.

Related:How to Turn a Turn a Directory in a Git Repository Into a Submodule

Once you add the submodule, you will need to commit the changes to the parent repository. This will update the configuration for everyone else that pulls the parent repository.

Updating Git Submodules

If someone else updated the submodule, or you need to pull updates from the submodule’s repository, you’ll want to usegit submodule update:

However, if you need to make changes yourself, it becomes a little trickier. Making changes to code in Git submodules requires a bit of extra care compared to updating code in a regular Git repository, and you generally have two options:

If you’re making changes inside the parent repository, you’ll need tocdinto the submodule and update:

Then, head back up to the parent repo and push the updates to the submodule to the parent’s repository:

You should see changes both on the submodule’s Github repository as well as the parent repository.