threads / bug / 66859

submodule: linked-worktree submodule hits BUG() in validate_submodule_legacy_git_dir()

Subject: submodule: linked-worktree submodule hits BUG() in validate_submodule_legacy_git_dir()

## tl;dr

A reproducible abort in validate_submodule_legacy_git_dir() affects superproject worktrees whose submodule is itself a linked worktree. Read the story.

replies: 12people: 3as markdown or json

Andreas Wendleder· Nov 16, 2026, 22:51 UTC · lore

With submodule.recurse=true, switching branches in a superproject worktree whose submodule is itself a linked worktree of the submodule repository aborts:

  BUG: submodule.c:2414: submodule name 'sub' not a suffix of git dir
  '.../.git/modules/sub/worktrees/sub1'
Reproduction (git 2.56.0; the code is the same on master, next and seen):
  #!/bin/sh
  set -e
  export GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1
  g() { git -c user.name=t -c user.email=t@t -c protocol.file.allow=always "$@"; }
  rm -rf w && mkdir w && cd w
  g init -q -b main sub && g -C sub commit -q --allow-empty -m s1
  g init -q -b main super && cd super
  g submodule add -q ../sub sub && g commit -q -m add
  g -C sub commit -q --allow-empty -m s2 && g add sub && g commit -q -m bump
  g branch other HEAD~1
  g worktree add -q --detach ../wt main
  g -C sub worktree add -q --detach ../../other/sub HEAD  # takes the name 'sub'
  g -C sub worktree add -q --detach ../../wt/sub HEAD     # so this one is 'sub1'
  cd ../wt
  g -c submodule.recurse=true switch other

submodule_move_head() expects validate_submodule_git_dir() to return < 0 and then dies with "refusing to create/use ... Enabling extensions.submodulePathConfig should fix this", but without the extension validate_submodule_legacy_git_dir() calls BUG() instead. A linked worktree's git dir (modules/<name>/worktrees/<id>) never ends in the submodule name, so this setup always hits it.

With extensions.submodulePathConfig enabled (repositoryformatversion 1), the same commands no longer crash but die with the "refusing to create/use ..." message, which recommends enabling the extension that is already enabled.

I would expect a linked worktree of a submodule's repository to be accepted as the submodule's git dir. If it is meant to be rejected, the legacy path should return an error instead of calling BUG(), and the hint should not suggest the extension when it is already on.

Adrian Ratiu· Nov 17, 2026, 17:45 UTC · re: Andreas Wendleder · lore

Re: submodule: linked-worktree submodule hits BUG() in validate_submodule_legacy_git_dir()

Hi Andreas,
On Mon, 16 Nov 2026, Andreas Wendleder <gonsolo@gmail.com> wrote:
Show 6 quoted lines
> With submodule.recurse=true, switching branches in a superproject worktree
> whose submodule is itself a linked worktree of the submodule repository
> aborts:
>
>   BUG: submodule.c:2414: submodule name 'sub' not a suffix of git dir
>   '.../.git/modules/sub/worktrees/sub1'
Thanks for reporting this and for the reproducer.

The BUG() is older than submodulePathConfig. Users could not reach it before 9cf8547320 (clone: prevent clashing git dirs when cloning submodule in parallel, 2024-01-28), which made submodule_move_head() validate whatever path the submodule's gitfile points to. A path read from disk can be anything, so it should never hit a BUG().

Your reproducer needs the second worktree because the gitdir ".../sub" happens to end in the submodule name, so the check passes by accident.

t2405 sets up exactly this layout but never runs a recursvie checkout.
I'll send a fix.
Show 9 quoted lines
> With extensions.submodulePathConfig enabled (repositoryformatversion 1),
> the same commands no longer crash but die with the "refusing to create/use
> ..." message, which recommends enabling the extension that is already
> enabled.
>
> I would expect a linked worktree of a submodule's repository to be
> accepted as the submodule's git dir. If it is meant to be rejected, the
> legacy path should return an error instead of calling BUG(), and the hint
> should not suggest the extension when it is already on.
Yes, the hint is actually my mistake.

I have a local fix which I need to test a bit more, but makes your script switch cleanly in both modes and the main submodule checkout isn't touched.

Will send it in the next few days with you in Reported-by.

Thanks again, Adrian

Adrian Ratiu· Nov 18, 2026, 16:32 UTC · re: Andreas Wendleder · lore

[PATCH 0/3] submodule: support linked worktrees in recursive checkout

Hello all,

This fixes a few submodule bugs reported by Andreas at: https://lore.kernel.org/git/avuJBGlB3pRU3JU0@pampelmuse/

In short: when a submodule is a linked worktree of its repository ("git worktree add" inside the submodule), a recursive checkout in the superproject either crashes with a BUG() or leaves the submodule broken.

The patches should be self-explanatory, many thanks to Andreas for reporting and sharing a reproducer.

Regards, Adrian

Adrian Ratiu (3):
  submodule: return an error instead of BUG() for an unexpected git dir
  submodule: only suggest submodulePathConfig when it is disabled
  submodule: accept a linked worktree as the submodule's git dir
 submodule.c                                | 72 +++++++++++++++++++---
 t/t2405-worktree-submodule.sh              | 40 ++++++++++++
 t/t7425-submodule-gitdir-path-extension.sh | 14 +++++
 t/t7450-bad-git-dotfiles.sh                | 31 ++++++++++
 4 files changed, 148 insertions(+), 9 deletions(-)
