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

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 17, 2015, 17:03 UTC
Message-ID: <xmqqa8uu3edr.fsf@gitster.dls.corp.google.com>
In-Reply-To: <1437092222-11131-1-git-send-email-sunshine@sunshineco.com>

Eric Sunshine <sunshine@sunshineco.com> writes:

Show 20 quoted lines

> 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.