How To Pull The Latest Git Submodule

August 17, 2022


Git submodules allow users to host multiple repositories as subdirectories of the main repository. With submodules, other Git sources can be used without copying their code into the main project tree.

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.

How to pull the latest Git submodule.


Pulling the Latest Git Submodule

When a user clones a Git repository that contains submodules, the submodules appear as directories in the project's tree. However, these directories are cloned empty and require further steps to become functional.

The following sections describe the procedure for setting up submodules locally and pulling the latest versions. Lastly, the tutorial helps you fix a common error that appears during the submodule update process.

Initialize a Submodule in Your Repository

Type the following command in the Git directory to initialize submodules and clone them into their path:

git submodule update --init

The output shows that the submodule is registered and checked out successfully.

Initializing a submodule.

If a project contains nested submodules, i.e., submodules within submodules, add the --recursive option to the previous command:

git submodule update --init --recursive

Note: To eliminate this step, add the --recurse-submodules option to the git clone command when cloning the repository:

git clone --recurse-submodules [repository-name]

Pull the Latest Submodule with git fetch and git merge

Use the git fetch and git merge commands to update the contents of a submodule directory to the latest version. To do so:

1. Go to the submodule directory you want to update:

cd [submodule-directory]

2. Use git fetch to see if the submodule has new updates:

git fetch

The output shows the latest remote commits.

Using git fetch to see the remote commits for a submodule.

3. Merge the remote changes with your local version:

git merge [submodule-branch]
Merging the remote commits with the local version.

Note: Learn how to pull all branches in Git using two methods.

Pull the Latest Submodule with git update

Using git fetch and git merge to update submodules can be time-consuming, especially if you work on a project with multiple submodules. The easier way to perform the action is using the git submodule update command.

For Git 1.8.2 and above, execute the command below in the project's main directory:

git submodule update --recursive --remote

The output shows that Git updated the submodule automatically:

Updating submodules automatically.

For Git 1.7.3 and above, use the following syntax:

git submodule update --recursive

Alternatively, execute the git pull command with the --recurse-submodules option:

git pull --recurse-submodules

Fix the "Fatal: Needed a Single Revision" Error

When performing the git submodule update command, the following error may appear:

Fatal: Needed a single revision
Unable to find current origin/master revision in submodule path '[submodule-name]'
Fatal, needed a single revision error in Git.

The error comes up if you do not use the master branch of the submodule in question. Fix it by editing the .gitmodules file in the project's main directory.

1. Open .gitmodules in a text editor:

nano .gitmodules

2. Add the submodule branch you are using to the configuration section of the submodule:

branch = [branch-name]
Editing the gitmodules file in Nano.

3. Save and exit the file, then run the git submodule update command again.

To make the same change for multiple submodules without directly editing the .gitmodules file, enter:

git submodule foreach 'git config -f .gitmodules submodule.${sm_path}.branch [branch-name]'

The output shows Git automatically editing the configuration file for each submodule.

Using the foreach statement to automatically update multiple submodules.

Note: Learn how to perform Git submodule checkout to obtain the contents of a submodule.


After reading this tutorial, you should know how to pull the latest versions of Git submodules to your local machine. The article also showed you how to fix a common error related to submodule updates.

To learn more about Git workflows, read How Does Git Work?

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 Set Upstream Branch in Git
January 18, 2021

Learn how to set up a Git upstream branch, how to change it and how to have an overview of which Git branch is tracking...
Read more
Git Commands Cheat Sheet
March 10, 2020

Git commands are an essential lesson that every developer needs to master at some point. To use the full potential of Git, the popular version control...
Read more
How to Restore a Git Repository
August 1, 2022

Deleted or overwritten a repository? No backup? Don't worry just yet, this guide covers some steps to try and restore the repository.
Read more
Git Checkout Tag
December 2, 2021

Git tags help developers create source points during development. The primary purpose is to mark and reference release versions. Checkout works with any Git object, including tags.
Read more