In large-scale software projects, it is common to reuse code from other repositories. Simply copying the code can make maintenance difficult and error-prone. This is where Git Submodules provide one of the most classic and effective solutions.
In software development, there are many situations where a project needs to reference another independent project, such as a shared library, reusable UI components, or a third-party package. When you want these components to be maintained independently while still being shared across multiple projects, Git Submodules provide an excellent solution.
A Git Submodule is a feature provided by Git that allows one Git repository to be included as a subdirectory within another Git repository. Unlike simply copying and pasting source code, Git Submodules use a pointer-based mechanism. The parent repository stores only the submodule’s remote repository URL and a specific commit ID (SHA-1 hash). When other team members clone the parent repository, Git uses this pointer to retrieve the exact version of the submodule from its corresponding repository, ensuring everyone works with the same code.
Why Use Git Submodules? (Key Benefits)
- Code Reusability and Sharing
A shared library (such as a utils repository) can be referenced by multiple projects, eliminating duplicate code and reducing maintenance effort. - Clear Project Boundaries
Developers working on the parent repository do not need to deal with the detailed commit history of the submodule. As a result, the parent repository’s commit history remains clean and focused. - Precise Version Control
The parent repository has complete control over when to upgrade to a newer version of the submodule. Updates made to the submodule repository will not automatically affect the parent project, preventing unexpected issues caused by untested changes.
git submodule add example
1. Navigate to the C drive root directory.
2. Create a folder named Module and enter the Module directory.
3. Create a file named 1.txt.
4. Initialize the Git repository, add 1.txt to the staging area, and make a commit.
5. Create a folder named submodule and enter it.
6. Create a file named 2.txt inside the submodule folder.
7. Return to the Module directory. To configure the newly created submodule folder and its files as a submodule of the Module repository, execute the following command:
git submodule add ./submodule
8. Run git status, and it will show that the submodule folder has been added to the Module repository. (Note: Remember that the submodule folder must be initialized as a separate Git repository first using git init, git add ., and git commit -m).
Please Note: This issue stems from a common security restriction introduced in Git 2.38+. By default, Git disallows the use of file:// protocols or local directory paths to add submodules, preventing malicious repositories from exploiting local files. As shown in the example below.
Git treats local paths as a local (file) transport mechanism, and therefore rejects the operation.
Add git submodules to GitHub
I have two repositories on GitHub: Module and Submodule. We will try to make the Submodule repository a submodule of the Module repository.
Please note that the files in these two remote repositories are newly created and are completely unrelated to the previous local examples.
1. To configure the Submodule repository as a submodule of the Module repository, execute the following command:
git submodule add https://github.com/Joseph225Gang/Submodule.git
2. Next, run git add, git commit, and git push to add the submodule to the remote Module repository.
3. Once the Submodule repository is successfully added as a submodule of the Module project as described above, you can open the .gitmodules file to view the path and URL configurations of the child repository.
4. Next, let’s try updating the Submodule repository. We will add a file named test.txt on the submodule side.
5. Please note that if you want to pull the latest version of the submodule within the Module repository, you need to execute either of the following commands:
git submodule update –remote or
git submodule update –remote submodule specific submodule
Therefore, updating a submodule requires a two-step process:
- First, update the submodule itself (using git pull inside the submodule directory, or git submodule update –remote from the parent directory).
- Next, return to the parent repository and commit the new submodule commit pointer (by running git add Submodule
git commit
git push).
In other words, even if changes have already been git pushed within the submodule repository, the parent repository must still make another commit to allow other team members to pull the updated version of the submodule.
Finally, if we head back to GitHub to check, we will see that the Submodule folder inside the Module repository has been successfully updated.
In summary, Git Submodule is ideal for scenarios where multiple projects need to share a stable base library, UI components, or utility functions, especially when you want to precisely control versions and keep the main project clean. It effectively avoids reinventing the wheel while allowing submodules to be maintained independently. However, if two projects are highly coupled, the submodule requires very frequent updates, or the team is not yet familiar with the tool, using Submodules is not recommended; in such cases, you might consider a Monorepo architecture, Git Subtree, or publishing packages directly through package managers instead. Mastering the right timing and update workflows for Submodules will significantly boost project management efficiency. I highly recommend practicing the actual steps firsthand and continuing to refine your workflow as you encounter challenges, making it a powerful asset for your team’s development!