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

[Elijah Newren <newren@gmail.com>]

On Wed, Feb 9, 2022 at 9:19 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> Derrick Stolee <stolee@gmail.com> writes:
>
> >> +[[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".
>
> "per-worktree ref" is an entry in the glossary.
>
>     [[def_per_worktree_ref]]per-worktree ref::
>             Refs that are per-<<def_working_tree,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.
>
> And those other things are also listed as "pseudoref".
>
>     [[def_pseudoref]]pseudoref::
>             Pseudorefs are a class of files under `$GIT_DIR` which behave
>             like refs for the purposes of rev-parse, but which are treated
>             specially by git...
>
> I think the motivation of special casing refs/bisect/ is to allow
> use of a separate worktree for bisecting without affecting other
> development or another bisection.  The HEAD is singled out in the
> description, but MERGE_HEAD and others (pseudoref) that are declared
> here to be files under '$GIT_DIR', when we migrate fully to other
> backend that may not want to have files under '$GIT_DIR' to
> represent them, ought to become per-worktree, for the same reason as
> HEAD should be per-worktree, i.e. it allows worktrees to be
> independent from each other and have their checkout at different
> commits, growing history of different branches in parallel.

You had me worried for a second; things would be really broken if
these pseudorefs weren't per-worktree.

But testing just now, I think the pseudorefs are already per-worktree.
I just did a merge in a secondary worktree, and then observed from the
primary worktree that a .git/worktrees/<id>/MERGE_HEAD was created,
not a .git/MERGE_HEAD.  (Maybe the glossary could just spell out that
these are under $GIT_DIR and _not_ $GIT_COMMON_DIR to avoid potential
confusion?)