diff mbox series

[v6,2/5] introduce submodule.superprojectGitDir record

Message ID 20211117005701.371808-3-emilyshaffer@google.com (mailing list archive)
State New, archived
Headers show
Series teach submodules to know they're submodules | expand

Commit Message

Emily Shaffer Nov. 17, 2021, 12:56 a.m. UTC 
Teach submodules a reference to their superproject's gitdir. This allows
us to A) know that we're running from a submodule, and B) have a
shortcut to the superproject's vitals, for example, configs.

By using a relative path instead of an absolute path, we can move the
superproject directory around on the filesystem without breaking the
submodule's pointer. And by using the path from gitdir to gitdir, we can
move the submodule within the superproject's tree structure without
breaking the submodule's pointer, too. Finally, by pointing at the
superproject's worktree gitdir (if it exists), we ensure that we can
tell which worktree contains our submodule.

Since this hint value is only introduced during new submodule creation
via `git submodule add`, though, there is more work to do to allow the
record to be created at other times.

Once this new config is reliably in place, we can use it to know
definitively that we are working in a submodule, and to know which
superproject we are a submodule of. This allows us to do some
value-added behavior, like letting "git status" print additional info
about the submodule's status in relation to its superproject, or like
letting the superproject and submodule share an additional config file
separate from either one's local config.

Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
Helped-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/config/submodule.txt | 12 +++++++++++
 builtin/submodule--helper.c        | 11 ++++++++++
 t/t7400-submodule-basic.sh         | 32 ++++++++++++++++++++----------
 3 files changed, 45 insertions(+), 10 deletions(-)

Comments

Jonathan Tan Nov. 17, 2021, 11:43 p.m. UTC | #1 
Emily Shaffer <emilyshaffer@google.com> writes:
> Teach submodules a reference to their superproject's gitdir. This allows
> us to A) know that we're running from a submodule, and B) have a
> shortcut to the superproject's vitals, for example, configs.

If we're going with my proposal [1], I think it's worth further
explaining the concept right at the beginning of the commit message:

  Teach submodules a config variable referencing their superproject's
  gitdir. Git commands may rely on this reference to determine if the
  current repo is a submodule to another repo: if this reference is
  absent, Git may assume that the current repo is not a submodule. In
  practice, commands and arguments that specifially reference the
  submodule relationship (like "rev-parse
  --show-superproject-working-tree") will still search the ancestor
  directory, but others (say, a "git status" that prints the submodule's
  status in relation to its superproject or a config option that lets
  the superproject and submodule share config) would not.

[1] https://lore.kernel.org/git/20211117232846.2596110-1-jonathantanmy@google.com/

> By using a relative path instead of an absolute path, we can move the
> superproject directory around on the filesystem without breaking the
> submodule's pointer. And by using the path from gitdir to gitdir, we can
> move the submodule within the superproject's tree structure without
> breaking the submodule's pointer, too. Finally, by pointing at the
> superproject's worktree gitdir (if it exists), we ensure that we can
> tell which worktree contains our submodule.

OK.

> Since this hint value is only introduced during new submodule creation
> via `git submodule add`, though, there is more work to do to allow the
> record to be created at other times.

This is not a hint anymore. I would reword as:

  This commit teaches "git submodule add" to add the aforementioned
  config variable. Subsequent commits will teach other commands to do
  so.

> Once this new config is reliably in place, we can use it to know
> definitively that we are working in a submodule, and to know which
> superproject we are a submodule of. This allows us to do some
> value-added behavior, like letting "git status" print additional info
> about the submodule's status in relation to its superproject, or like
> letting the superproject and submodule share an additional config file
> separate from either one's local config.

I folded this into the first paragraph above, so this would no longer
needed if you used my suggestion above.

> +submodule.superprojectGitDir::
> +	The relative path from the submodule's gitdir to its superproject's
> +	gitdir. When Git is run in a repository, it usually makes no
> +	difference whether this repository is standalone or a submodule, but if
> +	this configuration variable is present, additional behavior may be
> +	possible, such as "git status" printing additional information about
> +	this submodule's status with respect to its superproject. This config
> +	should only be present in projects which are submodules, but is not
> +	guaranteed to be present in every submodule, so only optional
> +	value-added behavior should be linked to it. It is set automatically
> +	during submodule creation.

If we're going to rely on the variable more, this needs to be updated.
Maybe:

  If this repository is a submodule, the relative path from this repo's
  gitdir to its superproject's gitdir. Git commands may rely on this
  reference to determine if the current repo is a submodule to another
  repo: if this reference is absent, Git may assume that the current
  repo is not a submodule (this does not make a difference to most Git
  commands). It is set automatically during ??

(and probably each subsequent patch will need to update the ??)
diff mbox series

Patch

diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
index ee454f8126..61d975745e 100644
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.txt
@@ -91,3 +91,15 @@  submodule.alternateErrorStrategy::
 	`ignore`, `info`, `die`. Default is `die`. Note that if set to `ignore`
 	or `info`, and if there is an error with the computed alternate, the
 	clone proceeds as if no alternate was specified.
+
+submodule.superprojectGitDir::
+	The relative path from the submodule's gitdir to its superproject's
+	gitdir. When Git is run in a repository, it usually makes no
+	difference whether this repository is standalone or a submodule, but if
+	this configuration variable is present, additional behavior may be
+	possible, such as "git status" printing additional information about
+	this submodule's status with respect to its superproject. This config
+	should only be present in projects which are submodules, but is not
+	guaranteed to be present in every submodule, so only optional
+	value-added behavior should be linked to it. It is set automatically
+	during submodule creation.
diff --git a/builtin/submodule--helper.c b/builtin/submodule--helper.c
index e630f0c730..24f0ef2a78 100644
--- a/builtin/submodule--helper.c
+++ b/builtin/submodule--helper.c
@@ -1838,6 +1838,17 @@  static int clone_submodule(struct module_clone_data *clone_data)
 		git_config_set_in_file(p, "submodule.alternateErrorStrategy",
 				       error_strategy);
 
+	/*
+	 * Set the path from submodule's new gitdir to superproject's gitdir.
+	 * The latter may be a worktree gitdir. However, it is not possible for
+	 * the submodule to have a worktree-specific gitdir or config at clone
+	 * time, because "extensions.worktreeConfig" is only valid when set in
+	 * the local gitconfig, which the brand new submodule does not have yet.
+	 */
+	git_config_set_in_file(p, "submodule.superprojectGitDir",
+			       relative_path(absolute_path(get_git_dir()),
+					     sm_gitdir, &sb));
+
 	free(sm_alternate);
 	free(error_strategy);
 
diff --git a/t/t7400-submodule-basic.sh b/t/t7400-submodule-basic.sh
index d69a5c0032..3d146491df 100755
--- a/t/t7400-submodule-basic.sh
+++ b/t/t7400-submodule-basic.sh
@@ -109,12 +109,24 @@  submodurl=$(pwd -P)
 
 inspect() {
 	sub_dir=$1 &&
+	super_dir=$2 &&
 
 	git -C "$sub_dir" for-each-ref --format='%(refname)' 'refs/heads/*' >heads &&
 	{ git -C "$sub_dir" symbolic-ref HEAD || :; } >head &&
 	git -C "$sub_dir" rev-parse HEAD >head-sha1 &&
 	git -C "$sub_dir" update-index --refresh &&
 	git -C "$sub_dir" diff-files --exit-code &&
+
+	# Ensure that submodule.superprojectGitDir contains the path from the
+	# submodule's gitdir to the superproject's gitdir.
+
+	super_abs_gitdir=$(git -C "$super_dir" rev-parse --absolute-git-dir) &&
+	sub_abs_gitdir=$(git -C "$sub_dir" rev-parse --absolute-git-dir) &&
+
+	[ "$(git -C "$sub_dir" config --get submodule.superprojectGitDir)" = \
+	  "$(test-tool path-utils relative_path "$super_abs_gitdir" \
+						"$sub_abs_gitdir")" ] &&
+
 	git -C "$sub_dir" clean -n -d -x >untracked
 }
 
@@ -138,7 +150,7 @@  test_expect_success 'submodule add' '
 	) &&
 
 	rm -f heads head untracked &&
