Re: [RFC] worktree: add --recurse-submodules support to git worktree add

[Phillip Wood <phillip.wood123@gmail.com>]

On 15/04/2026 01:14, JAM wrote:
> Back in 2022, Glen Choo noted [1] that git worktree add leaves submodules
> unhandled and suggested a --recurse-submodules flag to fix that. The thread
> went quiet. The 2015–2016 discussions by Duy and Beller [2][3] had flagged a
> deeper design concern: submodule existence (which worktrees have which
> submodules checked out) is tangled up with submodule configuration (URL, 
> path),
> making per-worktree submodule support tricky to reason about.
> 
> This proposal sidesteps that concern entirely. Rather than touching 
> submodule
> configuration at all, the idea is to reuse the git object data that's 
> already
> present in the main repository — the same thing git worktree add already 
> does
> for the top-level object store, extended down to the submodule layer.

I'm not really a submodule user so maybe I'm missing something. 
Worktrees separate out per-worktree data such as refs like HEAD which 
are stored under the worktree's gitdir in 
"$GIT_COMMON_DIR/worktrees/$id" and per-repository data such as the 
object store which is stored under "$GIT_COMMON_DIR". The proposal below 
appears to use the same modules directory for each worktree so if I have 
two worktrees A and B each with a submodule "sub" how can I checkout 
commit C1 in "A/sub" and commit C2 in "B/sub" when they share the same 
gitdir? It makes sense for "A/sub" and "B/sub" to share the same object 
database, but they don't want to share the same HEAD.

Thanks

Phillip


> 
> The use case has also grown more pressing: multi-agent development workflows
> (where several autonomous coding agents work concurrently on different 
> branches
> of the same repository) rely heavily on worktrees for isolation, and 
> fall apart
> on projects with submodules.
> 
> Concretely, git worktree add --recurse-submodules would:
> 
> 1. Hardlink $GIT_COMMON_DIR/modules/ into the new worktree's entry.
> Independent directory trees, shared inodes — no extra disk, no network.
> 2. Rewrite core.worktree in the hardlinked config and config.worktree
> files to point at the new worktree's working directory instead of the main
> repo's.
> 3. Run git submodule update inside the new worktree to write the .git
> pointer files into each submodule directory. Entirely local since the
> modules directory is already there.
> 4. Populate working trees with git read-tree HEAD && git checkout -- . per
> submodule, since the hardlinked index files start empty.
> 
> A shell script implementing this as a prototype is attached.
> 
> The worktreeConfig extension case (step 2) is the one place that needs care,
> since core.worktree may live in either config or config.worktree
> depending on the submodule. The prototype handles both. The other open 
> question
> is policy for submodules not yet initialized in the main repo — skip 
> silently,
> warn, or error out.
> 
> Would there be interest in a proper patch series for this?
> 
> [1] https://lore.kernel.org/git/kl6lwnimyxbq.fsf@chooglen- 
> macbookpro.roam.corp.google.com/ <https://lore.kernel.org/git/ 
> kl6lwnimyxbq.fsf@chooglen-macbookpro.roam.corp.google.com/>
> [2] https://lore.kernel.org/git/CACsJy8D8Ur4W348t- 
> WFUPrb7SQxmff5MJ4aRp+w+ZiQ7VVvipg@mail.gmail.com/ <https:// 
> lore.kernel.org/git/CACsJy8D8Ur4W348t- 
> WFUPrb7SQxmff5MJ4aRp+w+ZiQ7VVvipg@mail.gmail.com/>
> [3] https://lore.kernel.org/git/CAGZ79kZB8U+ERNeYpZ- 
> i7Ldip7xbz0ND53g4bzMkzFC3pnyv+w@mail.gmail.com/ <https:// 
> lore.kernel.org/git/CAGZ79kZB8U+ERNeYpZ- 
> i7Ldip7xbz0ND53g4bzMkzFC3pnyv+w@mail.gmail.com/>
> 
> Signed-off-by: Jimmy Aguilar kratsbinovish@gmail.com 
> <mailto:kratsbinovish@gmail.com>