Introduction
Submodules help manage complex projects in Git. They allow external repositories to exist as directories within another repository, which makes it easier to maintain separate records of changes for each feature, module, or microservice.
This tutorial will teach you how to perform basic submodule management operations - adding, updating, and removing Git submodules.
Prerequisites
- Git installed.
- Access to a Git repository hosting service, such as GitHub.
Add Git Submodule
A Git submodule is a record in a repository that points to a specific commit in another external repository. When a user adds a submodule, Git creates a .gitmodules file in which it stores the mapping between the URL of the original repository and the local subdirectory hosting its contents.
To add a submodule to a repository, type the following command:
git submodule add [repository-url]The command output shows that Git cloned the contents of the external repository into a subdirectory of the same name:
Check the records by opening the .gitmodules file in a text editor:
nano .gitmodulesThe submodule's path and URL are successfully registered in the file.
Specify Target Directory
To create a submodule with a name that differs from the original repository's name, add the custom path to the git submodule add command:
git submodule add [repository-url] [custom-directory-path]In the example below, Git clones the contents of the external repository into a subdirectory named custom-name.
Commit Submodule
As with any changes made to a repository, you must commit and push the submodule addition to remote before the changes become available to everyone working in the repository.
1. Commit the changes with git commit.
git commit -m [message-text]The output displays the submodule creation action as a committed change.
2. Push the commit to remote.
git push
Updating Submodules
As the project progresses, the contents of a submodule repository may change. Since submodules point to a particular commit in the original repository, using git fetch to check for remote changes does not reflect the changes made to a submodule repository.
Use the git submodule update command to check if a submodule directory is up-to-date.
Submodule directories are initially empty in cloned repositories. When performing the first update, use the --init flag to initialize submodules and the --recursive flag to ensure that the command checks for nested submodules too.
git submodule update --init --recursiveThe command registers the submodules, clones their content into the respective subdirectories, and checks out the submodule paths.
If you are updating already initialized submodules, use the --remote flag to tell Git to enter each submodule directory and fetch any available changes, and the --merge option to merge local and remote changes.
git submodule update --remote --mergeThe command output shows the changes made.
Removing Submodules
Removing a submodule in Git involves the following actions:
- Deleting the contents of the subdirectory.
- Removing the subdirectory path registration.
- Deleting the subdirectory.
- Committing and pushing the changes.
Follow the procedure below to remove a submodule from a project.
1. Use the git submodule deinit command to clear the directory and unregister the submodule path.
git submodule deinit [submodule-path]
2. Remove the submodule with the git rm subcommand.
git rm [submodule-path]
3. Commit the changes made.
git commit -m "[message]"
4. Push the changes to remote.
git push
The submodule is now completely removed from the project, but the original repository still exists. It can be added again at a later time or maintained separately.
Conclusion
This article explained how to perform the most common submodule management operations in Git. After reading it, you should know how to add a submodule to your Git project, update its contents, and remove it if necessary.
For a more comprehensive submodule tutorial, read Git Submodule Guide & Basic Commands to Get Started.
