Re: [PATCH v2] Documentation/git: fix stale "MULTIPLE CHECKOUT MODE" reference

[Eric Sunshine <sunshine@sunshineco.com>]

On Fri, Jul 17, 2015 at 1:03 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
>> This should have been changed by 93a3649 (Documentation: move linked
>> worktree description from checkout to worktree, 2015-07-06).
>>
>> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
>> ---
>> @@ -845,7 +845,7 @@ Git so take care if using Cogito etc.
>>       normally in $GIT_DIR will be taken from this path
>>       instead. Worktree-specific files such as HEAD or index are
>>       taken from $GIT_DIR. See linkgit:gitrepository-layout[5] and
>> -     the section 'MULTIPLE CHECKOUT MODE' in linkgit:checkout[1]
>> +     the linkgit:git-worktree[1] for
>>       details. This variable has lower precedence than other path
>>       variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY...
>
> Thanks.  I have two comments.
>
> "if using Cogito etc.", which is totally outside the topic of this
> patch, is way outdated. Perhaps we would want to remove or replace
> it.

Do you want me to re-roll the current patch to also include the
"Cogito" change as a "while here..." add-on?

Also, I have v3 of "rid git-checkout of too-intimate knowledge of new
worktree"[1] ready to roll. Do you want me to fold the current
patch[2] and its brother [3] into v3?

(I'd actually prefer to keep [2] and [3] out of v3, however, since I'm
not eager to keep piling on more not-particularly-related patches to
that already overly long series -- v3 adds two more patches -- and I
think Duy is waiting for the series to land, as well, since he plans
on adding more tests[4] when fixing the can't-clone-a-linked-worktree
problem.)

[1]: http://thread.gmane.org/gmane.comp.version-control.git/274024
[2]: http://article.gmane.org/gmane.comp.version-control.git/274052
[3]: http://article.gmane.org/gmane.comp.version-control.git/274048
[4]: http://article.gmane.org/gmane.comp.version-control.git/273985

> The other one is more heavy.  Do we even want to have and expose
> GIT_COMMON_DIR environment variable?

I'm probably under-qualified to answer in any sort of authoritative
fashion, but your arguments make sense to me. Duy?

> The primary reason why we added GIT_DIR, GIT_OBJECT_DIRECTORY
> etc. in the early days of Git was because we didn't exactly know
> what kind of layout and flexibility was needed from "various SCMs
> that sit on top of Git core", and we wanted to make progress rapidly
> without making decisions back then.  But it is not 2005 anymore.
>
> Suppose a file "gitdir: /home/gitster/w/src/.git/worktrees/rerere"
> (call that $GIT_DIR) is there, and there is $GIT_DIR/commondir. Is
> there any valid reason why somebody may want to use only part of
> that arrangement and have a $GIT_COMMON_DIR that points at a place
> different from $GIT_DIR/commondir points at to override only a part
> of the setting?
>
> Or perhaps there is a plain vanilla $GIT_DIR that does not have
> $GIT_DIR/commondir.  Is there any valid reason why somebody may want
> to reuse only part of that directory as if it were a linked checkout
> and then use $GIT_COMMON_DIR to redirect the access to the meat of
> the repository elsewhere?
>
> The safety that comes from the primary checkout and the secondary
> checkouts all knowing everybody else is lost in such a use case,
> that is the whole point of adding this new feature.  The fact that
> $GIT_COMMON_DIR/worktrees/* and $GIT_DIR/commondir reference each
> other is what gives us object-prune-safety and multi-checkout-safety.
>
> Unless I am mistaken, I think a separate GIT_COMMON_DIR environment
> variable that can be tweaked by end-user is nothing but a source of
> future bugs and user confusion, without giving us any useful
> flexibility.

Removal of GIT_COMMON_DIR looks like it will require more than a few
patches. Even without an actual environment variable, it seems useful
to keep it around in the documentation in some abstract form in order
to properly explain details of git-worktree, gitrepository-layout, and
git-rev-parse.

It also seems to be used by t0060-path-utils, though I haven't
investigated its purpose there.

Other than that, the only consumer of GIT_COMMON_DIR seems to be
setup.c, and, based upon a quick scan, it looks like it can be easily
dropped, thus alleviating your concerns (but hopefully as a series
separate from v3 of [1] which I'd like to see land).