A Guide to Project Dependency Management with Git Submodule: Hands-On Practice and Real-World Troubleshooting

Git tutorial - IT technology blog
Git tutorial - IT technology blog

The Problem of Sharing Code Across Multiple Projects

Once you work on more than two projects, you will inevitably run into this situation: a shared authentication (auth) module or UI library needs to be used across both a web app and an admin CMS. The initial reaction of many developers is to copy-paste the entire code folder from project A to project B (rather than using git subtree split to extract a subdirectory into an independent repo).

This gets the job done in five minutes. But headaches follow shortly after.

Imagine the auth library develops a critical security flaw. You patch the bug in the main repo, then have to open three other repositories to manually overwrite the files and commit the changes in each location.

Miss a single spot, and you’re in trouble: projects run diverging codebases, spawning silent bugs that are notoriously difficult to debug. Packaging the library and pushing it to a private npm or pip registry is the standard approach. However, if the library is under active, rapid development with dozens of commits each day, constantly bumping versions will eat up hours of waiting for builds and deployments.

Git Submodule was designed specifically to solve this bottleneck: embed one Git repository directly inside another while keeping the commit history of both fully separate.

Under the Hood: How Git Submodule Actually Works

Many developers assume that Git Submodule downloads all commits from the sub-repo and merges them into the parent repo. That is actually not the case.

At its core, a Git Submodule functions simply as a pointer. The parent repo does not track every file or line of code from the sub-repo. Instead, it only records two pieces of data:

  • The URL of the sub-repo (declared in the .gitmodules file).
  • The specific commit hash (SHA-1 or SHA-256) where the subfolder currently rests at the time you commit in the parent repo.

The .gitmodules file lives right in the root directory of the parent repo, looking straightforward like this:

[submodule "libs/shared-auth"]
	path = libs/shared-auth
	url = [email protected]:my-company/shared-auth.git

Thanks to this pointer mechanism, the two repositories have completely independent development lifecycles. You can freely commit and branch in the sub-repo without cluttering the main project’s commit history. The parent repo only points to a new commit once the team has thoroughly verified compatibility.

Hands-On: Adding, Cloning, and Syncing Git Submodules

1. Embedding a Sub-repo into the Main Project

From the root directory of your main project, run the following command to embed the shared-auth repo into the libs/shared-auth folder:

git submodule add [email protected]:my-company/shared-auth.git libs/shared-auth

Git will automatically clone the sub-repo’s source code into the specified folder and generate the .gitmodules file. Running git status will show the new configuration file alongside a directory entry with a special mode (gitlink mode 160000). Now, save this change to the parent repo:

git commit -am "feat: integrate shared-auth submodule"
git push origin main

2. Cloning a Project with Submodules Without Empty Folders

Nine out of ten developers new to submodules hit this trap: cloning the parent repo using the familiar git clone command, only to find the submodule directory completely empty.

The reason is simple: by default, Git does not automatically fetch dependency repositories to conserve bandwidth. To pull both the parent project and all sub-repos right from the start, simply add the --recurse-submodules flag:

git clone --recurse-submodules [email protected]:my-company/main-project.git

If you already cloned it the regular way, there is no need to delete everything and start over. Just run this command to pull the missing code:

git submodule update --init --recursive

3. Updating a Submodule to the Latest Version

When a teammate pushes a patch to the sub-repo, your parent project will not update automatically. To pull the latest commit from the remote tracking branch to your local machine, run:

git submodule update --remote --merge

Running git diff in the parent repo will reveal that the submodule’s commit pointer has changed. The final step is to commit this new hash to the parent repo so the entire team receives the update:

git add libs/shared-auth
git commit -m "chore: update shared-auth submodule to latest commit"
git push origin main

4. Real-World Troubleshooting: Escaping the Detached HEAD Trap

The HEAD detached at <commit-hash> state is the most classic headache when working with submodules. It occurs because the git submodule update command points HEAD directly to a specific commit hash rather than checking out a branch name.

If you happen to edit code and commit directly in this state, that commit becomes orphaned (detached from any branch). When someone runs an update, your commits can easily get misplaced and lost inside the Git reflog.

In a production project with a team of six backend engineers, our rule was crystal clear: never commit directly while in a detached HEAD state. If you need to urgently patch a bug directly inside the sub-repo, follow these steps:

# 1. Navigate into the submodule directory
cd libs/shared-auth

# 2. Checkout the specific working branch
git checkout main
git pull origin main

# 3. Modify code, commit, and push to the sub-repo's remote FIRST
git commit -am "fix: resolve JWT token verification bug"
git push origin main

# 4. Return to the parent repo root to record the new commit hash
cd ../..
git add libs/shared-auth
git commit -m "fix: update shared-auth submodule with JWT patch"
git push origin main

Pushing changes to the sub-repo’s remote before updating the hash in the parent repo is a non-negotiable rule. This ensures teammates pulling the parent repo will always find the corresponding commit on the remote, completely avoiding the fatal: reference is not a tree error that breaks CI/CD pipelines.

Summary

Git Submodule does require remembering a few additional command flags when cloning and updating. In return, it provides the cleanest solution for sharing internal code without the overhead of setting up a complex private package infrastructure. By mastering the commit pointer concept, always cloning with --recurse-submodules, and remembering to checkout a branch before editing code, you can smoothly manage multi-repo architectures without fear of data loss.

Share: