Re: [PATCH v2 2/4] introduce submodule.superprojectGitDir cache

[Jonathan Tan <jonathantanmy@google.com>]

> 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.

The first sentence is probably better "Introduce a new config variable
storing a submodule's reference to its superproject's gitdir, and teach
'git submodule add' to write it".

Also, I think there should be more detail about the planned use both
here in the commit message and in the config documentation. Is the plan
just to use it for best-effort explanatory messages? (Using it as a true
cache is probably too performance-intensive, I would think, since in its
absence, we have no idea whether the repo is a submodule and would
always have to search to the root of the filesystem.) If it is just for
best-effort explanatory messages, maybe write:

  If present, commands like "git status" in this submodule may print
  additional information about this submodule's status with respect to
  its superproject.

This would further reinforce that this variable being missing is OK.

> diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
> index d7a63c8c12..7c459cc19e 100644
> --- a/Documentation/config/submodule.txt
> +++ b/Documentation/config/submodule.txt
> @@ -90,3 +90,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 worktree  to the superproject's
> +	gitdir. This config should only be present in projects which are
> +	submodules, but is not guaranteed to be present in every submodule. It
> +	is set automatically during submodule creation.
> ++
> +	In situations where more than one superproject references the same
> +	submodule worktree, the value of this config and the behavior of
> +	operations which use it are undefined. To reference a single project
> +	from multiple superprojects, it is better to create a worktree of the
> +	submodule for each superproject.

So my suggestion would be:

  The relative path from this repository's worktree 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, commands
  like "git status" in this submodule may print additional information
  about this submodule's status with respect to its superproject.

(I believe Junio has commented on the second paragraph - I don't have
additional comments on that.)