Git Submodules Explained: When and How to Use Them
A submodule is a repository inside a repository. Learn the commands, the detached HEAD, the alternatives, and the traps.
By Velloreth
What a submodule is
A reference from one repository to another at a specific commit.
parent/
.gitmodules # the URL and the path
libs/shared/ # the submodule, at a pinned commit
The parent stores the URL and the commit hash, not the submodule’s history.
The .gitmodules file records the mapping.
[submodule "libs/shared"]
path = libs/shared
url = https://github.com/example/shared.git
The commands
# Add a submodule
git submodule add https://github.com/example/shared.git libs/shared
# Clone with the submodules
git clone --recurse-submodules <url>
# Initialise after a plain clone
git submodule update --init --recursive
# Update to the recorded commit
git submodule update
# Update to the latest of the tracked branch
git submodule update --remote
# Run a command in every submodule
git submodule foreach 'git status'
--init registers the submodule, and --recursive handles a nested one.
The detached HEAD
The parent records a commit hash, so the submodule is checked out at that commit with no branch.
$ git -C libs/shared status
HEAD detached at abc1234
A commit made there is not on a branch and can be lost.
The fix: switch to a branch before making a change.
git -C libs/shared switch main
The update workflow
To move the parent to a new submodule commit:
cd libs/shared
git fetch
git switch main
git pull
cd ../..
git add libs/shared
git commit -m "chore: bump shared to the latest"
The parent records the new hash.
The step that is forgotten is the commit in the parent, which is why a teammate gets the old code.
The traps
An empty directory after a clone. The submodules are not initialised.
A detached HEAD. A commit is not on a branch.
A forgotten parent commit. The pointer is stale.
A CI job that does not initialise. The build fails on a missing file.
A submodule that is not pinned. The build is not reproducible.
A nested submodule. --recursive is required.
A private submodule. The CI needs a credential.
A submodule with a large history. The clone is slow.
A submodule used for shared code that changes often. Constant pointer churn.
The alternatives
| Alternative | When |
|---|---|
| A package manager | the code can be published |
| A monorepo | the projects are developed together |
| A subtree | the code should be copied in |
| A submodule | the repo is independent and must be pinned |
A package manager is the common choice for shared code, because the version is explicit and the tooling is familiar.
A monorepo is the choice when the projects change together.
A subtree copies the code into the parent, so a clone has everything, at the cost of a duplicated history.
A submodule is the right choice when the other repository is developed independently and must be pinned to a commit.
The CI
A CI job must initialise the submodules.
- uses: actions/checkout@v4
with:
submodules: recursive
A private submodule needs a token with access to the other repository.
A shallow submodule is faster.
git submodule update --init --depth 1
Common mistakes
A plain clone. An empty submodule directory.
A commit in a detached HEAD. A lost change.
A forgotten parent commit. A stale pointer.
A CI without --init. A build failure.
A private submodule without a credential. A clone failure.
A nested submodule without --recursive. A missing file.
A submodule for code that changes often. Constant churn.
A submodule used where a package would do. Unnecessary complexity.
No documentation. A new developer does not know to initialise.
A quotable summary
A git submodule is a reference from one repository to another at a specific commit, and the parent stores the URL and the hash rather than the submodule’s history. A clone does not initialise the submodules, so run git submodule update --init --recursive, and a submodule is in a detached HEAD state, so switch to a branch before committing. A package manager or a monorepo is often a better choice, and a submodule is right when the other repository is independent and must be pinned.
Related reading
For the related topics, see git-rebase-vs-merge and monorepo-vs-multirepo. For the broader context, npm-vs-yarn-vs-pnpm and ci-cd-pipeline-basics.