Git Submodules: A Guide

How to Use Git Submodules

As a Git repository grows in size, you’ll probably find yourself depending on other repositories. A blog project may depend on another repository that stores the code for a particular theme. A software project may depend on a particular, in-house version of a framework.

How do you connect these repositories together? That’s where submodules come in handy.

In this tutorial, we’re going to talk about what submodules are and why they are useful. We’ll walk through a few examples of how to set up a repository with submodules to help you get started.

What is a Submodule?

A submodule is a link to a repository within a Git repository. It makes it easy to connect different repositories together which depend on each other.

Submodules are a good way to link plugins and themes into your code. The links created by submodules will make it easier to navigate around your codebase.

They’re not a perfect fit for every project. Before you create a submodule, you should ask whether there is a better alternative available. Dependency management projects like npm and rubygems may be more convenient to use. This is because they are easy to configure and have extensive, language-specific management tools.

Submodules are not downloaded to a repository by default. We’ll talk about this later on.

How to Create a Submodule

We’re going to use submodules to create a link between Career Karma’s Git repositories. The repository we create will have a link to all of our other tutorials.

The repository we are going to create our submodule in is called git-submodules.

First, we’ll need to navigate into our repository. We’re going to create a submodule that references a repository called web-tutorials. Adding a submodule is accomplished using the submodule add method:

git submodule add https://github.com/Career-Karma-Tutorials/web-tutorials web

This command creates a folder called “web” inside the git-submodules repository. Let’s take a look inside our repository using the ls command:

We now have a link to our web-tutorials repository. Now that we have created this link, we can add it to our remote repository using git add and git commit:

git add web/
git commit -m "feat: Create submodule Career-Karma-Tutorials/web-tutorials"
git push

This code will commit our “web” folder to our remote repository.

Our repository is associated with GitHub. The GitHub platform has a nice feature which adds in a link to the repository associated with a submodule:

Our submodule has been successfully created! When you click on the link in GitHub, it will take you to the web-tutorials repository to which our submodule points.

Any command that we execute inside the “web” folder will affect the web-tutorials repository. This is because a submodule is just like a version of a repository inside a repository.

How to Clone a Project with Submodules

If you use git clone on a repository with submodules, you would get a copy of everything inside a repository except the submodules. There would be no code inside any submodule folder.

This is because submodules are not downloaded by default. There are two ways to retrieve the contents of a submodule and download them to your local machine.

You can download the contents of submodules by specifying the –recursive flag in your git clone statement:

git clone https://github.com/Career-Karma-Tutorials/git-submodules

Cloning is the most convenient method of retrieving submodules. If you have already cloned a project and want to download its submodules, you can use this command:

git submodule update --remote --recursive

The git submodule update command will fetch all the submodules from a repository that is already on your local machine.

How to Update a Submodule

Any changes you make to the parent repository to which a submodule links will not be reflected in your main repository. This is because submodules are linked to a particular commit.

You can update the local version of a submodule like you would with any Git repository. Let’s update our “web” submodule:

cd web
git fetch
git merge origin/master

This will fetch the branch “master” on the origin associated with the “web” submodule. 

If you want to update multiple submodules, you can use the submodule update command. This will retrieve the latest commit in all the repositories listed as a submodule in a project:

git submodule update --remote --recursive

Delete a Submodule

There are three steps you need to take to delete a submodule.

You should start by removing a reference to a submodule from your repository:

"Career Karma entered my life when I needed it most and quickly helped me match with a bootcamp. Two months after graduating, I found my dream job that aligned with my values and goals in life!"

Venus, Software Engineer at Rockbot

Find Your Bootcamp Match

git submodule deinit web

“web” is the path of the submodule that we are going to remove. Next, we need to remove it from our Git repository by running git rm:

git rm web/
git commit -m "feat: Remove web submodule"
git push

This removes the “web” submodule directory from our code.

We’re not done just yet. We need to remove the hidden reference to our submodule which exists inside the .git folder in the root directory of our project:

rm -rf .git/modules/web/*

This will remove all the remaining traces of our submodule.

How to View the Status of a Submodule

Submodules are references to a Git repository. This means that you can find out what files have been modified since the last commit. We can do this using the git status command.

First, we’ve got a bit of configuring to do. We need to enable a config option called status.submodulesummary. This will include any changes you have made to submodules inside the output of the git status command. Let’s enable this option:

git config status.submodulesummary

Now that we’ve configured this option, we can use git status to view the status of our entire repository, including its submodules:

git status

Here’s what this command returns when no changes have been made to a repository:

On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

Conclusion

Submodules are links to a Git repository within a repository. They make it easy to create a connection between multiple projects that depend on one another.

Here’s a quick cheat sheet that you can use to help you work with submodules:

• git add submodule: Adds a submodule to a repository
• git update submodule –remote: Updates the submodules in a repository.
• git submodule deinit: Removes a submodule from a repository.

Now you’re ready to start working with Git submodules like an expert developer!