Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Git Submodules vs Subtree: Cloning, Updating, and Removal

A submodule records a commit hash and needs an extra init step everywhere; a subtree copies files into your history. The comparison that decides which friction you want.

~5 min readGit
#Git#Submodules#Subtree#Dependency
3D illustration of a parent repository cube containing a nested repository cube beside a vendored copy

Quick Summary

A submodule is a repository nested inside another one, recorded as a single gitlink entry (mode 160000) plus a .gitmodules file holding its URL. The parent repository stores a commit hash, not files, so the parent and the dependency have independent histories.

A subtree copies the dependency's files into a subdirectory of the parent, keeping its commits in the parent's history. Consumers clone once and get everything; there is no separate init step.

The trade is explicit: submodules keep a clean separation and pin an exact upstream commit, but every clone, CI job, and code review has to know about them. Subtrees erase that friction at the price of a larger repository, awkward upstream synchronisation, and upstream hashes that are not preserved when --squash is used.

Basic Syntax and Core Signatures

bash
# --- Submodules --- git submodule add https://github.com/lib/util.git vendor/util git submodule status # "-" not init, "+" wrong commit, " " clean git clone --recurse-submodules <url> git submodule update --init --recursive # after a plain clone git submodule update --remote --merge # move to the upstream branch tip git submodule foreach 'git switch -c tmp && git status' # run in each git submodule sync --recursive # after .gitmodules URL changes git submodule deinit -f vendor/util # remove working tree + config entry git rm vendor/util && rm -rf .git/modules/vendor/util # --- Subtrees --- git subtree add --prefix=vendor/util https://github.com/lib/util.git main --squash git subtree pull --prefix=vendor/util https://github.com/lib/util.git main --squash git subtree push --prefix=dist origin gh-pages git subtree split --prefix=vendor/util -b util-only

.gitmodules is committed and shared; .git/config gets a second copy of the same settings the first time you initialise, which is why URL changes need git submodule sync in addition to editing the file.

ini
[submodule "vendor/util"] path = vendor/util url = https://github.com/lib/util.git branch = main shallow = true

Key Comparison Table

AspectSubmoduleSubtree
Where dependency content livesSeparate repository, checked out into the pathCopied into the parent tree
Parent recordsCommit hash in a gitlinkReal files and blobs
Clone costNeeds --recurse-submodulesNone, one clone
Upstream history availableYes, full, in the nested repoOnly what was merged in
PinningExact commit, alwaysWhatever was merged last
Pulling upstream updatesgit submodule update --remotegit subtree pull
Code review across the boundaryTwo repositoriesOne diff, one review
Reproducibility for CIRequires submodule credentialsNothing extra
Repository sizeSmallGrows with every sync
SymptomSubmodule causeSubtree cause
Empty directory after cloneupdate --init not runPrefix path wrong
Local changes not committed upstreamCommitted in the submodule, parent still points at the old hashChanges belong to the parent only until subtree push
Merge conflicts on every sync--squash lost upstream ancestrySame, without --squash, still differs from a real merge
Sensitive URL in history.gitmodules changeCopied files include a secret

Practical Edge Cases and Deep Dives

1. The empty directory after clone

bash
git clone https://github.com/org/app.git cd app ls vendor/util # empty git submodule update --init --recursive

A plain clone checks out the gitlink as an empty directory; nothing inside it is fetched. Make it automatic for everyone:

bash
git config --global submodule.recurse true # checkout/pull/switch recurse git config --global fetch.recurseSubmodules on-demand # or per clone: git clone --recurse-submodules --shallow-submodules <url>

on-demand fetches submodule objects only when a needed commit is missing, which keeps a normal git fetch fast. Also be aware that --recurse-submodules does not help if the submodule URL is unreachable to a teammate or CI — the failure is a permission error on a second repository, and that is usually the real cause of "clone works for me".

2. Submodule updates leave a detached HEAD

bash
git submodule update # moves each submodule to the recorded commit cd vendor/util && git status # HEAD detached at 9c1e2f4

