Re: [PATCH v6 1/6] Documentation: add extensions.worktreeConfig details

[Derrick Stolee <stolee@gmail.com>]

On 2/8/2022 5:20 PM, Junio C Hamano wrote:
> "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>> diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt
>> index 4e23d73cdca..bccaec7a963 100644
>> --- a/Documentation/config/extensions.txt
>> +++ b/Documentation/config/extensions.txt
>> @@ -6,3 +6,34 @@ extensions.objectFormat::
>>  Note that this setting should only be set by linkgit:git-init[1] or
>>  linkgit:git-clone[1].  Trying to change it after initialization will not
>>  work and will produce hard-to-diagnose issues.
>> +
>> +extensions.worktreeConfig::
>> +	If enabled, then worktrees will load config settings from the
>> +	`$GIT_DIR/config.worktree` file in addition to the
>> +	`$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and
>> +	`$GIT_DIR` are the same for the main working tree, while other
>> +	working trees have `$GIT_DIR` equal to
>> +	`$GIT_COMMON_DIR/worktrees/<id>/`. The settings in the
> 
> The mixed use of "worktree" and "working tree" in this paragraph
> might confuse readers into thinking that the paragraph is being
> careful to make distinction between the two.  All references to
> "working tree" in the above paragraph should actually be "worktree",
> I would think.

I generally agree. This was changed in the most-recent re-roll
based on a request by Eric [1]. I'm happy to take whichever
version the two of you settle on.

[1] https://lore.kernel.org/git/CAPig+cS-3CxxyPGcy_vkeN_WYTRo1b-ZhJNdPy8ARZSNKkF1Xg@mail.gmail.com/

> 	Side note: "working tree" is in the glossary-content.txt,
> 	but "worktree", which is one "working tree" + repository
> 	metadata (i.e. ".git/") that may be partially shared with
> 	other "worktree"s of a single repository, is not defined.
> 
> This is a tangent, but I wonder why we chose to use a different
> filename (i.e. not "config" but "config.worktree") for this.  If we
> were redoing multi-worktree support from scratch, we would not reuse
> the $GIT_DIR used by the primary worktree as $GIT_COMMON_DIR, so
> that all worktrees would share a single $GIT_COMMON_DIR and
> $GIT_COMMON_DIR/config that has stuff that is shared among all the
> worktrees, while per worktree stuff is in $GIT_DIR/config even for
> the primary worktree.  But that is all water under the bridge now.

Right. I think that since the primary worktree uses $GIT_COMMON_DIR
as its location for base information (like HEAD) it also means that
its worktree-specific config file cannot be called "config".

Perhaps there could have been a way to split the worktrees so the
primary worktree got its own directory within ".git/worktrees/", but
my guess is that the design optimized for backwards compatibility:
Git clients that don't understand worktrees could still interact with
the primary worktree.

> Other than the terminology gotcha, looked sensible.  Migrating
> automatically and/or noticing a suspicious setting may be needed to
> help end users, but that would not be within the scope of this step.
> 
> Attached is a "how about this?" glossary update suggestion.  Most of
> the existing mention of "working tree" are fine as-is because they
> only care about what is in the "working tree", but some should be
> changed to "worktree" to stress the fact that they care not just the
> "working tree" part but also the repository metadata part that is
> associated with that single "working tree".  The first hunk says
> worktree but it is clear that it is interested only in the "working
> tree" files.
> 
>  Documentation/glossary-content.txt | 13 +++++++++++--
>  1 file changed, 11 insertions(+), 2 deletions(-)
> 
> diff --git c/Documentation/glossary-content.txt w/Documentation/glossary-content.txt
> index c077971335..d816512c6a 100644
> --- c/Documentation/glossary-content.txt
> +++ w/Documentation/glossary-content.txt
> @@ -312,7 +312,7 @@ Pathspecs are used on the command line of "git ls-files", "git
>  ls-tree", "git add", "git grep", "git diff", "git checkout",
>  and many other commands to
>  limit the scope of operations to some subset of the tree or
> -worktree.  See the documentation of each command for whether
> +working tree.  See the documentation of each command for whether
>  paths are relative to the current directory or toplevel.  The
>  pathspec syntax is as follows:
>  +
> @@ -446,7 +446,7 @@ exclude;;
>  	interface than the <<def_plumbing,plumbing>>.
>  
>  [[def_per_worktree_ref]]per-worktree ref::
> -	Refs that are per-<<def_working_tree,worktree>>, rather than
> +	Refs that are per-<<def_worktree,worktree>>, rather than
>  	global.  This is presently only <<def_HEAD,HEAD>> and any refs
>  	that start with `refs/bisect/`, but might later include other
>  	unusual refs.
> @@ -669,3 +669,12 @@ The most notable example is `HEAD`.
>  	The tree of actual checked out files.  The working tree normally
>  	contains the contents of the <<def_HEAD,HEAD>> commit's tree,
>  	plus any local changes that you have made but not yet committed.
> +
> +[[def_work_tree]]worktree::
> +	A repository can have zero (i.e. bare repository) or one or
> +	more worktrees attached to it. One "worktree" consists of a
> +	"working tree" and repository metadata, most of which are
> +	shared among other worktrees of a single repository, and
> +	some of which are maintained separately per worktree
> +	(e.g. the index, HEAD, per-worktree refs and per-worktree
> +	configuration file)

I like this addition, except that I don't understand the "per-worktree
refs" (other than HEAD). Are there other thins used by features such
as merge and rebase that would appear as worktree-specific? Of course,
some state for these operations is stored per-worktree, I just didn't
know if any were actually "refs".

Other than that technicality, which could be completely correct, this
is a good idea to include.

Thanks,
-Stolee