base-commit: e1ec09b23c8e0deb21a0b95ac5996422277395d4
-- 
2.56.1
Adrian Ratiu· Nov 18, 2026, 16:32 UTC · re: Adrian Ratiu · lore

[PATCH 1/3] submodule: return an error instead of BUG() for an unexpected git dir

During a recursive checkout, Git reads a submodule's .git file to find its git dir and checks that the path ends in the submodule's name, e.g. ".git/modules/sub" for a submodule called "sub".

Without extensions.submodulePathConfig, a path that does not end that way triggers a BUG() and aborts the command:

  BUG: submodule.c:2414: submodule name 'sub' not a suffix of git dir '...'

This path comes from a file on disk, not from Git's own code, so an unexpected value is a problem with the user's setup, not a bug in Git. It can happen when the git dir under .git/modules has been renamed or the submodule is a linked worktree (handled in a later commit).

When the check was added in a8dee3ca61 (Disallow dubiously-nested submodule git directories, 2019-10-01), its callers only passed git dirs computed by Git from the submodule name, so BUG() was correct.

9cf8547320 (clone: prevent clashing git dirs when cloning submodule in parallel, 2024-01-28) added a caller that passes a path read from the gitfile, which made the BUG() reachable.

Return an error instead of BUG(), so the command dies with the same "refusing to create/use ..." message as when the submodulePathConfig extension is enabled.

Reported-by: Andreas Wendleder <gonsolo@gmail.com>
Signed-off-by: Adrian Ratiu <adrian.ratiu@collabora.com>
---
 submodule.c                 |  8 ++++++--
 t/t7450-bad-git-dotfiles.sh | 14 ++++++++++++++
 2 files changed, 20 insertions(+), 2 deletions(-)
diff --git a/submodule.c b/submodule.c
index 1302c11ddf..d00d820d42 100644
--- a/submodule.c
+++ b/submodule.c
@@ -2410,10 +2410,14 @@ static int validate_submodule_legacy_git_dir(char *git_dir, const char *submodul
 		BUG("validate_submodule_git_dir() must be called with "
 		    "extensions.submodulePathConfig disabled.");
 
+	/*
+	 * The git dir may come from a gitfile on disk, so a mismatch is
+	 * not necessarily a bug in the caller.
+	 */
 	if (len <= suffix_len || (p = git_dir + len - suffix_len)[-1] != '/' ||
 	    strcmp(p, submodule_name))
-		BUG("submodule name '%s' not a suffix of git dir '%s'",
-		    submodule_name, git_dir);
+		return error(_("submodule name '%s' not a suffix of git dir '%s'"),
+			     submodule_name, git_dir);
 
 	/*
 	 * We prevent the contents of sibling submodules' git directories to
diff --git a/t/t7450-bad-git-dotfiles.sh b/t/t7450-bad-git-dotfiles.sh
index 72c7f6f73b..e17642fc16 100755
--- a/t/t7450-bad-git-dotfiles.sh
+++ b/t/t7450-bad-git-dotfiles.sh
@@ -380,6 +380,20 @@ test_expect_success 'checkout -f --recurse-submodules must not use a nested gitd
 	test_path_is_missing nested_checkout/thing2/.git
 '
 
+test_expect_success 'checkout --recurse-submodules rejects gitfile not matching submodule name' '
+	git clone nested mismatched_gitdir &&
+	(
+		cd mismatched_gitdir &&
+		git submodule init thing1 &&
+		git submodule update thing1 &&
+		mv .git/modules/hippo .git/modules/elephant &&
+		echo "gitdir: ../.git/modules/elephant" >thing1/.git
+	) &&
+	test_must_fail git -C mismatched_gitdir checkout -f --recurse-submodules HEAD 2>err &&
+	test_grep "not a suffix of git dir" err &&
+	test_grep ! "BUG" err
+'
+
 test_expect_success SYMLINKS,!WINDOWS,!MINGW 'submodule must not checkout into different directory' '
 	test_when_finished "rm -rf sub repo bad-clone" &&
 
-- 
2.56.1
Junio C Hamano· Nov 18, 2026, 19:15 UTC · re: Adrian Ratiu · lore

Re: [PATCH 1/3] submodule: return an error instead of BUG() for an unexpected git dir

Adrian Ratiu <adrian.ratiu@collabora.com> writes:
Show 7 quoted lines
> 9cf8547320 (clone: prevent clashing git dirs when cloning submodule in
> parallel, 2024-01-28) added a caller that passes a path read from the
> gitfile, which made the BUG() reachable.
>
> Return an error instead of BUG(), so the command dies with the same
> "refusing to create/use ..." message as when the submodulePathConfig
> extension is enabled.
Makes sense.

The above archaeology was quite illuminating. It seems that the offending commit came without the usual on-list reviews as part of the Git 2.39.4/2.45.1 updates.

Show 19 quoted lines
> Reported-by: Andreas Wendleder <gonsolo@gmail.com>
> Signed-off-by: Adrian Ratiu <adrian.ratiu@collabora.com>
> ---
>  submodule.c                 |  8 ++++++--
>  t/t7450-bad-git-dotfiles.sh | 14 ++++++++++++++
>  2 files changed, 20 insertions(+), 2 deletions(-)
>
> diff --git a/submodule.c b/submodule.c
> index 1302c11ddf..d00d820d42 100644
> --- a/submodule.c
> +++ b/submodule.c
> @@ -2410,10 +2410,14 @@ static int validate_submodule_legacy_git_dir(char *git_dir, const char *submodul
>  		BUG("validate_submodule_git_dir() must be called with "
>  		    "extensions.submodulePathConfig disabled.");
>  
> +	/*
> +	 * The git dir may come from a gitfile on disk, so a mismatch is
> +	 * not necessarily a bug in the caller.
> +	 */

"is not necessarily a bug" is not incorrect per se, but it is only relevant in the context of turning what was originally a BUG() into a "return error()". If this had been written to return an error instead of calling BUG() from the beginning, you would not have phrased the comment that way.

If this if() statement needs a comment, we should state why these two are expected to match, or why it is an error if they do not match.

Show 6 quoted lines
>  	if (len <= suffix_len || (p = git_dir + len - suffix_len)[-1] != '/' ||
>  	    strcmp(p, submodule_name))
> -		BUG("submodule name '%s' not a suffix of git dir '%s'",
> -		    submodule_name, git_dir);
> +		return error(_("submodule name '%s' not a suffix of git dir '%s'"),
> +			     submodule_name, git_dir);
Adrian Ratiu· Nov 18, 2026, 19:33 UTC · re: Junio C Hamano · lore

Re: [PATCH 1/3] submodule: return an error instead of BUG() for an unexpected git dir

On Wed, 18 Nov 2026, Junio C Hamano <gitster@pobox.com> wrote:
Show 15 quoted lines
> Adrian Ratiu <adrian.ratiu@collabora.com> writes:
>
>> 9cf8547320 (clone: prevent clashing git dirs when cloning submodule in
>> parallel, 2024-01-28) added a caller that passes a path read from the
>> gitfile, which made the BUG() reachable.
>>
>> Return an error instead of BUG(), so the command dies with the same
>> "refusing to create/use ..." message as when the submodulePathConfig
>> extension is enabled.
>
> Makes sense.
>
> The above archaeology was quite illuminating.  It seems that the
> offending commit came without the usual on-list reviews as part of
> the Git 2.39.4/2.45.1 updates.

Yeah, I wasn't part of discussions on this, so I don't have the full context either, but I do think switching BUG() -> error() makes sense.

Show 29 quoted lines
>> Reported-by: Andreas Wendleder <gonsolo@gmail.com>
>> Signed-off-by: Adrian Ratiu <adrian.ratiu@collabora.com>
>> ---
>>  submodule.c                 |  8 ++++++--
>>  t/t7450-bad-git-dotfiles.sh | 14 ++++++++++++++
>>  2 files changed, 20 insertions(+), 2 deletions(-)
>>
>> diff --git a/submodule.c b/submodule.c
>> index 1302c11ddf..d00d820d42 100644
>> --- a/submodule.c
>> +++ b/submodule.c
>> @@ -2410,10 +2410,14 @@ static int validate_submodule_legacy_git_dir(char *git_dir, const char *submodul
>>  		BUG("validate_submodule_git_dir() must be called with "
>>  		    "extensions.submodulePathConfig disabled.");
>>  
>> +	/*
>> +	 * The git dir may come from a gitfile on disk, so a mismatch is
>> +	 * not necessarily a bug in the caller.
>> +	 */
>
> "is not necessarily a bug" is not incorrect per se, but it is only
> relevant in the context of turning what was originally a BUG() into
> a "return error()".  If this had been written to return an error
> instead of calling BUG() from the beginning, you would not have
> phrased the comment that way.
>
> If this if() statement needs a comment, we should state why these
> two are expected to match, or why it is an error if they do not
> match.
Good point.

I'll drop the comment addition in v2 since we don't need to over-explain the BUG() -> error() transition.

Adrian Ratiu· Nov 18, 2026, 16:32 UTC · re: Adrian Ratiu · lore

[PATCH 2/3] submodule: only suggest submodulePathConfig when it is disabled

When a recursive checkout refuses to use a submodule's git dir, the error message ends with:

  Enabling extensions.submodulePathConfig should fix this.

This is printed even when the extension is already enabled, which is confusing: the user is told to turn on something that is already on.

Move the suggestion into a separate hint, as submodule_name_to_gitdir() already does, and only show it when the extension is disabled.

Reported-by: Andreas Wendleder <gonsolo@gmail.com>
Signed-off-by: Adrian Ratiu <adrian.ratiu@collabora.com>
---
 submodule.c                                | 10 ++++++----
 t/t7425-submodule-gitdir-path-extension.sh | 14 ++++++++++++++
 t/t7450-bad-git-dotfiles.sh                |  1 +
 3 files changed, 21 insertions(+), 4 deletions(-)
diff --git a/submodule.c b/submodule.c
index d00d820d42..64cd8005f7 100644
--- a/submodule.c
+++ b/submodule.c
@@ -2171,11 +2171,13 @@ int submodule_move_head(const char *path, const char *super_prefix,
 
 				free(dotgit);
 				if (validate_submodule_git_dir(git_dir,
-							       sub->name) < 0)
+							       sub->name) < 0) {
+					if (!the_repository->repository_format_submodule_path_cfg)
+						advise(_("enabling extensions.submodulePathConfig "
+							 "might fix the following error."));
 					die(_("refusing to create/use '%s' in "
-					      "another submodule's git dir. "
-					      "Enabling extensions.submodulePathConfig "
-					      "should fix this."), git_dir);
+					      "another submodule's git dir."), git_dir);
+				}
 				free(git_dir);
 			}
 		} else {
diff --git a/t/t7425-submodule-gitdir-path-extension.sh b/t/t7425-submodule-gitdir-path-extension.sh
index ea86ecf7ee..80438a7231 100755
--- a/t/t7425-submodule-gitdir-path-extension.sh
+++ b/t/t7425-submodule-gitdir-path-extension.sh
@@ -525,4 +525,18 @@ test_expect_success 'submodule gitdir conflicts with previously encoded name (lo
 	)
 '
 
+test_expect_success 'rejected submodule gitfile does not suggest enabling the extension' '
+	git clone -c extensions.submodulePathConfig=true --recurse-submodules nested clone_moved_gitdir &&
+	(
+		cd clone_moved_gitdir &&
+		mkdir .git/modules/zoo &&
+		mv .git/modules/hippo .git/modules/zoo/hippo &&
+		git config set -f .git/modules/zoo/hippo/config core.worktree ../../../../thing1 &&
+		echo "gitdir: ../.git/modules/zoo/hippo" >thing1/.git
+	) &&
+	test_must_fail git -C clone_moved_gitdir checkout -f --recurse-submodules HEAD 2>err &&
+	test_grep "refusing to create/use" err &&
+	test_grep ! "extensions.submodulePathConfig" err
+'
+
 test_done
diff --git a/t/t7450-bad-git-dotfiles.sh b/t/t7450-bad-git-dotfiles.sh
index e17642fc16..a710c05a5d 100755
--- a/t/t7450-bad-git-dotfiles.sh
+++ b/t/t7450-bad-git-dotfiles.sh
@@ -391,6 +391,7 @@ test_expect_success 'checkout --recurse-submodules rejects gitfile not matching
 	) &&
 	test_must_fail git -C mismatched_gitdir checkout -f --recurse-submodules HEAD 2>err &&
 	test_grep "not a suffix of git dir" err &&
+	test_grep "enabling extensions.submodulePathConfig" err &&
 	test_grep ! "BUG" err
 '
 
-- 
2.56.1
Junio C Hamano· Nov 18, 2026, 19:28 UTC · re: Adrian Ratiu · lore

Re: [PATCH 2/3] submodule: only suggest submodulePathConfig when it is disabled

Adrian Ratiu <adrian.ratiu@collabora.com> writes:
Show 7 quoted lines
> When a recursive checkout refuses to use a submodule's git dir, the
> error message ends with:
>
>   Enabling extensions.submodulePathConfig should fix this.
>
> This is printed even when the extension is already enabled, which is
> confusing: the user is told to turn on something that is already on.
The motivation sounds sensible.
> Move the suggestion into a separate hint, as submodule_name_to_gitdir()
> already does, and only show it when the extension is disabled.
Hmph, but submodule_name_to_gitdir() does
	/* validate because users might have modified the config */
	if (validate_submodule_git_dir(buf->buf, submodule_name)) {
		advise(_("enabling extensions.submodulePathConfig might fix the "
			 "following error, if it's not already enabled."));
		die(_("refusing to create/use '%s' in another submodule's "
		      " git dir."), buf->buf);
	}

which does not really check if it is enabled; it just hedges the message by using "might fix ... if it's not" and lets the users do the work themselves, which is not necessarily a bad approach to take to simplify our job.

Similarly, builtin/submodule--helper.c:clone_submodule(), which is another caller of validate_submodule_git_dir(), has an unconditional "Enabling ... should fix this" message, which we may want to give a similar treatment.

Show 27 quoted lines
> Reported-by: Andreas Wendleder <gonsolo@gmail.com>
> Signed-off-by: Adrian Ratiu <adrian.ratiu@collabora.com>
> ---
>  submodule.c                                | 10 ++++++----
>  t/t7425-submodule-gitdir-path-extension.sh | 14 ++++++++++++++
>  t/t7450-bad-git-dotfiles.sh                |  1 +
>  3 files changed, 21 insertions(+), 4 deletions(-)
>
> diff --git a/submodule.c b/submodule.c
> index d00d820d42..64cd8005f7 100644
> --- a/submodule.c
> +++ b/submodule.c
> @@ -2171,11 +2171,13 @@ int submodule_move_head(const char *path, const char *super_prefix,
>  
>  				free(dotgit);
>  				if (validate_submodule_git_dir(git_dir,
> -							       sub->name) < 0)
> +							       sub->name) < 0) {
> +					if (!the_repository->repository_format_submodule_path_cfg)
> +						advise(_("enabling extensions.submodulePathConfig "
> +							 "might fix the following error."));
>  					die(_("refusing to create/use '%s' in "
> -					      "another submodule's git dir. "
> -					      "Enabling extensions.submodulePathConfig "
> -					      "should fix this."), git_dir);
> +					      "another submodule's git dir."), git_dir);
> +				}