git submodule update checks out the parent's recorded commit, which is detached because the parent does not own a branch in the submodule. Committing here is legal and produces a commit nobody points at; the parent then shows a modified gitlink until you commit the new hash in the parent. The workflow that survives code review is: branch inside the submodule, push it, open a PR against the dependency, merge, then in the parent git submodule update --remote and commit the new gitlink as a deliberate change.

3. Removing a submodule completely

bash
git submodule deinit -f vendor/util # working tree + .git/config entry git rm -f vendor/util # index + working tree rm -rf .git/modules/vendor/util # cached clone, otherwise it lingers git commit -m "chore: drop vendor/util submodule"

Skipping the third step leaves the submodule's clone and its objects in .git/modules/, which reappears as a usable repository if the path is added again, and keeps the disk cost forever. If .gitmodules is edited by hand instead of via git rm, the entry survives in the index and every subsequent clone fails with No url found for submodule path 'vendor/util' in .gitmodules.

4. Subtree without --squash, and what split buys you

bash
git subtree add --prefix=vendor/util https://github.com/lib/util.git main git subtree pull --prefix=vendor/util https://github.com/lib/util.git main git subtree split --prefix=vendor/util -b util-only git log --oneline util-only | head

Without --squash the upstream commits are merged with their original authorship and hashes, so git log --prefix shows real history and a later subtree pull performs a proper merge with no repeated conflicts. With --squash each sync is a single new commit on the parent, which keeps history short but makes every later pull look like unrelated histories — the repeated conflict source. subtree split rebuilds a standalone branch from just that directory, which is how a subtree-managed package is published back upstream or to a package registry.

5. Relative URLs, shallow clones, and CI

bash
git submodule add ../lib.git vendor/lib # relative to the superproject's remote URL git clone --recurse-submodules --depth=1 <url> # fails or empties without care [submodule "vendor/lib"] shallow = true

A relative URL resolves against the superproject's remote, so the same .gitmodules works over HTTPS for contributors and over SSH for CI — but a fork that clones over a different protocol may resolve to a path that does not exist, producing fatal: repository not found. Deep shallow clones are the other trap: --depth=1 applies to the superproject, and submodule objects are fetched with their own depth, so a submodule pinned to an old commit needs git submodule update --init --depth=50 or no depth flag at all.

6. Reviewing a dependency bump

bash
git diff --submodule=log main...feature # Submodule vendor/util 9c1e2f4..3f2a1b9: # > fix: bounds check in parser # > chore: bump deps git diff --submodule=diff # full file-level diff inside the submodule

A default git diff prints -Subproject commit 9c1e2f4 and +Subproject commit 3f2a1b9, which tells a reviewer nothing about what changed. --submodule=log shows the commit subjects, and --submodule=diff shows the actual patch — the difference between a reviewer approving a hash bump and a reviewer noticing a dependency that now makes network calls. For subtree changes the diff is ordinary, which is the strongest argument for subtrees in organisations where review is the bottleneck.

Common Git Operation Mistakes

SymptomCauseFix
No url found for submodule path.gitmodules edited by hand, or entry removed incompletelygit submodule sync, fix .gitmodules, re-init
fatal: transport 'file' not allowedSubmodule URL resolves to a local pathUse a real remote URL, or protocol.file.allow=always deliberately
CI builds without the dependencyNo --recurse-submodules in the clone stepAdd it, plus credentials for the submodule repo
Parent shows modified gitlink after a submodule commitSubmodule HEAD moved, parent hash not committedCommit the gitlink in the parent
git subtree pull conflicts every timePrevious syncs used --squashContinue with --squash, or reset and adopt the unsquashed flow
prefix ... already exists on subtree addDirectory present in the treeRemove it first, or choose a new prefix
Deleted submodule reappears.git/modules/<path> still cachedrm -rf .git/modules/<path>
Cloned repo is huge after subtree useEvery sync copied files into historyAccept it, or switch to the submodule model
Submodule URL changed but clones still old.git/config holds a stale copygit submodule sync --recursive

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.