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

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

[Eric Sunshine]

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...
 
-- 
2.5.0.rc2.378.g0af52e8

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

[Eric Sunshine]

On Thu, Jul 16, 2015 at 8:17 PM, Eric Sunshine <sunshine@sunshineco.com> wrote:
> 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>
> ---
> 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

s/the//

>         details. This variable has lower precedence than other path
>         variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY...

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

[Junio C Hamano]

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.

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

[Eric Sunshine]

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

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

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

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

No.  That is totally outside the topic of this patch series.

> 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 think I took them and merged them to 'master' today.

> ... since he plans
> on adding more tests[4] when fixing the can't-clone-a-linked-worktree
> problem.)

I saw that issue myself yesterday, too, I think, with a failed
attempt to fetch from one.  I do not think it is such a huge issue
in a sense that we can always say "don't do that", as cloning and
fetching only from the primary location is not something that would
make users feel unnatural.  After all, we sell this as "allowing
secondary checkout", meaning that it is perfectly OK for us to keep
secondaries second-class citizens compared to the primary one.  So
being able to fetch from and clone from is "nice to have".

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

One step at a time is perfectly fine.  We will be cautioning users
to avoid storing the only copy of their data in repositories that
employ this feature for a few releases until it matures by marking
it experimental exactly so that we can tweak external interfaces
like that incrementally.

Thanks.

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

[Duy Nguyen]

On Sat, Jul 18, 2015 at 12:03 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 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.

The flexibility here is not about extending this feature per se but
maybe trying out an entirely different setup. Yes a bunch of safety
nets are thrown out of the window if you try it. I guess I still had
the 2005 mindset when I designed this. If there is no strong objection
to $GIT_COMMON_DIR, I suggest we keep it until we sort out the
submodule problem. There are a few options on how to share git repos
between submodules that this explicit separation _might_ help.
-- 
Duy

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

[Junio C Hamano]

Duy Nguyen <pclouds@gmail.com> writes:

> The flexibility here is not about extending this feature per se but
> maybe trying out an entirely different setup. Yes a bunch of safety
> nets are thrown out of the window if you try it. I guess I still had
> the 2005 mindset when I designed this. If there is no strong objection
> to $GIT_COMMON_DIR, I suggest we keep it until we sort out the
> submodule problem.

OK, let's revisit this after we finish futzing with the submodule part.