Re: [PATCH v6 2/5] introduce submodule.superprojectGitDir record

[Jonathan Tan <jonathantanmy@google.com>]

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