Git Submodule Guide & Basic Commands to Get Started

September 1, 2022


When developing an application using Git, it is practical to integrate code available in other repositories. Reusing the code shortens development time and conserves resources.

Copying repository contents directly into the project is an adequate solution in some scenarios. However, merging customizations with future upstream changes can be challenging. Submodules are a Git feature designed to address this issue.

This guide will show you how to work with Git submodules and provide a list of the most frequently used commands and their options.

Git submodule guide and basic commands to get started.


What is Git Submodule?

A Git submodule is a feature that allows the integration of multiple independent repositories into a single project. A submodule acts as a subdirectory within the main project directory, but the code it contains does not have to be copied directly into the project.

Instead, Git creates a reference to the submodule's repository and places it inside the main project's repository. The image below shows a submodule in a repository hosted on GitHub.

An example repository in GitHub, containing a directory and a submodule.

Why Use Git Submodules?

Git submodules are helpful when working with complex projects. For example, developers of microservice-based apps can design and update each microservice separately to preserve independent change histories.

Another benefit is that multiple projects can share the code maintained in a single repository. This way, developers ensure consistency between various products using the same feature.

Basic Git Submodule Commands

The Git command-line interface has a dedicated subcommand for manipulating submodules. Use git submodule to create, update, and manage submodules.

The sections below list the most common git submodule commands and their options.

git submodule add

Add a submodule to your main repository using the git submodule add command.

To do so:

1. Go to the main directory of your project:

cd [main-project-directory]

2. Provide the URL of the submodule's origin repository to the add command:

git submodule add [submodule-repository-url]

The output shows Git cloning the repository into the project's subdirectory.

Adding a Git submodule.

To specify the path and name of the directory containing the submodule, add the path argument to the command:

git submodule add [submodule-repository-url] [path]

The following example clones the repository new-submodule into the submodules/example path:

git submodule add submodules/example

If you do not specify a path, Git defaults to the repository name.

Note: Use the -b option to specify a non-default branch for the submodule.

git submodule init

When cloning the repositories that contain submodules, you must initialize the submodules with the git submodule init command:

git submodule init

The command registers the paths to submodules within the project tree.

Initializing a submodule in Git.

To initialize a specific submodule, add its path to the command:

git submodule init [path]

git submodule update

Update the state of the submodules in the project with the following command:

git submodule update

The command clones the missing submodules, fetches any new remote commits, and updates the directory tree.

Updating a submodule in Git.

Adding the --init flag to the command eliminates the need to run git submodule init. The --recursive option tells Git to check the submodules for nested submodules and update them as well.

git submodule status

Check the status of the submodules by typing:

git submodule status 

The command prints out the SHA-1 and the path of each submodule.

Checking the status of the submodules in Git.

The SHA-1 string can have three different prefixes.

  • The - prefix marks an uninitialized submodule.
  • The + sign shows that the checked-out submodule commit differs from the state of the original submodule repository.
  • The U prefix alerts to merge conflicts.

Note: No prefix means that the submodule is initialized, synchronized with the origin, and has no conflicts.

Use the --recursive option to include nested submodules in the status report.

git submodule foreach

The git submodule foreach command allows executing a command on each submodule. Use the following syntax:

git submodule foreach '[command]'

For example, to perform the fetch action on each submodule, type:

git submodule foreach 'git fetch'

The example output shows Git checking submodules and fetching new data for the test-submodule.

Performing the git fetch command on all submodules using the git submodule foreach command.

git submodule deinit

Unregister a submodule by typing the following command:

git submodule deinit [path]

Git removes the content of the submodule directory and deletes the section of the .git/config file relevant to the submodule.

De-registering a submodule in Git.

De-initialize a submodule containing local modifications by adding the --force option:

git submodule deinit [path] --force

Working with Git Submodules

In projects that utilize submodules, the workflow must include submodule management. The sections below deal with the most common submodule operations, such as:

  • Creating submodules from subdirectories.
  • Pulling changes from submodule and project remotes.
  • Merging and publishing submodule changes.
  • Using aliases.

Joining a Project Using Submodules

If a project contains submodules, follow the steps below to obtain a full local copy:

1. Clone the repository:

git clone [repository]

The output of the git clone command confirms the successful cloning.

Cloning a repository containing submodules.

The directory with the cloned repository contains all the files and subdirectories of the original repository. However, the submodule directories are created empty and uninitialized.

2. Initialize the submodules and clone their contents by typing:

git submodule update --init --recursive

Git registers the submodules, clones the related files, and checks out the path of each submodule.

Updating submodules in a project.

Alternatively, perform all the above actions using a single command by adding the --recursive flag to git clone.

git clone --recursive [repository-url]

Switching From Subdirectories to Submodules

If you start using submodules in a project that is already in progress, subdirectories containing the relevant code need to be turned into submodules. The simplest way to perform this switch is using the procedure below.

