git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Adrian Ratiu <adrian.ratiu@collabora.com>
Date
Nov 18, 2026, 16:32 UTC
Message-ID
<20261118163249.1693361-4-adrian.ratiu@collabora.com>
In-Reply-To
<20261118163249.1693361-1-adrian.ratiu@collabora.com>

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
Previous: Junio C HamanoNext: Junio C Hamano
Message 11 of 13 in “submodule: linked-worktree submodule hits BUG() in validate_submodule_legacy_git_dir()”
  1. Andreas WendlederNov 16, 2026
  2. Adrian RatiuNov 17, 2026
  3. 0/3 submodule: support linked worktrees in recursive checkoutAdrian Ratiu, Nov 18, 2026
  4. 1/3 submodule: return an error instead of BUG() for an unexpected git dirAdrian Ratiu, Nov 18, 2026
  5. Junio C HamanoNov 18, 2026
  6. Adrian RatiuNov 18, 2026
  7. 2/3 submodule: only suggest submodulePathConfig when it is disabledAdrian Ratiu, Nov 18, 2026
  8. Junio C HamanoNov 18, 2026
  9. Adrian RatiuNov 19, 2026
  10. Junio C HamanoNov 19, 2026
  11. 3/3 submodule: accept a linked worktree as the submodule's git dirAdrian Ratiu, Nov 18, 2026
  12. Junio C HamanoNov 18, 2026
  13. Adrian RatiuNov 19, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.