Skip to content
Velloreth
Developer Tools 4 min read

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

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

AlternativeWhen
A package managerthe code can be published
A monorepothe projects are developed together
A subtreethe code should be copied in
A submodulethe 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.

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.

Frequently asked questions

What is a git submodule?
It is a reference from one repository to another at a specific commit. The parent repository stores the URL and the commit hash, and the submodule's files are checked out into a subdirectory. The parent does not store the submodule's history, only the pointer.
Why is my submodule directory empty after a clone?
Because a clone does not initialise the submodules by default. Run git submodule update --init --recursive to fetch and check out the contents. A clone with --recurse-submodules does it in one step.
Why is my submodule in a detached HEAD state?
Because the parent records a commit hash rather than a branch, so the submodule is checked out at that commit with no branch. A commit made there is not on a branch and can be lost. Switch to a branch before making a change.
How do I update a submodule?
Enter the submodule, fetch and check out the commit you want, then commit the new pointer in the parent. The parent records the new hash. To pull the latest from the submodule's remote, run git submodule update --remote.
What is the alternative to a submodule?
A package manager, if the shared code can be published as a package. A monorepo, if the projects are developed together. A subtree, if the code should be copied into the parent. A submodule is the right choice when the other repository is developed independently and must be pinned.
What is the most common submodule mistake?
Committing in the submodule and forgetting to commit the updated pointer in the parent. The change is in the submodule's history but the parent still points at the old commit, so a teammate who clones gets the old code.