It is not exactly a new issue, but this makes an already too deeply nested block even worse. I wonder if the entire "if not dry-run, do these" block should be moved to a private helper function to make it a bit easier to read.

Adrian Ratiu· Nov 19, 2026, 11:46 UTC · re: Junio C Hamano · lore

Re: [PATCH 2/3] submodule: only suggest submodulePathConfig when it is disabled

On Wed, 18 Nov 2026, Junio C Hamano <gitster@pobox.com> wrote:
Show 34 quoted lines
> Adrian Ratiu <adrian.ratiu@collabora.com> writes:
>
>> When a recursive checkout refuses to use a submodule's git dir, the
>> error message ends with:
>>
>>   Enabling extensions.submodulePathConfig should fix this.
>>
>> This is printed even when the extension is already enabled, which is
>> confusing: the user is told to turn on something that is already on.
>
> The motivation sounds sensible.
>
>> Move the suggestion into a separate hint, as submodule_name_to_gitdir()
>> already does, and only show it when the extension is disabled.
>
> Hmph, but submodule_name_to_gitdir() does
>
> 	/* validate because users might have modified the config */
> 	if (validate_submodule_git_dir(buf->buf, submodule_name)) {
> 		advise(_("enabling extensions.submodulePathConfig might fix the "
> 			 "following error, if it's not already enabled."));
> 		die(_("refusing to create/use '%s' in another submodule's "
> 		      " git dir."), buf->buf);
> 	}
>
> which does not really check if it is enabled; it just hedges the
> message by using "might fix ... if it's not" and lets the users do
> the work themselves, which is not necessarily a bad approach to take
> to simplify our job.
>
> Similarly, builtin/submodule--helper.c:clone_submodule(), which is
> another caller of validate_submodule_git_dir(), has an unconditional
> "Enabling ... should fix this" message, which we may want to give a
> similar treatment.
Ack, I mis-remembered that we already checked the extension.

Happy to reword as you suggested, but for v2 I'd also like to explore dropping the "hedge" and actually check in all three places, it should be a trivial helper which reads repository_format_submodule_path_cfg.

Show 32 quoted lines
>> Reported-by: Andreas Wendleder <gonsolo@gmail.com>
>> Signed-off-by: Adrian Ratiu <adrian.ratiu@collabora.com>
>> ---
>>  submodule.c                                | 10 ++++++----
>>  t/t7425-submodule-gitdir-path-extension.sh | 14 ++++++++++++++
>>  t/t7450-bad-git-dotfiles.sh                |  1 +
>>  3 files changed, 21 insertions(+), 4 deletions(-)
>>
>> diff --git a/submodule.c b/submodule.c
>> index d00d820d42..64cd8005f7 100644
>> --- a/submodule.c
>> +++ b/submodule.c
>> @@ -2171,11 +2171,13 @@ int submodule_move_head(const char *path, const char *super_prefix,
>>  
>>  				free(dotgit);
>>  				if (validate_submodule_git_dir(git_dir,
>> -							       sub->name) < 0)
>> +							       sub->name) < 0) {
>> +					if (!the_repository->repository_format_submodule_path_cfg)
>> +						advise(_("enabling extensions.submodulePathConfig "
>> +							 "might fix the following error."));
>>  					die(_("refusing to create/use '%s' in "
>> -					      "another submodule's git dir. "
>> -					      "Enabling extensions.submodulePathConfig "
>> -					      "should fix this."), git_dir);
>> +					      "another submodule's git dir."), git_dir);
>> +				}
>
> It is not exactly a new issue, but this makes an already too deeply
> nested block even worse.  I wonder if the entire "if not dry-run, do
> these" block should be moved to a private helper function to make it
> a bit easier to read.
Sure, I can add a helper here as well in v2. Thanks!
Junio C Hamano· Nov 19, 2026, 22:14 UTC · re: Adrian Ratiu · lore

Re: [PATCH 2/3] submodule: only suggest submodulePathConfig when it is disabled

Adrian Ratiu <adrian.ratiu@collabora.com> writes:
> ... dropping the "hedge" and actually check in all three places, it should
> be a trivial helper which reads repository_format_submodule_path_cfg.
Sounds super sensible.
Thanks.
Adrian Ratiu· Nov 18, 2026, 16:32 UTC · re: Adrian Ratiu · lore

[PATCH 3/3] submodule: accept a linked worktree as the submodule's git dir

A submodule's working tree can be a linked worktree of the submodule's repository, created e.g. with:

  git -C super/sub worktree add ../../wt/sub

Its .git file then points to "super/.git/modules/sub/worktrees/<id>" instead of "super/.git/modules/sub". t2405 already creates such a submodule, but it doesn't test a recursive checkout, and its worktree id happens to match the submodule name.

A recursive checkout (--recurse-submodules or submodule.recurse=true) has two problems with this setup:

 1. It checks that the git dir ends in the submodule's name. A
    worktree's git dir ends in the worktree id instead, so the check
    fails and the command dies. It only passes by chance, when the id
    is the same as the name.
 2. Even when the check passes, Git then rewrites the .git file to
    point to the git dir it would normally use for the submodule,
    "$GIT_DIR/modules/<name>" of the superproject. That is not the
    repository the worktree belongs to and it usually does not exist,
    so the submodule is left broken. Likewise, when the submodule is
    removed, Git tries to unset core.worktree in that git dir and
    prints an error and a warning.
    This happens on every recursive checkout, not only with --force,
    because unpack_trees() always passes SUBMODULE_MOVE_HEAD_FORCE to
    submodule_move_head().

