What Are Git Submodules, and How Do You Use Them?

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 can 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 run git submodule add:

git submodule add URL submodule_directory

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

However, if you want to convert an existing folder, the process is a bit more complicated. You can read 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.

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.

git commit -m “Added submodule submodule_directory”

Updating Git Submodules

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

git submodule update –remote

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:

Make the changes in a separate repository for the submodule, and commit and update them as normal. You will need to run git submodule update in the parent repository to pull the new changes.
Make the changes inside the parent repository. Since a submodule is basically an embedded Git repository, you’re able to cd into the submodule directory and run Git commands as normal. This is one of the main benefits of submodules, as you can maintain separate repos while working on both at the same time.

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

cd submodule_dir
git commit -am “submodule commit”
git push

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

cd ..
git commit -am “updated submodule”

git push

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

>>> Read full article>>>
Copyright for syndicated content belongs to the linked Source : How To Geek – https://www.howtogeek.com/devops/what-are-git-submodules-and-how-do-you-use-them/