1. Recursively copy the contents of the entire project directory to a new location:

cp -r [existing-directory] [new-directory]

2. Go to the new directory and execute the git filter-branch command. Use the --subdirectory-filter option and provide the name of the subdirectory containing files for the new submodule.

git filter-branch --subdirectory-filter [subdirectory] -- --all

The example below uses git filter-branch to remove everything except the contents of the test-dir directory.

The git filter-branch command output.

3. Create an empty repository to store the new submodule and copy the URL. If you use GitHub, read how to create a new repository on GitHub.

4. On the local system, set the new remote origin for the submodule repository:

git remote set-url origin [submodule-repository-url]

5. Push the changes to remote.

git push

The contents of the submodule directory are uploaded to the repository you created.

Pushing the directory contents to a new repository.

6. Return to the main project's directory and remove the subdirectory containing the code that now belongs to the new submodule.

git rm -r [subdirectory]

7. Commit the changes with:

git commit -m "[message]"

8. Push the changes to remote.

git push

9. Use the git submodule add command to add the submodule to the project.

git submodule add [new-repository]

Pulling Changes From the Submodule Remote

A frequent usage scenario for submodules is utilizing their code without changing it locally. In this case, updating submodules with new content from their remote origin is performed with the following command:

git submodule update --recursive --remote

The output shows the submodule's remote origin and confirms the successful update.

Updating submodules using the remote flag.

Note: For more details on pulling the latest submodule version, read How to Pull the Latest Git Submodule. And to learn about obtaining repositories containing submodules, refer to our guide on Git submodule checkout.

Pulling Changes from the Project Remote

If a submodule is changed as a part of the superproject's commit, pull the changes by following the procedure below:

1. Execute git pull:

git pull [remote-repository] [branch-name]

2. Update the submodules.

git submodule update --init --recursive

The --init flag in the command above is important in case new submodules have been created in the remote commit.

Publishing Submodule Changes

Changes made on a submodule locally are published similarly to any other repository changes in Git. The only difference is that the command execution takes place in the submodule directory.

To publish the changes:

1. Go to the directory containing the submodule.

cd [submodule-path]

2. Use git add to choose which files to commit.

git add [filename]

3. Commit the changes.

git commit -m "[message]"

4. Push the changes to remote.

git push

Merging Submodule Changes

To merge upstream changes to submodules with the local versions, type:

git submodule update --remote --merge
Merging submodule changes using the merge flag.

To merge the main project's gitlink changes into the submodules, type:

git submodule update --merge

Using Aliases

Most of the commands related to submodule management in Git are long. To simplify frequently performed actions, create aliases for the commonly used commands.

The syntax for creating an alias is as follows:

git config --global alias.[new-alias] '[original-command]'

For example, to create the sub-update alias which replaces the submodule update --recursive --remote command, type:

git config --global alias.sub-update 'submodule update --recursive --remote'

Test the new command alias on your system:

git sub-update

The output of the alias is the same as the output of the original command.

Using a Git alias to replace the submodule update command.

Submodules and Branch Switching

Switching to a new submodule branch in Git is performed using the git checkout command. Execute it from the submodule directory, adding the name of the branch you want to switch to:

git checkout [branch]

The output confirms that the new branch is checked out.

Switching branches in submodules using the git checkout command.

If you are checking out a new branch for the entire project, add the --recurse-submodules flag to properly transfer the state of submodules.

Note: With older Git versions that do not support the --recurse-submodules option, use the git submodule update --init --recursive command to restore the state of submodules after the checkout.


This guide aimed to provide a simple overview of Git submodules, focusing on the most frequently used commands and workflows.

If you need a comprehensive general introduction to Git, read our beginner's guide to Git.

Was this article helpful?
Marko Aleksic
Marko Aleksić is a Technical Writer at phoenixNAP. His innate curiosity regarding all things IT, combined with over a decade long background in writing, teaching and working in IT-related fields, led him to technical writing, where he has an opportunity to employ his skills and make technology less daunting to everyone.
Next you should read
How To Pull The Latest Git Submodule
August 17, 2022

This tutorial will show you how to pull the latest Git submodule to your local machine and Fix the "Fatal: Needed a Single Revision" error.
Read more
How to Use Git {Beginner's Guide}
September 2, 2021

Git is the world's most popular version control system (VCS), and, consequently, knowing how to use Git has become a mandatory skill in the world of coding.
Read more
How Does Git Work?
September 16, 2021

Having a good understanding of Git is essential if you want to code and work on a collaborative software development project. In this article, you will learn how Git works and how to use its crucial functions.
Read more
Working with Git Bash Commands
September 8, 2021

Git Bash is an application for Microsoft Windows, allowing developers to use Git in a command-line interface. In this article, you will learn what Git Bash is and how to use it.
Read more
  • © 2022 Copyright phoenixNAP | Global IT Services. All Rights Reserved.