Fix both: when the git dir is a linked worktree of a valid submodule git dir, i.e. it is located at "<common-dir>/worktrees/<id>", check the common dir against the submodule's name and leave the .git file and core.worktree alone. Reject a git dir that has a commondir file but is located anywhere else.

Reported-by: Andreas Wendleder <gonsolo@gmail.com>
Signed-off-by: Adrian Ratiu <adrian.ratiu@collabora.com>
---
 submodule.c                   | 56 ++++++++++++++++++++++++++++++++---
 t/t2405-worktree-submodule.sh | 40 +++++++++++++++++++++++++
 t/t7450-bad-git-dotfiles.sh   | 16 ++++++++++
 3 files changed, 108 insertions(+), 4 deletions(-)
diff --git a/submodule.c b/submodule.c
index 64cd8005f7..1bd7fb7e04 100644
--- a/submodule.c
+++ b/submodule.c
@@ -2119,6 +2119,45 @@ static void submodule_reset_index(const char *path, const char *super_prefix)
 		die(_("could not reset submodule index"));
 }
 
+/*
+ * A submodule gitfile may point to a linked worktree of the submodule
+ * repository, i.e. "<common-dir>/worktrees/<id>", whose path does not end
+ * in the submodule name. Validate the common dir in that case, after making
+ * sure that the git dir is where "git worktree add" would have put it, and
+ * die if it is not.
+ *
+ * Returns:
+ *   1 if git_dir is a valid linked worktree.
+ *   0 if it is a valid submodule git dir.
+ *   a negative value otherwise.
+ */
+static int validate_submodule_gitfile_dir(const char *git_dir,
+					  const char *submodule_name)
+{
+	struct strbuf common_dir = STRBUF_INIT;
+	struct strbuf worktree_dir = STRBUF_INIT;
+	int is_worktree, ret;
+
+	is_worktree = get_common_dir_noenv(&common_dir, git_dir);
+	if (is_worktree) {
+		const char *id;
+
+		strbuf_realpath(&worktree_dir, git_dir, 1);
+		if (!skip_prefix(worktree_dir.buf, common_dir.buf, &id) ||
+		    !skip_prefix(id, "/worktrees/", &id) ||
+		    !*id || strchr(id, '/'))
+			die(_("submodule git dir '%s' is not a worktree of '%s'"),
+			    git_dir, common_dir.buf);
+	}
+
+	ret = validate_submodule_git_dir(common_dir.buf, submodule_name);
+	if (!ret)
+		ret = is_worktree;
+	strbuf_release(&common_dir);
+	strbuf_release(&worktree_dir);
+	return ret;
+}
+
 /**
  * Moves a submodule at a given path from a given head to another new head.
  * For edge cases (a submodule coming into existence or removing a submodule)
@@ -2132,6 +2171,7 @@ int submodule_move_head(const char *path, const char *super_prefix,
 	struct child_process cp = CHILD_PROCESS_INIT;
 	const struct submodule *sub;
 	int *error_code_ptr, error_code;
+	int is_worktree = 0;
 
 	if (!is_submodule_active(the_repository, path))
 		return 0;
@@ -2170,8 +2210,9 @@ int submodule_move_head(const char *path, const char *super_prefix,
 				char *git_dir = xstrdup(read_gitfile(dotgit));
 
 				free(dotgit);
-				if (validate_submodule_git_dir(git_dir,
-							       sub->name) < 0) {
+				is_worktree = validate_submodule_gitfile_dir(git_dir,
+									     sub->name);
+				if (is_worktree < 0) {
 					if (!the_repository->repository_format_submodule_path_cfg)
 						advise(_("enabling extensions.submodulePathConfig "
 							 "might fix the following error."));
@@ -2191,7 +2232,13 @@ int submodule_move_head(const char *path, const char *super_prefix,
 			submodule_reset_index(path, super_prefix);
 		}
 
-		if (old_head && (flags & SUBMODULE_MOVE_HEAD_FORCE)) {
+		/*
+		 * Do not reconnect a linked worktree to the submodule's
+		 * main git dir: that would take over the git dir of another
+		 * working tree.
+		 */
+		if (old_head && (flags & SUBMODULE_MOVE_HEAD_FORCE) &&
+		    !is_worktree) {
 			struct strbuf gitdir = STRBUF_INIT;
 			submodule_name_to_gitdir(&gitdir, the_repository,
 						 sub->name);
@@ -2256,7 +2303,8 @@ int submodule_move_head(const char *path, const char *super_prefix,
 			if (is_empty_dir(path))
 				rmdir_or_warn(path);
 
-			submodule_unset_core_worktree(sub);
+			if (!is_worktree)
+				submodule_unset_core_worktree(sub);
 		}
 	}
 out:
