Over the past weeks, I ran into something small but surprisingly persistent: Git submodules that nobody uses anymore, but are still quietly hiding in the codebase.
Submodules that:
- were added years ago,
- are no longer referenced anywhere,
- still appear in .gitmodules,
- confuse developers and clutter builds,
- and sometimes even pose an attack surface.
I looked for a simple tool that could automatically detect unused / “ghost” submodules…
But I couldn’t find one that quickly.
So I built one 😛
Introducing ghostbuster-submodules
- A small Python tool that:Reads .gitmodules / .submodules
- Scans your entire repository
- Detects which submodules are still actively referenced
- Flags the ones that are truly dead (ghosts)
- Handles Windows + Linux
- Provides proper exit codes for CI/CD
- Even detects self-references inside submodules
Repository: https://github.com/mkleinman64/ghostbuster-submodules
Usage:
python3 ghostbuster-submodules.py <path_to_git_repository>
During scanning it will show something like this:
Scanning directory: /home/repository .Valid submodules file found: /home/repository/.submodules submodules: - Shared/Schema_SomeProject - Shared/AndAnotherModule References found: Submodule path: Shared/Schema_SomeProject (no references found!) <-- GHOST!!! Submodule path: Shared/AndAnotherModule -> ProxyServices/test.java Very satisfying cleanup. Ghosts busted.
If you work with large Git repositories or long-lived enterprise codebases, feel free to try it out, give feedback, or share ideas.
Happy to improve it further.