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

[Emily Shaffer <emilyshaffer@google.com>]

On Tue, Jul 27, 2021 at 10:46:50AM -0700, Jonathan Tan wrote:
> 
> > 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.

Ok, I'll expand the commit message. The first use case for this extra
pointer is for a shared config between superproject and submodule, which
I've sent a series for already; I'll mention that in the commit message
too.

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

The spirit of this suggestion seems to be "describe a possible side
effect of this config", so I'll do that, although the wording may not be
exactly the same. Thanks.

 - Emily