diff --git a/t/t2405-worktree-submodule.sh b/t/t2405-worktree-submodule.sh
index f5c94d490b..fc5cb849de 100755
--- a/t/t2405-worktree-submodule.sh
+++ b/t/t2405-worktree-submodule.sh
@@ -59,6 +59,46 @@ test_expect_success 'submodule is checked out after manually adding submodule wo
 	test_grep "file1 updated" out
 '
 
+test_expect_success 'checkout --recurse-submodules accepts a submodule worktree' '
+	git -C main worktree add "$base_path/submodule-worktree" "$rev1_hash_main" &&
+	git -C main/sub worktree add "$base_path/submodule-worktree/sub" "$rev1_hash_sub" &&
+	cat submodule-worktree/sub/.git >expect-gitfile &&
+	# the worktree id must not end in the submodule name
+	test_grep "/worktrees/sub1$" expect-gitfile &&
+	git -C main/sub rev-parse HEAD >expect-head-main &&
+	git -C submodule-worktree checkout --recurse-submodules "$(git -C main rev-parse HEAD)" &&
+	git -C submodule-worktree rev-parse HEAD:sub >expect-head &&
+	git -C submodule-worktree/sub rev-parse HEAD >actual-head &&
+	test_cmp expect-head actual-head &&
+	cat submodule-worktree/sub/.git >actual-gitfile &&
+	test_cmp expect-gitfile actual-gitfile &&
+	git -C main/sub rev-parse HEAD >actual-head-main &&
+	test_cmp expect-head-main actual-head-main
+'
+
+test_expect_success 'checkout --recurse-submodules accepts a submodule worktree with submodulePathConfig' '
+	test_config -C main core.repositoryformatversion 1 &&
+	test_config -C main extensions.submodulePathConfig true &&
+	test_config -C main submodule.sub.gitdir .git/modules/sub &&
+	git -C submodule-worktree checkout --recurse-submodules "$rev1_hash_main" &&
+	git -C submodule-worktree/sub rev-parse --short HEAD >actual-head &&
+	echo "$rev1_hash_sub" >expect-head &&
+	test_cmp expect-head actual-head &&
+	cat submodule-worktree/sub/.git >actual-gitfile &&
+	test_cmp expect-gitfile actual-gitfile &&
+	git -C main/sub rev-parse HEAD >actual-head-main &&
+	test_cmp expect-head-main actual-head-main
+'
+
+test_expect_success 'checkout --recurse-submodules removes a submodule worktree' '
+	git -C main/sub config get core.worktree >expect-main &&
+	git -C submodule-worktree checkout --recurse-submodules first 2>err &&
+	test_grep ! "core.worktree" err &&
+	test_path_is_missing submodule-worktree/sub/.git &&
+	git -C main/sub config get core.worktree >actual-main &&
+	test_cmp expect-main actual-main
+'
+
 test_expect_success 'checkout --recurse-submodules uses $GIT_DIR for submodules in a linked worktree' '
 	git -C main worktree add "$base_path/checkout-recurse" --detach  &&
 	git -C checkout-recurse submodule update --init &&
diff --git a/t/t7450-bad-git-dotfiles.sh b/t/t7450-bad-git-dotfiles.sh
index a710c05a5d..26d442c0ad 100755
--- a/t/t7450-bad-git-dotfiles.sh
+++ b/t/t7450-bad-git-dotfiles.sh
@@ -395,6 +395,22 @@ test_expect_success 'checkout --recurse-submodules rejects gitfile not matching
 	test_grep ! "BUG" err
 '
 
+test_expect_success 'checkout --recurse-submodules rejects gitfile pointing to a forged worktree' '
+	git clone nested forged_worktree &&
+	(
+		cd forged_worktree &&
+		git submodule init thing1 &&
+		git submodule update thing1 &&
+		mkdir .git/modules/forged &&
+		cp .git/modules/hippo/HEAD .git/modules/forged/HEAD &&
+		echo "../hippo" >.git/modules/forged/commondir &&
+		echo "gitdir: ../.git/modules/forged" >thing1/.git
+	) &&
+	test_must_fail git -C forged_worktree checkout -f --recurse-submodules HEAD 2>err &&
+	test_grep "is not a worktree of" err &&
+	test_grep ! "extensions.submodulePathConfig" err
+'
+
 test_expect_success SYMLINKS,!WINDOWS,!MINGW 'submodule must not checkout into different directory' '
 	test_when_finished "rm -rf sub repo bad-clone" &&
 
-- 
2.56.1
Junio C Hamano· Nov 18, 2026, 19:52 UTC · re: Adrian Ratiu · lore

Re: [PATCH 3/3] submodule: accept a linked worktree as the submodule's git dir

Adrian Ratiu <adrian.ratiu@collabora.com> writes:
Show 9 quoted lines
> A submodule's working tree can be a linked worktree of the submodule's
> repository, created e.g. with:
>
>   git -C super/sub worktree add ../../wt/sub
>
> Its .git file then points to "super/.git/modules/sub/worktrees/<id>"
> instead of "super/.git/modules/sub". t2405 already creates such a
> submodule, but it doesn't test a recursive checkout, and its worktree
> id happens to match the submodule name.

It is tempting to say "don't do it then", but if we can cater to the use case that is great ;-)

