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

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

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>
> ---
>  Documentation/git.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index d4aa3f6..eb38027 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -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.

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

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.