{"thread":{"id":"65486","subject":"[RFC] worktree: add --recurse-submodules support to git worktree add","startedAt":"2026-04-15T00:14:56Z","lastAt":"2026-04-15T16:23:30Z","messageCount":3,"participants":["JAM","Phillip Wood","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"541608","messageId":"CAPSFGa8uu9CEEPH3XVjfN5VEOfcnb2p8YgXVuansjKc0S2S_tA@mail.gmail.com","threadId":"65486","inReplyTo":null,"subject":"[RFC] worktree: add --recurse-submodules support to git worktree add","fromName":"JAM","fromEmail":"kratsbinovish@gmail.com","sentAt":"2026-04-15T00:14:43Z","receivedAt":"2026-04-15T00:14:56Z","isPatch":false,"body":"Back in 2022, Glen Choo noted [1] that git worktree add leaves submodules\nunhandled and suggested a --recurse-submodules flag to fix that. The thread\nwent quiet. The 2015–2016 discussions by Duy and Beller [2][3] had flagged a\ndeeper design concern: submodule existence (which worktrees have which\nsubmodules checked out) is tangled up with submodule configuration (URL,\npath),\nmaking per-worktree submodule support tricky to reason about.\n\nThis proposal sidesteps that concern entirely. Rather than touching\nsubmodule\nconfiguration at all, the idea is to reuse the git object data that's\nalready\npresent in the main repository — the same thing git worktree add already\ndoes\nfor the top-level object store, extended down to the submodule layer.\n\nThe use case has also grown more pressing: multi-agent development workflows\n(where several autonomous coding agents work concurrently on different\nbranches\nof the same repository) rely heavily on worktrees for isolation, and fall\napart\non projects with submodules.\n\nConcretely, git worktree add --recurse-submodules would:\n\n1. Hardlink $GIT_COMMON_DIR/modules/ into the new worktree's entry.\nIndependent directory trees, shared inodes — no extra disk, no network.\n2. Rewrite core.worktree in the hardlinked config and config.worktree\nfiles to point at the new worktree's working directory instead of the main\nrepo's.\n3. Run git submodule update inside the new worktree to write the .git\npointer files into each submodule directory. Entirely local since the\nmodules directory is already there.\n4. Populate working trees with git read-tree HEAD && git checkout -- . per\nsubmodule, since the hardlinked index files start empty.\n\nA shell script implementing this as a prototype is attached.\n\nThe worktreeConfig extension case (step 2) is the one place that needs care,\nsince core.worktree may live in either config or config.worktree\ndepending on the submodule. The prototype handles both. The other open\nquestion\nis policy for submodules not yet initialized in the main repo — skip\nsilently,\nwarn, or error out.\n\nWould there be interest in a proper patch series for this?\n\n[1]\nhttps://lore.kernel.org/git/kl6lwnimyxbq.fsf@chooglen-macbookpro.roam.corp.google.com/\n[2]\nhttps://lore.kernel.org/git/CACsJy8D8Ur4W348t-WFUPrb7SQxmff5MJ4aRp+w+ZiQ7VVvipg@mail.gmail.com/\n[3]\nhttps://lore.kernel.org/git/CAGZ79kZB8U+ERNeYpZ-i7Ldip7xbz0ND53g4bzMkzFC3pnyv+w@mail.gmail.com/\n\nSigned-off-by: Jimmy Aguilar kratsbinovish@gmail.com\n"},{"id":"541657","messageId":"823d30b3-b355-430b-b8af-c8421a87b0aa@gmail.com","threadId":"65486","inReplyTo":"CAPSFGa8uu9CEEPH3XVjfN5VEOfcnb2p8YgXVuansjKc0S2S_tA@mail.gmail.com","subject":"Re: [RFC] worktree: add --recurse-submodules support to git worktree add","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2026-04-15T14:05:07Z","receivedAt":"2026-04-15T14:05:11Z","isPatch":false,"body":"On 15/04/2026 01:14, JAM wrote:\n> Back in 2022, Glen Choo noted [1] that git worktree add leaves submodules\n> unhandled and suggested a --recurse-submodules flag to fix that. The thread\n> went quiet. The 2015–2016 discussions by Duy and Beller [2][3] had flagged a\n> deeper design concern: submodule existence (which worktrees have which\n> submodules checked out) is tangled up with submodule configuration (URL, \n> path),\n> making per-worktree submodule support tricky to reason about.\n> \n> This proposal sidesteps that concern entirely. Rather than touching \n> submodule\n> configuration at all, the idea is to reuse the git object data that's \n> already\n> present in the main repository — the same thing git worktree add already \n> does\n> for the top-level object store, extended down to the submodule layer.\n\nI'm not really a submodule user so maybe I'm missing something. \nWorktrees separate out per-worktree data such as refs like HEAD which \nare stored under the worktree's gitdir in \n\"$GIT_COMMON_DIR/worktrees/$id\" and per-repository data such as the \nobject store which is stored under \"$GIT_COMMON_DIR\". The proposal below \nappears to use the same modules directory for each worktree so if I have \ntwo worktrees A and B each with a submodule \"sub\" how can I checkout \ncommit C1 in \"A/sub\" and commit C2 in \"B/sub\" when they share the same \ngitdir? It makes sense for \"A/sub\" and \"B/sub\" to share the same object \ndatabase, but they don't want to share the same HEAD.\n\nThanks\n\nPhillip\n\n\n> \n> The use case has also grown more pressing: multi-agent development workflows\n> (where several autonomous coding agents work concurrently on different \n> branches\n> of the same repository) rely heavily on worktrees for isolation, and \n> fall apart\n> on projects with submodules.\n> \n> Concretely, git worktree add --recurse-submodules would:\n> \n> 1. Hardlink $GIT_COMMON_DIR/modules/ into the new worktree's entry.\n> Independent directory trees, shared inodes — no extra disk, no network.\n> 2. Rewrite core.worktree in the hardlinked config and config.worktree\n> files to point at the new worktree's working directory instead of the main\n> repo's.\n> 3. Run git submodule update inside the new worktree to write the .git\n> pointer files into each submodule directory. Entirely local since the\n> modules directory is already there.\n> 4. Populate working trees with git read-tree HEAD && git checkout -- . per\n> submodule, since the hardlinked index files start empty.\n> \n> A shell script implementing this as a prototype is attached.\n> \n> The worktreeConfig extension case (step 2) is the one place that needs care,\n> since core.worktree may live in either config or config.worktree\n> depending on the submodule. The prototype handles both. The other open \n> question\n> is policy for submodules not yet initialized in the main repo — skip \n> silently,\n> warn, or error out.\n> \n> Would there be interest in a proper patch series for this?\n> \n> [1] https://lore.kernel.org/git/kl6lwnimyxbq.fsf@chooglen- \n> macbookpro.roam.corp.google.com/ kl6lwnimyxbq.fsf@chooglen-macbookpro.roam.corp.google.com/>\n> [2] https://lore.kernel.org/git/CACsJy8D8Ur4W348t- \n> WFUPrb7SQxmff5MJ4aRp+w+ZiQ7VVvipg@mail.gmail.com/ lore.kernel.org/git/CACsJy8D8Ur4W348t- \n> WFUPrb7SQxmff5MJ4aRp+w+ZiQ7VVvipg@mail.gmail.com/>\n> [3] https://lore.kernel.org/git/CAGZ79kZB8U+ERNeYpZ- \n> i7Ldip7xbz0ND53g4bzMkzFC3pnyv+w@mail.gmail.com/ lore.kernel.org/git/CAGZ79kZB8U+ERNeYpZ- \n> i7Ldip7xbz0ND53g4bzMkzFC3pnyv+w@mail.gmail.com/>\n> \n> Signed-off-by: Jimmy Aguilar kratsbinovish@gmail.com \n> \n\n"},{"id":"541673","messageId":"xmqq1pgg8a68.fsf@gitster.g","threadId":"65486","inReplyTo":"823d30b3-b355-430b-b8af-c8421a87b0aa@gmail.com","subject":"Re: [RFC] worktree: add --recurse-submodules support to git worktree add","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-04-15T16:23:27Z","receivedAt":"2026-04-15T16:23:30Z","isPatch":false,"body":"Phillip Wood writes:\n\n> On 15/04/2026 01:14, JAM wrote:\n>> Back in 2022, Glen Choo noted [1] that git worktree add leaves submodules\n>> unhandled and suggested a --recurse-submodules flag to fix that. The thread\n>> went quiet. The 2015–2016 discussions by Duy and Beller [2][3] had flagged a\n>> deeper design concern: submodule existence (which worktrees have which\n>> submodules checked out) is tangled up with submodule configuration (URL, \n>> path),\n>> making per-worktree submodule support tricky to reason about.\n>> \n>> This proposal sidesteps that concern entirely. Rather than touching \n>> submodule\n>> configuration at all, the idea is to reuse the git object data that's \n>> already\n>> present in the main repository — the same thing git worktree add already \n>> does\n>> for the top-level object store, extended down to the submodule layer.\n>\n> I'm not really a submodule user so maybe I'm missing something. \n> Worktrees separate out per-worktree data such as refs like HEAD which \n> are stored under the worktree's gitdir in \n> \"$GIT_COMMON_DIR/worktrees/$id\" and per-repository data such as the \n> object store which is stored under \"$GIT_COMMON_DIR\". The proposal below \n> appears to use the same modules directory for each worktree so if I have \n> two worktrees A and B each with a submodule \"sub\" how can I checkout \n> commit C1 in \"A/sub\" and commit C2 in \"B/sub\" when they share the same \n> gitdir? It makes sense for \"A/sub\" and \"B/sub\" to share the same object \n> database, but they don't want to share the same HEAD.\n\nTrue. I am not a submodule user and do not have a strong interest\nin submodules, but I agree that once the superproject wants to use\nmultiple worktrees, the submodules bound to it inevitably need to\nuse different worktrees that correspond to the worktrees used by the\nsuperproject exactly because of the point you raise here. They need\nto be able to independently check out a suitable commit in the\ncontext of the superproject's worktree that is checked out.\n\n\n"}]}