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.

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
# --- 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.
[submodule "vendor/util"]
path = vendor/util
url = https://github.com/lib/util.git
branch = main
shallow = trueKey Comparison Table
| Aspect | Submodule | Subtree |
|---|---|---|
| Where dependency content lives | Separate repository, checked out into the path | Copied into the parent tree |
| Parent records | Commit hash in a gitlink | Real files and blobs |
| Clone cost | Needs --recurse-submodules | None, one clone |
| Upstream history available | Yes, full, in the nested repo | Only what was merged in |
| Pinning | Exact commit, always | Whatever was merged last |
| Pulling upstream updates | git submodule update --remote | git subtree pull |
| Code review across the boundary | Two repositories | One diff, one review |
| Reproducibility for CI | Requires submodule credentials | Nothing extra |
| Repository size | Small | Grows with every sync |
| Symptom | Submodule cause | Subtree cause |
|---|---|---|
| Empty directory after clone | update --init not run | Prefix path wrong |
| Local changes not committed upstream | Committed in the submodule, parent still points at the old hash | Changes belong to the parent only until subtree push |
| Merge conflicts on every sync | --squash lost upstream ancestry | Same, without --squash, still differs from a real merge |
| Sensitive URL in history | .gitmodules change | Copied files include a secret |
Practical Edge Cases and Deep Dives
1. The empty directory after clone
git clone https://github.com/org/app.git
cd app
ls vendor/util # empty
git submodule update --init --recursiveA plain clone checks out the gitlink as an empty directory; nothing inside it is fetched. Make it automatic for everyone:
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
git submodule update # moves each submodule to the recorded commit
cd vendor/util && git status
# HEAD detached at 9c1e2f4git 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
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
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 | headWithout --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
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 = trueA 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
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 submoduleA 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
| Symptom | Cause | Fix |
|---|---|---|
No url found for submodule path | .gitmodules edited by hand, or entry removed incompletely | git submodule sync, fix .gitmodules, re-init |
fatal: transport 'file' not allowed | Submodule URL resolves to a local path | Use a real remote URL, or protocol.file.allow=always deliberately |
| CI builds without the dependency | No --recurse-submodules in the clone step | Add it, plus credentials for the submodule repo |
| Parent shows modified gitlink after a submodule commit | Submodule HEAD moved, parent hash not committed | Commit the gitlink in the parent |
git subtree pull conflicts every time | Previous syncs used --squash | Continue with --squash, or reset and adopt the unsquashed flow |
prefix ... already exists on subtree add | Directory present in the tree | Remove it first, or choose a new prefix |
| Deleted submodule reappears | .git/modules/<path> still cached | rm -rf .git/modules/<path> |
| Cloned repo is huge after subtree use | Every sync copied files into history | Accept it, or switch to the submodule model |
| Submodule URL changed but clones still old | .git/config holds a stale copy | git submodule sync --recursive |
Try matching browser tools
All toolsSmall utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Git guides
All Git guidesGit config: Aliases, rerere, and Credential Helpers
Five config scopes decide one value at a time. Aliases are user-level shorthand, rerere records conflict resolutions, and credential helpers choose where your secret lives.
Git Hooks: pre-commit, commit-msg, and Husky Automation
Hooks live in .git/hooks, which a clone never receives, so core.hooksPath and Husky are how they travel. Exit codes abort the operation, and every hook is bypassable.
Git bisect: Binary Search, Automated Scripts, and Bug Hunting
Mark one bad and one good commit and Git halves the range each step. bisect run automates it through exit codes, and monotonicity is the assumption that must hold.
Git ignore: Patterns, Negation, and Untracking Cached Files
Patterns are relative and last match wins, but a negation cannot revive a file inside an excluded directory. Ignore rules never touch tracked files: rm --cached first.
More in Git
All Git guidesThe guides filed next to this one in Git, in library order.