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

[JAM <kratsbinovish@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 2526 bytes --]

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.

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/
[2]
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/

Signed-off-by: Jimmy Aguilar kratsbinovish@gmail.com

[-- Attachment #1.2: Type: text/html, Size: 3014 bytes --]

[-- Attachment #2: create-worktree.sh --]
[-- Type: application/x-shellscript, Size: 4936 bytes --]