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
