Git Submodules vs Subtrees: Sharing Code Between Repos
Submodules and subtrees both embed one repository in another. Learn how each works and which to choose.
By Velloreth
The problem
Two projects need to share code. The shared code lives in its own repository, and both projects need it.
The options:
- Copy and paste. Simple, but the copies drift.
- A package. Publish to a registry and install. Clean, but requires a release process.
- A submodule. Reference the other repository at a specific commit.
- A subtree. Copy the other repository’s files into yours.
- A monorepo. Put everything in one repository.
Submodules
A submodule is a pointer to a specific commit in another repository.
Add a submodule:
git submodule add https://github.com/user/lib.git vendor/lib
This creates:
.gitmodules— the submodule configuration, which is committed.- A tree entry at
vendor/libthat records a specific commit.
The .gitmodules file:
[submodule "vendor/lib"]
path = vendor/lib
url = https://github.com/user/lib.git
Clone with submodules:
git clone --recurse-submodules https://github.com/user/project.git
Or, after a normal clone:
git submodule update --init --recursive
Without this, the submodule directories are empty.
Update a submodule to the latest commit:
cd vendor/lib
git fetch
git checkout main
git pull
cd ../..
git add vendor/lib
git commit -m "Update lib to latest"
The parent repository records the new commit. This is the key point: the parent pins a specific commit, not a branch.
Update all submodules:
git submodule update --remote --merge
Why submodules are confusing
A clone does not fetch the contents. The submodule directories are empty until you run the update command. This surprises everyone the first time.
The recorded commit can drift. The parent records a commit, not a branch. If the submodule’s branch moves, the parent still points at the old commit until someone updates it.
Detached HEAD. A submodule is usually in a detached HEAD state, because it is checked out at a specific commit rather than a branch. Committing there is easy to do by accident.
Two-step commits. A change to the submodule requires a commit in the submodule and a commit in the parent.
CI needs the flag. A CI checkout must use --recurse-submodules, or the build fails with missing files.
Subtrees
A subtree copies the other repository’s files into a subdirectory of yours.
Add a subtree:
git subtree add --prefix=vendor/lib https://github.com/user/lib.git main --squash
This fetches the other repository and merges its files into vendor/lib. The files are now part of your repository.
Pull updates:
git subtree pull --prefix=vendor/lib https://github.com/user/lib.git main --squash
Push changes back:
git subtree push --prefix=vendor/lib https://github.com/user/lib.git main
Why subtrees are simpler
A clone gets everything. The files are part of your repository, so there is no extra step.
No separate state. There is no .gitmodules, no detached HEAD, and no two-step commit.
CI works normally. No special flags.
You can modify the code. Since the files are yours, you can edit them. Pushing back is possible but optional.
The cost
The history is merged. The other repository’s commits become part of your history, which can be noisy. The --squash flag collapses them into one commit.
The commands are long. git subtree is not a built-in command in older Git versions; it is a contributed script. It is bundled with modern Git.
Pushing back is awkward. The subtree push command replays your commits onto the other repository, which can be slow and can produce conflicts.
The copy can drift. If you modify the vendored code, pulling an update may conflict.
Comparing them
| Submodule | Subtree | |
|---|---|---|
| Files in your repo | No | Yes |
| Clone needs extra step | Yes | No |
| History | Separate | Merged |
| Modify the code | Awkward | Natural |
| Push changes back | Natural | Awkward |
| CI setup | Needs a flag | Normal |
| Complexity | High | Medium |
.gitmodules | Yes | No |
Choosing
Use a submodule when:
- The other repository is a dependency you do not modify.
- You want to track a specific commit.
- The other repository is large and you do not want its history in yours.
Use a subtree when:
- You vendor code that you may modify.
- You want a clone to work with no extra steps.
- You want the files to be part of your repository.
Use neither when:
- The shared code can be a package. A registry is almost always simpler.
- The projects are closely related. A monorepo with workspaces avoids the problem entirely.
The simpler alternatives
A package. Publish the shared code to npm, PyPI, or a private registry, and install it. This is the standard solution, and it has a real release process, versioning, and dependency resolution.
A monorepo. Put both projects in one repository with a workspace tool. The shared code is a local package, and there is no embedding at all. This is what most large organisations do.
A git dependency. Some package managers can install directly from a Git URL.
{
"dependencies": {
"lib": "github:user/lib#v1.2.3"
}
}
This gets the benefit of a pinned commit without the submodule machinery.
The honest assessment: submodules and subtrees are both workarounds for the absence of a package. If the shared code can be a package, make it one.
Practical guidance
- Prefer a package over embedding a repository.
- Use a submodule for a dependency you do not modify.
- Use a subtree for code you vendor and edit.
- Clone with
--recurse-submoduleswhen submodules are present. - Use
--squashwith subtree to keep the history clean. - Add the CI flag for submodules.
- Pin a commit, not a branch, for reproducibility.
- Document the update procedure for the team.
For the related guides, see git-worktrees-guide and git-branching-strategies. For the broader context, git-large-files-guide and semantic-versioning-explained.
Quotable summary
A submodule is a pointer to a specific commit in another repository, which must be cloned and updated separately, while a subtree copies the other repository’s files into yours so a clone gets everything with no extra steps. Submodules keep the history separate and are better for a dependency you do not modify, while subtrees merge the history into your repository and are better for code you vendor and edit. Submodules are confusing because a clone does not fetch the contents by default, the recorded commit can drift from the branch, and CI needs a special flag. Both add complexity, so consider a package registry or a monorepo first, since submodules and subtrees are both workarounds for the absence of a package.