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

[Junio C Hamano <gitster@pobox.com>]

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.