What is a GIT submodule and what's the best way to work with them?

This blog is written by Akshat Virmani at KushoAI. We're building the fastest way to test your APIs. It's completely free and you can sign up here.

When working with large organizations or multiple repositories, leveraging or depending on different repositories is very common. Working with them on the individual level can be tricky and time-consuming. That’s why the GIT submodule was introduced to solve all these problems. It allows you to work with different repositories while keeping them separate but connected.

What is a GIT Submodule?

A Git submodule allows you to include a repository inside another repository. It’s particularly useful when you want to reuse or depend on the external code of multiple projects. Instead of copying code into your project, a GIT submodule links to the original repository, allowing you to pull updates when necessary.

Why use the GIT submodule?

Some of the scenarios where the GIT submodule does wonders:

1. Shared Libraries: If multiple projects depend on a shared library, a submodule ensures consistency by linking to the library's repository.

2. Third-Party Code: Submodules allow you to easily manage and update external tools or frameworks if you need to integrate them into your project.

3. Flexibility: Submodules can be updated independently of the main project, allowing you to use different dependency versions in different environments or situations.

4. Reusability: Submodules allow you to reuse the same external code across multiple projects, reducing duplication and increasing maintainability.

How to Work with Git Submodules

Below is a visual representation of a submodule in a repository. The ‘->’ logo represents the submodule, as seen in the ‘client’.

Here’s a step-by-step guide to using Git submodules:

1. Adding a Submodule

To clone the external repository into a folder inside your project and add it as a submodule, use the following command:

git submodule add <repository-url>

2. Cloning a Repository with Submodules

If you’re cloning a repository that already contains submodules, you’ll need to initialize them after cloning, This ensures the submodules are pulled and properly linked:

git clone <repository-url>

cd <repository-folder>

git submodule init

git submodule update

3. Updating a Submodule

Submodules don’t update automatically. To pull the latest changes from a submodule, use:

cd <submodule-directory>

git pull origin <branch>

You can then commit the updated submodule reference in your main repository.

4. Removing a Submodule

To remove a submodule, follow these steps:

• Delete the relevant line from the .gitmodules file.

• Run git rm --cached <submodule-directory>.

• Commit the change, then remove the directory and update your repository.

5. Working with Multiple Submodules

To update all submodules at once, use:

git submodule update --remote --merge

Conclusion

Git submodules are a powerful feature for managing dependencies between multiple repositories. While they require additional steps compared to simply copying files, they offer the flexibility to track and manage external code efficiently. Git submodules provide an organized and controlled way to integrate external repositories into your workflow.

This blog is written by Akshat Virmani at KushoAI. We're building an AI agent that tests your APIs for you. Bring in API information and watch KushoAI turn it into fully functional and exhaustive test suites in minutes.