-	inspect addtest/submod &&
+	inspect addtest/submod addtest &&
 	test_cmp expect heads &&
 	test_cmp expect head &&
 	test_must_be_empty untracked
@@ -240,7 +252,7 @@  test_expect_success 'submodule add --branch' '
 	) &&
 
 	rm -f heads head untracked &&
-	inspect addtest/submod-branch &&
+	inspect addtest/submod-branch addtest &&
 	test_cmp expect-heads heads &&
 	test_cmp expect-head head &&
 	test_must_be_empty untracked
@@ -256,7 +268,7 @@  test_expect_success 'submodule add with ./ in path' '
 	) &&
 
 	rm -f heads head untracked &&
-	inspect addtest/dotsubmod/frotz &&
+	inspect addtest/dotsubmod/frotz addtest &&
 	test_cmp expect heads &&
 	test_cmp expect head &&
 	test_must_be_empty untracked
@@ -272,7 +284,7 @@  test_expect_success 'submodule add with /././ in path' '
 	) &&
 
 	rm -f heads head untracked &&
-	inspect addtest/dotslashdotsubmod/frotz &&
+	inspect addtest/dotslashdotsubmod/frotz addtest &&
 	test_cmp expect heads &&
 	test_cmp expect head &&
 	test_must_be_empty untracked
@@ -288,7 +300,7 @@  test_expect_success 'submodule add with // in path' '
 	) &&
 
 	rm -f heads head untracked &&
-	inspect addtest/slashslashsubmod/frotz &&
+	inspect addtest/slashslashsubmod/frotz addtest &&
 	test_cmp expect heads &&
 	test_cmp expect head &&
 	test_must_be_empty untracked
@@ -304,7 +316,7 @@  test_expect_success 'submodule add with /.. in path' '
 	) &&
 
 	rm -f heads head untracked &&
-	inspect addtest/realsubmod &&
+	inspect addtest/realsubmod addtest &&
 	test_cmp expect heads &&
 	test_cmp expect head &&
 	test_must_be_empty untracked
@@ -320,7 +332,7 @@  test_expect_success 'submodule add with ./, /.. and // in path' '
 	) &&
 
 	rm -f heads head untracked &&
-	inspect addtest/realsubmod2 &&
+	inspect addtest/realsubmod2 addtest &&
 	test_cmp expect heads &&
 	test_cmp expect head &&
 	test_must_be_empty untracked
@@ -351,7 +363,7 @@  test_expect_success 'submodule add in subdirectory' '
 	) &&
 
 	rm -f heads head untracked &&
-	inspect addtest/realsubmod3 &&
+	inspect addtest/realsubmod3 addtest &&
 	test_cmp expect heads &&
 	test_cmp expect head &&
 	test_must_be_empty untracked
@@ -492,7 +504,7 @@  test_expect_success 'update should work when path is an empty dir' '
 	git submodule update -q >update.out &&
 	test_must_be_empty update.out &&
 
-	inspect init &&
+	inspect init . &&
 	test_cmp expect head-sha1
 '
 
@@ -551,7 +563,7 @@  test_expect_success 'update should checkout rev1' '
 	echo "$rev1" >expect &&
 
 	git submodule update init &&
-	inspect init &&
+	inspect init . &&
 
 	test_cmp expect head-sha1
 '