Introduction
Git submodules allow users to host multiple repositories as subdirectories of the master repository. With submodules, you can use other Git sources without copying their code into the main project tree.
This tutorial will show you how to extract 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
.
Extracting the last Git submodule
When a user clones a Git repository that contains submodules, the submodules appear as directories in the project tree. However, these directories are cloned empty and require additional steps to be functional.
The following sections describe how to configure submodules locally and extract the latest versions. Finally, the tutorial helps you fix a common error that appears during the submodule upgrade process.
Initialize
a submodule in the repository Type the following command in the
Git directory to initialize the submodules and clone them to their path
: git submodule update -init
The output shows that the submodule has been successfully registered and checked out.
If a project contains nested submodules, that is, submodules within submodules, add the -recursive option to the above command:
git submodule update -init -recursive Extract the last 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 this:
1. Go to the directory of the submodule 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 remote changes with their local version:
git merge [submodule-branch]
Extract the last submodule
with git update Using git
fetch and git merge to update submodules can be time-consuming, especially if you are working on a project with multiple submodules. The easiest way to perform the action is to use the git submodule update command.
For Git 1.8.2 and above, run the following command in the project’s home directory: git submodule update -recursive -remote
The output shows that
Git updated the submodule automatically:
For Git 1.7.3 and higher, use the following syntax
: git submodule update -recursive Alternatively, run the git pull command with the -recurse-submodules
option: git pull –recurse-submodules
Fix
the error “Fatal: I needed a single revision”
When performing the git submodule update command, the following error may appear
: Fatal: I needed a single revision The current original/master revision cannot be found in the submodule path ‘[submodule-name]’
The error appears if you do not use the master branch of the submodule in question. Fix it by editing the . gitmodules in the main directory of the project.
1. Open .gitmodules
in a text editor: nano. gitmodules
2. Add the branch of the submodule you are using to the submodule configuration section:
branch = [branch-name]
3. Save and exit the file, and then run the git submodule update command again.
To make the same change for multiple submodules without directly editing the . gitmodules, type:
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 extract the latest versions of Git submodules to your local machine. The article also showed you how to fix a common bug related to submodule updates.
For more information about Git workflows, see How does Git work?