Show 20 quoted lines
> @@ -2132,6 +2171,7 @@ int submodule_move_head(const char *path, const char *super_prefix,
>  	struct child_process cp = CHILD_PROCESS_INIT;
>  	const struct submodule *sub;
>  	int *error_code_ptr, error_code;
> +	int is_worktree = 0;
>  
>  	if (!is_submodule_active(the_repository, path))
>  		return 0;
> @@ -2170,8 +2210,9 @@ int submodule_move_head(const char *path, const char *super_prefix,
>  				char *git_dir = xstrdup(read_gitfile(dotgit));
>  
>  				free(dotgit);
> -				if (validate_submodule_git_dir(git_dir,
> -							       sub->name) < 0) {
> +				is_worktree = validate_submodule_gitfile_dir(git_dir,
> +									     sub->name);
> +				if (is_worktree < 0) {
>  					if (!the_repository->repository_format_submodule_path_cfg)
>  						advise(_("enabling extensions.submodulePathConfig "
>  							 "might fix the following error."));

Earlier near the beginning of the function we initialized is_worktree to 0 and then only when submodule_uses_gitfile() is true, we update it with validate_submodule_gitfile_dir().

Show 12 quoted lines
> @@ -2191,7 +2232,13 @@ int submodule_move_head(const char *path, const char *super_prefix,
>  			submodule_reset_index(path, super_prefix);
>  		}
>  
> -		if (old_head && (flags & SUBMODULE_MOVE_HEAD_FORCE)) {
> +		/*
> +		 * Do not reconnect a linked worktree to the submodule's
> +		 * main git dir: that would take over the git dir of another
> +		 * working tree.
> +		 */
> +		if (old_head && (flags & SUBMODULE_MOVE_HEAD_FORCE) &&
> +		    !is_worktree) {

If a linked-worktree submodule 'sub' contains a nested submodule 'inner' whose .git is a directory, submodule_uses_gitfile("sub") would have returned 0 (because the check is recursive), we ran absorb_git_dir_into_superproject() (which is also recursive so it would cause .git in 'inner' to be absorbed), and is_worktree is still 0 at this point, which means if() condition here is satisfied (if forced) and we will enter this block. Would it cause an issue?

I am wondering if the check for is_worktree should be moved outside the else clause, i.e. making the overall flow look more like

        if (old_head) {
                if (!submodule_uses_gitfile(path))
                        absorb_git_dir_into_superproject(path, super_prefix);
                /*
                 * Now path/.git is guaranteed to be a gitfile; 
                 * validate and detect worktrees.
                 */
                ...
                is_worktree = validate_submodule_gitfile_dir(git_dir, sub->name);
                ...
        }
Or am I grossly misreading the code flow?
Thanks.
Adrian Ratiu· Nov 19, 2026, 12:19 UTC · re: Junio C Hamano · lore

Re: [PATCH 3/3] submodule: accept a linked worktree as the submodule's git dir

On Wed, 18 Nov 2026, Junio C Hamano <gitster@pobox.com> wrote:
Show 20 quoted lines
>> @@ -2191,7 +2232,13 @@ int submodule_move_head(const char *path, const char *super_prefix,
>>  			submodule_reset_index(path, super_prefix);
>>  		}
>>  
>> -		if (old_head && (flags & SUBMODULE_MOVE_HEAD_FORCE)) {
>> +		/*
>> +		 * Do not reconnect a linked worktree to the submodule's
>> +		 * main git dir: that would take over the git dir of another
>> +		 * working tree.
>> +		 */
>> +		if (old_head && (flags & SUBMODULE_MOVE_HEAD_FORCE) &&
>> +		    !is_worktree) {
>
> If a linked-worktree submodule 'sub' contains a nested submodule
> 'inner' whose .git is a directory, submodule_uses_gitfile("sub")
> would have returned 0 (because the check is recursive), we ran
> absorb_git_dir_into_superproject() (which is also recursive so it
> would cause .git in 'inner' to be absorbed), and is_worktree is
> still 0 at this point, which means if() condition here is satisfied
> (if forced) and we will enter this block.  Would it cause an issue?

Yes, good catch. I reproduced it with a "sub" linked worktree and a "sub/inner/.git" directory, a recursive checkout absorbs the "inner" and then rewrites sub/.git to point to "$GIT_DIR/modules/sub" which does not exist:

  fatal: gitfile does not point to a valid repository: .git
  error: Submodule 'sub' could not be updated.

It's basically the same breakage this patch is meant to fix, just reached through the absorb path.

Show 16 quoted lines
>
> I am wondering if the check for is_worktree should be moved outside
> the else clause, i.e. making the overall flow look more like
>
>         if (old_head) {
>                 if (!submodule_uses_gitfile(path))
>                         absorb_git_dir_into_superproject(path, super_prefix);
>
>                 /*
>                  * Now path/.git is guaranteed to be a gitfile; 
>                  * validate and detect worktrees.
>                  */
>                 ...
>                 is_worktree = validate_submodule_gitfile_dir(git_dir, sub->name);
>                 ...
>         }

Yes, that fixes it, the sub/.git is left alone and the submodule is checked-out at the correct commit. The validation also runs after an absorb, but absorb puts the gitdir where submodule_name_to_gitdir() says it should be, so the check always passes.

> Or am I grossly misreading the code flow?
You understood it perfectly. :) I'll do this in v2 as well.
Many thanks!

← back to recent threads