🔀 Git: Fix a Submodule Pointing to a Commit That No Longer Exists
A Git submodule reference stores a specific commit SHA, not a branch. If that commit is later removed from the submodule’s own remote history — a force-push that rewrites history, a branch deleted after a squash-merge, or the submodule repository being migrated — the parent repo’s recorded SHA becomes dangling: git submodule update fails to fetch an object that simply no longer exists on the remote, even though the parent repo’s own history looks completely unchanged.
🔎 The Problem
parent repo gitlink: libs/shared-utils @ a1b2c3d shared-utils remote: a1b2c3d was squash-merged into main and the feature branch it lived on was deleted. a1b2c3d is now unreachable. git submodule update --init -> fatal: remote error: upload-pack: not our ref a1b2c3d Fetched in submodule path 'libs/shared-utils', but it did not contain a1b2c3d. Direct fetching of that commit failed.
✅ Fix: Re-Point to a Surviving Equivalent Commit
- Before force-pushing or rewriting history on any repository used as a submodule elsewhere, check whether known parent repositories pin commits that would become unreachable, since the parent’s reference has no way to know the commit disappeared until someone tries to update it.
- If a submodule reference is already dangling, find the nearest surviving equivalent commit (often the squashed/merged replacement), check it out inside the submodule, and commit the updated gitlink in the parent repo rather than trying to recover the exact original SHA.
- Where possible, have the submodule’s maintainers keep rewritten history reachable from a tag or an archive branch for some transition period, so parent repos pinning an older commit have time to update before the object is actually pruned.
🚨 Why This Is Dangerous
- A broken submodule reference can silently fail a fresh clone or CI checkout with an error that looks unrelated to any recent change in the parent repo, since the parent’s own commit history never changed — only the submodule’s did, somewhere else entirely.
A submodule reference is a promise that one exact commit will still be there when you ask for it — and that promise is only as good as the submodule repository’s willingness to never rewrite past it.
