Git Submodule Explained: Add, Clone, Update and Remove Safely
A git submodule embeds one Git repository inside another at a fixed commit, which is how projects share libraries, themes or vendor code without copying them. Submodules are also famous for confusing people. We walked through the full life cycle in a test repository: adding one, cloning a project that uses it, updating it, the detached HEAD trap, and removing it cleanly.
- A git submodule records a path, a URL in
.gitmodulesand one exact commit of the other repository. - A plain
git cloneleft the submodule folder empty until we rangit submodule update --init --recursive. - When the library gained a new commit, the parent stayed on the old one until
git submodule update --remoteand a new commit in the parent. - Submodule checkouts sat on a detached HEAD, and
git rmleft a copy of the submodule repository behind in.git/modules.
Sometimes one repository needs another: an application uses a shared library, a website uses a theme, a firmware build includes a vendor SDK. Copying the code loses its history and makes updates painful. A git submodule keeps the other project as its own repository inside yours, pinned to a specific commit, so everyone builds against exactly the same version.
We built a small library repository and an application that uses it, then ran every step on Git 2.56.0. Paths in the output are shortened to /work.
What is a git submodule?
A submodule is a pointer from the parent repository (the superproject) to a commit in another repository. The parent does not store the submodule’s files; it stores the path, the URL and the commit ID. When you check out the submodule, Git clones the other repository into that path and checks out exactly that commit.
Our test setup
lib.git a bare repository holding util.py with VERSION = '1.0'
app the application repository, which will use lib as a submodule
Adding a submodule
git submodule add ../lib.git vendor/lib
Cloning into '/work/app/vendor/lib'
done.
cat .gitmodules
[submodule "vendor/lib"]
path = vendor/lib
url = ../lib.git
git status --short
A .gitmodules
A vendor/lib
git submodule add URL PATH clones the repository into the path, creates or updates .gitmodules, and stages both. You then commit as usual. We used a relative URL, which resolves against the parent’s own remote; in real projects this is usually an HTTPS or SSH URL, configured like any git remote.
What the parent actually stores
git submodule status
9f851faf41b201abc77cc98459a8a0f75459cef1 vendor/lib (heads/main)
git ls-tree HEAD vendor/lib
160000 commit 9f851faf41b201abc77cc98459a8a0f75459cef1 vendor/lib
The parent’s tree contains a special entry with mode 160000 and type commit: a single commit ID, not files. That is the whole trick. The superproject says “use lib at commit 9f851fa”, and nothing changes until someone commits a different ID.
The empty folder after a normal clone
git clone app.git clone1
ls clone1/vendor/lib # [] empty
git submodule status
-9f851faf41b201abc77cc98459a8a0f75459cef1 vendor/lib
This is the most common submodule surprise. A normal clone created the vendor/lib folder but left it empty, and builds that need the library fail with “file not found”. The minus sign in git submodule status means “not initialised”.
Filling it: update –init –recursive
git submodule update --init --recursive
Submodule 'vendor/lib' (/work/lib.git) registered for path 'vendor/lib'
Cloning into '/work/clone1/vendor/lib'
done.
Submodule path 'vendor/lib': checked out '9f851faf41b201abc77cc98459a8a0f75459cef1'
ls clone1/vendor/lib # ['.git', 'util.py']
--init copies the submodule settings from .gitmodules into your local configuration, and update clones and checks out the pinned commit. --recursive does the same for submodules inside submodules. This one command is worth putting in your project’s setup instructions and CI scripts.
Cloning with submodules in one step
git clone --recurse-submodules app.git clone2
# clone2/vendor/lib/util.py exists: True
Adding --recurse-submodules to the clone fills every submodule straight away. Hosted CI systems usually have a checkout option for the same thing, for example the submodules setting of the checkout action in our GitHub Actions guide.
Submodules are pinned, not live
# the library gets a new commit upstream: "lib v1.1"
git submodule status # in clone1
9f851faf41b201abc77cc98459a8a0f75459cef1 vendor/lib (heads/main) still the old commit
After the library moved forward, the application still used the old commit. This is deliberate: a change in the library cannot break the application until someone chooses to update. It is also why a submodule can quietly fall far behind, so schedule updates rather than forgetting them.
Updating a submodule to the latest commit
git submodule update --remote
From /work/lib
9f851fa..84addbb main -> origin/main
Submodule path 'vendor/lib': checked out '84addbb2ff27bd2e8daa037abce418ee8888619d'
git status --short
M vendor/lib
git diff --submodule=log
Submodule vendor/lib 9f851fa..84addbb:
> lib v1.1
git commit -am "bump lib to v1.1"
--remote fetches the submodule’s remote and checks out the latest commit of its tracked branch (the default branch, unless branch is set in .gitmodules). The parent now shows the submodule as modified, and git diff --submodule=log lists the library commits you are pulling in, which is exactly what a reviewer needs to see. Committing records the new pointer; until then, teammates still get the old version. After a teammate pulls that commit, they run git submodule update to move their checkout, or use git pull --recurse-submodules.
The detached HEAD trap
cd clone2/vendor/lib
git status --short --branch
## HEAD (no branch)
Submodules are checked out at a specific commit, not on a branch, so they are in a detached HEAD state. If you edit and commit inside the submodule now, the commit belongs to no branch and is easy to lose on the next update. Before changing code inside a submodule, run git switch main (or create a branch) in the submodule, commit and push there first, then commit the new pointer in the parent. Our git branch guide explains detached HEAD in more detail.
Tip: push the submodule’s commits before pushing the parent. If the parent points at a commit that only exists on your machine, everyone else’s update fails.
Running a command in every submodule
git submodule foreach git log --oneline -1
Entering 'vendor/lib'
84addbb lib v1.1
foreach runs any shell command inside each checked-out submodule, useful for status reports, pulling, or cleaning. Add --recursive to include nested submodules.
Removing a submodule cleanly
git submodule deinit -f vendor/lib
Cleared directory 'vendor/lib'
Submodule 'vendor/lib' (../lib.git) unregistered for path 'vendor/lib'
git rm vendor/lib
git status --short
M .gitmodules
D vendor/lib
# .gitmodules is now empty
# .git/modules/vendor/lib still exists: True
deinit removes the working files and the local configuration, and git rm deletes the pointer and its entry in .gitmodules. Commit the result. One thing is left behind: Git keeps the submodule’s own repository in .git/modules/vendor/lib, so re-adding it later is fast. Delete that folder manually if you want the space back or plan to add a different repository at the same path. Leftover files outside Git’s tracking can be checked with git clean, which skips nested repositories unless forced twice.
The “transport ‘file’ not allowed” error
git submodule add ../lib.git vendor/lib2
fatal: transport 'file' not allowed
fatal: clone of '/work/lib.git' into submodule path '/work/app/vendor/lib2' failed
Since Git 2.38.1, cloning submodules from local file paths is blocked by default, a security fix against malicious repositories. Real projects use network URLs and are unaffected. For local experiments like ours, Git must be told to allow the file protocol for that command, which is how we ran the rest of this walkthrough; do not enable it globally on machines that clone untrusted repositories.
Alternatives to submodules
- Package managers (pip, npm, Maven, Go modules): usually the best choice for libraries with versioned releases.
- git subtree: copies another repository’s history into a folder of yours; no extra commands for people who clone, but updates are more manual.
- Monorepo: keep related projects in one repository with shared tooling.
- Submodules fit best when you need an exact commit of a repository that is not packaged, such as firmware SDKs, shared configuration or themes.
For working on two versions side by side instead, see git worktree; for everyday commands, our Git cheat sheet.
Final thoughts
A git submodule is simply a pointer to one commit of another repository. Most problems come from forgetting that: a fresh clone needs update --init --recursive, upstream changes arrive only after update --remote and a commit in the parent, and submodule checkouts sit on a detached HEAD until you switch to a branch. Push submodule commits before the parent, review updates with diff --submodule=log, and remove submodules with deinit plus rm. Follow that routine and submodules become predictable rather than painful.
Frequently asked questions
What is a git submodule?
A reference from one Git repository to a specific commit of another repository, checked out into a folder. The parent stores only the path, URL and commit ID, not the files.
Why is my submodule folder empty after cloning?
A normal clone does not fetch submodules. Run git submodule update with the init and recursive options, or clone with the recurse submodules option next time.
How do I update a submodule to the latest version?
Run git submodule update with the remote option to check out the newest commit of the tracked branch, then commit the changed submodule pointer in the parent repository.
Why is my submodule in detached HEAD state?
Submodules are checked out at the exact commit the parent records, not on a branch. Switch to a branch inside the submodule before making commits there.
How do I remove a git submodule?
Run git submodule deinit on the path, then git rm on the path, and commit. Optionally delete the leftover copy inside the git modules folder of the parent repository.
Keep learning
Need help with testing, WordPress or SEO?
We help teams ship better software and grow their sites. Tell us what you are working on and we will suggest a clear next step.