Git submodules as a package manager

Andrew Nesbitt got there through a small annoyance. He added a worktree, ran git submodule update --init in it, and then git worktree remove refused. The man page gives submodules their own clause next to dirty state: removing such a worktree needs --force, and git worktree move won't move one at all. The caveat has been there since git worktree arrived in git 2.5 in July 2015, and worktree add later had to be patched to ignore submodule.recurse because honouring it made its internal reset --hard recurse into empty submodule paths.

That led him to read submodules as a package manager. Most of the parts exist. A gitlink, a commit SHA recorded at a path with mode 160000, is the lockfile entry. `.gitmodules`, mapping paths to URLs, is the manifest. git submodule update is the install step. The pin is as exact as any lockfile's. Almost every other step is worse than in a real package manager.

Resolution

A gitlink says which commit to check out, and the URL in .gitmodules says where to get it. There is no other resolution mechanism. If the upstream is renamed, moved to another host or made private, every pin to it breaks, even though the SHA hasn't changed and the objects exist in every clone that already has them.

On top of that, git submodule init copies each URL into .git/config, and later commands read it from there. Changing .gitmodules to point at a mirror does nothing for an existing clone until git submodule sync. In CI the usual workaround is a global url.<base>.insteadOf rewrite, for example GitHub HTTPS to SSH so a deploy key applies.

This is where cursed-bundler-go-get-ruby-gems makes a useful contrast: Golang's module proxy is exactly the lookup from a content identity to servers holding it that submodules lack.

Installation

A plain clone records the gitlink and leaves the directory empty until git submodule update --init or --recurse-submodules. The submodule.recurse setting, which makes checkout, fetch, pull and grep recurse, defaults to off. update checks out the pinned commit detached; --remote checks out the tip of the tracked branch instead, so one command name covers both "install what's pinned" and "upgrade to latest".

Switching superproject branches updates the gitlink but leaves the submodule's working tree behind, and git status immediately shows it as modified. The Rust project's June 2026 write-up on moving compiler subprojects off submodules lists the resulting problems from experience: empty or wrong checkouts after clone, unrelated submodule bumps slipping into pull requests after a branch switch, and custom logic in bootstrap to put each submodule on the right commit before building.

Storage

A submodule's git directory lives under $GIT_DIR/modules/<name>/, with its own refs, index, config, hooks and by default its own object store; the working tree has a .git file pointing back. Removal takes three steps: git rm, git submodule deinit, and a documented manual rm -rf of the leftover modules directory.

This layout is why worktrees and submodules collide. Linked worktrees share $GIT_DIR but have their own HEAD and index, so two worktrees on different branches reference the same submodule at different commits, over storage that is partly shared and partly per-worktree. Git asks for --force rather than working out whether that state is disposable, and move refuses because the pointer rewrite is unimplemented. After Xavier Morel asked on the git list in March 2026 whether a submodule checkout could be a worktree of a shared clone, an RFC and a three-patch series followed in April proposing git worktree add --recurse-submodules, with per-worktree submodule directories under $GIT_COMMON_DIR/worktrees/<id>/modules/ sharing objects by hardlink.

The same duplication happens without worktrees. Two submodules that depend on one repository get two module directories, two object stores unless alternates are set up by hand, and two independent pins. Cargo's registry cache, pnpm's content-addressable store and the Golang module cache store the bytes once.

Updating

Moving a pin means entering the submodule, fetching, checking out, leaving, and git add on the path; update --remote shortcuts the middle. The manifest can name a branch, but has no version ranges, tag patterns or minimum commits, so a branch is the only floating reference. Dependabot's gitsubmodule ecosystem and Renovate's git-submodules manager (disabled by default) both follow branch tips for that reason. The range semantics other package managers argue about, covered in default-version-bound-constraints, don't exist here at all.

Security

.gitmodules is controlled by the upstream and parsed during clone --recurse-submodules before the user has seen anything, and that has produced remote code execution repeatedly. CVE-2018-11235 used ../ in a submodule name to write its git directory, hooks included, outside modules/. CVE-2018-17456 used a URL starting with -, which the child clone parsed as an option. CVE-2022-39253 used a symlinked object directory to copy local files during a local-transport clone, and the fix made protocol.file.allow default to user. CVE-2024-32002 combined a symlink with a case-insensitive filesystem to write a hook into .git/. The general pattern of checkout paths as attack surface is part of supply-chain-security.

Abstraction

Submodules expose git internals directly: object IDs as pins, detached HEADs, the modules layout, transport URLs in the manifest. A package manager puts a manifest format, resolver and cache in front of the equivalent pieces. Nesbitt's list of what's missing is mostly already solved elsewhere: a shared object cache, recursion by default, one lifecycle for adding and removing, and range constraints. The April patch series addresses one storage case. He thinks resolution is the hard one: a SHA is already a host-independent identity for the content, and a URL in .gitmodules is still the only way git has to find a server that holds it. dependency-vendoring is the other way out, where the dependency's bytes live in the superproject and the question never comes up.