How To Pull The Latest Git Submodule

Introduction

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.

Prerequisites

• Git installed (read our installation tutorials for Windows, macOS, CentOS 7, CentOS 8, and Ubuntu).
• GitHub account.

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.

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

git submodule update --init --recursive

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.

3. Merge the remote changes with your local version:

git merge [submodule-branch]

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:

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]'

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]

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.

Conclusion

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?