{"thread":{"id":"39865","subject":"[PATCH v2] Documentation/git: fix stale \"MULTIPLE CHECKOUT MODE\" reference","startedAt":"2015-07-17T00:17:02Z","lastAt":"2015-07-18T20:56:43Z","messageCount":7,"participants":["Eric Sunshine","Junio C Hamano","Duy Nguyen"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"266217","messageId":"1437092222-11131-1-git-send-email-sunshine@sunshineco.com","threadId":"39865","inReplyTo":null,"subject":"[PATCH v2] Documentation/git: fix stale \"MULTIPLE CHECKOUT MODE\" reference","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-07-17T00:17:02Z","receivedAt":"2015-07-17T00:17:02Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"This should have been changed by 93a3649 (Documentation: move linked\nworktree description from checkout to worktree, 2015-07-06).\n\nSigned-off-by: Eric Sunshine \n---\n Documentation/git.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex d4aa3f6..eb38027 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -845,7 +845,7 @@ Git so take care if using Cogito etc.\n \tnormally in $GIT_DIR will be taken from this path\n \tinstead. Worktree-specific files such as HEAD or index are\n \ttaken from $GIT_DIR. See linkgit:gitrepository-layout[5] and\n-\tthe section 'MULTIPLE CHECKOUT MODE' in linkgit:checkout[1]\n+\tthe linkgit:git-worktree[1] for\n \tdetails. This variable has lower precedence than other path\n \tvariables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY...\n \n-- \n2.5.0.rc2.378.g0af52e8\n"},{"id":"266218","messageId":"CAPig+cShY2Op9ET9xcbvvQmM33fnrbDLR2ft2SELzqJTdg-D4w@mail.gmail.com","threadId":"39865","inReplyTo":"1437092222-11131-1-git-send-email-sunshine@sunshineco.com","subject":"Re: [PATCH v2] Documentation/git: fix stale \"MULTIPLE CHECKOUT MODE\" reference","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-07-17T00:19:17Z","receivedAt":"2015-07-17T00:19:17Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Thu, Jul 16, 2015 at 8:17 PM, Eric Sunshine wrote:\n> This should have been changed by 93a3649 (Documentation: move linked\n> worktree description from checkout to worktree, 2015-07-06).\n>\n> Signed-off-by: Eric Sunshine \n> ---\n> diff --git a/Documentation/git.txt b/Documentation/git.txt\n> index d4aa3f6..eb38027 100644\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -845,7 +845,7 @@ Git so take care if using Cogito etc.\n> normally in $GIT_DIR will be taken from this path\n> instead. Worktree-specific files such as HEAD or index are\n> taken from $GIT_DIR. See linkgit:gitrepository-layout[5] and\n> - the section 'MULTIPLE CHECKOUT MODE' in linkgit:checkout[1]\n> + the linkgit:git-worktree[1] for\n\ns/the//\n\n> details. This variable has lower precedence than other path\n> variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY...\n"},{"id":"266249","messageId":"xmqqa8uu3edr.fsf@gitster.dls.corp.google.com","threadId":"39865","inReplyTo":"1437092222-11131-1-git-send-email-sunshine@sunshineco.com","subject":"Re: [PATCH v2] Documentation/git: fix stale \"MULTIPLE CHECKOUT MODE\" reference","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-07-17T17:03:44Z","receivedAt":"2015-07-17T17:03:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n> This should have been changed by 93a3649 (Documentation: move linked\n> worktree description from checkout to worktree, 2015-07-06).\n>\n> Signed-off-by: Eric Sunshine \n> ---\n> Documentation/git.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git.txt b/Documentation/git.txt\n> index d4aa3f6..eb38027 100644\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -845,7 +845,7 @@ Git so take care if using Cogito etc.\n> \tnormally in $GIT_DIR will be taken from this path\n> \tinstead. Worktree-specific files such as HEAD or index are\n> \ttaken from $GIT_DIR. See linkgit:gitrepository-layout[5] and\n> -\tthe section 'MULTIPLE CHECKOUT MODE' in linkgit:checkout[1]\n> +\tthe linkgit:git-worktree[1] for\n> \tdetails. This variable has lower precedence than other path\n> \tvariables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY...\n\nThanks. I have two comments.\n\n\"if using Cogito etc.\", which is totally outside the topic of this\npatch, is way outdated. Perhaps we would want to remove or replace\nit.\n\nThe other one is more heavy. Do we even want to have and expose\nGIT_COMMON_DIR environment variable?\n\nThe primary reason why we added GIT_DIR, GIT_OBJECT_DIRECTORY\netc. in the early days of Git was because we didn't exactly know\nwhat kind of layout and flexibility was needed from \"various SCMs\nthat sit on top of Git core\", and we wanted to make progress rapidly\nwithout making decisions back then. But it is not 2005 anymore.\n\nSuppose a file \"gitdir: /home/gitster/w/src/.git/worktrees/rerere\"\n(call that $GIT_DIR) is there, and there is $GIT_DIR/commondir. Is\nthere any valid reason why somebody may want to use only part of\nthat arrangement and have a $GIT_COMMON_DIR that points at a place\ndifferent from $GIT_DIR/commondir points at to override only a part\nof the setting?\n\nOr perhaps there is a plain vanilla $GIT_DIR that does not have\n$GIT_DIR/commondir. Is there any valid reason why somebody may want\nto reuse only part of that directory as if it were a linked checkout\nand then use $GIT_COMMON_DIR to redirect the access to the meat of\nthe repository elsewhere?\n\nThe safety that comes from the primary checkout and the secondary\ncheckouts all knowing everybody else is lost in such a use case,\nthat is the whole point of adding this new feature. The fact that\n$GIT_COMMON_DIR/worktrees/* and $GIT_DIR/commondir reference each\nother is what gives us object-prune-safety and multi-checkout-safety.\n\nUnless I am mistaken, I think a separate GIT_COMMON_DIR environment\nvariable that can be tweaked by end-user is nothing but a source of\nfuture bugs and user confusion, without giving us any useful\nflexibility.\n"},{"id":"266265","messageId":"CAPig+cQvVA0Cb60AxA=9RAUj6bBN419FQHObM6PARiDwGLiHow@mail.gmail.com","threadId":"39865","inReplyTo":"xmqqa8uu3edr.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2] Documentation/git: fix stale \"MULTIPLE CHECKOUT MODE\" reference","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-07-17T20:52:46Z","receivedAt":"2015-07-17T20:52:46Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, Jul 17, 2015 at 1:03 PM, Junio C Hamano wrote:\n> Eric Sunshine writes:\n>> This should have been changed by 93a3649 (Documentation: move linked\n>> worktree description from checkout to worktree, 2015-07-06).\n>>\n>> Signed-off-by: Eric Sunshine \n>> ---\n>> @@ -845,7 +845,7 @@ Git so take care if using Cogito etc.\n>> normally in $GIT_DIR will be taken from this path\n>> instead. Worktree-specific files such as HEAD or index are\n>> taken from $GIT_DIR. See linkgit:gitrepository-layout[5] and\n>> - the section 'MULTIPLE CHECKOUT MODE' in linkgit:checkout[1]\n>> + the linkgit:git-worktree[1] for\n>> details. This variable has lower precedence than other path\n>> variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY...\n>\n> Thanks. I have two comments.\n>\n> \"if using Cogito etc.\", which is totally outside the topic of this\n> patch, is way outdated. Perhaps we would want to remove or replace\n> it.\n\nDo you want me to re-roll the current patch to also include the\n\"Cogito\" change as a \"while here...\" add-on?\n\nAlso, I have v3 of \"rid git-checkout of too-intimate knowledge of new\nworktree\"[1] ready to roll. Do you want me to fold the current\npatch[2] and its brother [3] into v3?\n\n(I'd actually prefer to keep [2] and [3] out of v3, however, since I'm\nnot eager to keep piling on more not-particularly-related patches to\nthat already overly long series -- v3 adds two more patches -- and I\nthink Duy is waiting for the series to land, as well, since he plans\non adding more tests[4] when fixing the can't-clone-a-linked-worktree\nproblem.)\n\n[1]: http://thread.gmane.org/gmane.comp.version-control.git/274024\n[2]: http://article.gmane.org/gmane.comp.version-control.git/274052\n[3]: http://article.gmane.org/gmane.comp.version-control.git/274048\n[4]: http://article.gmane.org/gmane.comp.version-control.git/273985\n\n> The other one is more heavy. Do we even want to have and expose\n> GIT_COMMON_DIR environment variable?\n\nI'm probably under-qualified to answer in any sort of authoritative\nfashion, but your arguments make sense to me. Duy?\n\n> The primary reason why we added GIT_DIR, GIT_OBJECT_DIRECTORY\n> etc. in the early days of Git was because we didn't exactly know\n> what kind of layout and flexibility was needed from \"various SCMs\n> that sit on top of Git core\", and we wanted to make progress rapidly\n> without making decisions back then. But it is not 2005 anymore.\n>\n> Suppose a file \"gitdir: /home/gitster/w/src/.git/worktrees/rerere\"\n> (call that $GIT_DIR) is there, and there is $GIT_DIR/commondir. Is\n> there any valid reason why somebody may want to use only part of\n> that arrangement and have a $GIT_COMMON_DIR that points at a place\n> different from $GIT_DIR/commondir points at to override only a part\n> of the setting?\n>\n> Or perhaps there is a plain vanilla $GIT_DIR that does not have\n> $GIT_DIR/commondir. Is there any valid reason why somebody may want\n> to reuse only part of that directory as if it were a linked checkout\n> and then use $GIT_COMMON_DIR to redirect the access to the meat of\n> the repository elsewhere?\n>\n> The safety that comes from the primary checkout and the secondary\n> checkouts all knowing everybody else is lost in such a use case,\n> that is the whole point of adding this new feature. The fact that\n> $GIT_COMMON_DIR/worktrees/* and $GIT_DIR/commondir reference each\n> other is what gives us object-prune-safety and multi-checkout-safety.\n>\n> Unless I am mistaken, I think a separate GIT_COMMON_DIR environment\n> variable that can be tweaked by end-user is nothing but a source of\n> future bugs and user confusion, without giving us any useful\n> flexibility.\n\nRemoval of GIT_COMMON_DIR looks like it will require more than a few\npatches. Even without an actual environment variable, it seems useful\nto keep it around in the documentation in some abstract form in order\nto properly explain details of git-worktree, gitrepository-layout, and\ngit-rev-parse.\n\nIt also seems to be used by t0060-path-utils, though I haven't\ninvestigated its purpose there.\n\nOther than that, the only consumer of GIT_COMMON_DIR seems to be\nsetup.c, and, based upon a quick scan, it looks like it can be easily\ndropped, thus alleviating your concerns (but hopefully as a series\nseparate from v3 of [1] which I'd like to see land).\n"},{"id":"266268","messageId":"xmqqfv4m1ofk.fsf@gitster.dls.corp.google.com","threadId":"39865","inReplyTo":"CAPig+cQvVA0Cb60AxA=9RAUj6bBN419FQHObM6PARiDwGLiHow@mail.gmail.com","subject":"Re: [PATCH v2] Documentation/git: fix stale \"MULTIPLE CHECKOUT MODE\" reference","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-07-17T21:09:35Z","receivedAt":"2015-07-17T21:09:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n>> Thanks. I have two comments.\n>>\n>> \"if using Cogito etc.\", which is totally outside the topic of this\n>> patch, is way outdated. Perhaps we would want to remove or replace\n>> it.\n>\n> Do you want me to re-roll the current patch to also include the\n> \"Cogito\" change as a \"while here...\" add-on?\n\nNo. That is totally outside the topic of this patch series.\n\n> Also, I have v3 of \"rid git-checkout of too-intimate knowledge of new\n> worktree\"[1] ready to roll. Do you want me to fold the current\n> patch[2] and its brother [3] into v3?\n\nI think I took them and merged them to 'master' today.\n\n> ... since he plans\n> on adding more tests[4] when fixing the can't-clone-a-linked-worktree\n> problem.)\n\nI saw that issue myself yesterday, too, I think, with a failed\nattempt to fetch from one. I do not think it is such a huge issue\nin a sense that we can always say \"don't do that\", as cloning and\nfetching only from the primary location is not something that would\nmake users feel unnatural. After all, we sell this as \"allowing\nsecondary checkout\", meaning that it is perfectly OK for us to keep\nsecondaries second-class citizens compared to the primary one. So\nbeing able to fetch from and clone from is \"nice to have\".\n\n> Other than that, the only consumer of GIT_COMMON_DIR seems to be\n> setup.c, and, based upon a quick scan, it looks like it can be easily\n> dropped, thus alleviating your concerns (but hopefully as a series\n> separate from v3 of [1] which I'd like to see land).\n\nOne step at a time is perfectly fine. We will be cautioning users\nto avoid storing the only copy of their data in repositories that\nemploy this feature for a few releases until it matures by marking\nit experimental exactly so that we can tweak external interfaces\nlike that incrementally.\n\nThanks.\n"},{"id":"266321","messageId":"CACsJy8B5d250xdofWkj0+TXaye=h2fDoyEobA7ktBtw-0sJTwA@mail.gmail.com","threadId":"39865","inReplyTo":"xmqqa8uu3edr.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2] Documentation/git: fix stale \"MULTIPLE CHECKOUT MODE\" reference","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2015-07-18T07:57:38Z","receivedAt":"2015-07-18T07:57:38Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Sat, Jul 18, 2015 at 12:03 AM, Junio C Hamano wrote:\n> The other one is more heavy. Do we even want to have and expose\n> GIT_COMMON_DIR environment variable?\n>\n> The primary reason why we added GIT_DIR, GIT_OBJECT_DIRECTORY\n> etc. in the early days of Git was because we didn't exactly know\n> what kind of layout and flexibility was needed from \"various SCMs\n> that sit on top of Git core\", and we wanted to make progress rapidly\n> without making decisions back then. But it is not 2005 anymore.\n>\n> Suppose a file \"gitdir: /home/gitster/w/src/.git/worktrees/rerere\"\n> (call that $GIT_DIR) is there, and there is $GIT_DIR/commondir. Is\n> there any valid reason why somebody may want to use only part of\n> that arrangement and have a $GIT_COMMON_DIR that points at a place\n> different from $GIT_DIR/commondir points at to override only a part\n> of the setting?\n>\n> Or perhaps there is a plain vanilla $GIT_DIR that does not have\n> $GIT_DIR/commondir. Is there any valid reason why somebody may want\n> to reuse only part of that directory as if it were a linked checkout\n> and then use $GIT_COMMON_DIR to redirect the access to the meat of\n> the repository elsewhere?\n>\n> The safety that comes from the primary checkout and the secondary\n> checkouts all knowing everybody else is lost in such a use case,\n> that is the whole point of adding this new feature. The fact that\n> $GIT_COMMON_DIR/worktrees/* and $GIT_DIR/commondir reference each\n> other is what gives us object-prune-safety and multi-checkout-safety.\n>\n> Unless I am mistaken, I think a separate GIT_COMMON_DIR environment\n> variable that can be tweaked by end-user is nothing but a source of\n> future bugs and user confusion, without giving us any useful\n> flexibility.\n\nThe flexibility here is not about extending this feature per se but\nmaybe trying out an entirely different setup. Yes a bunch of safety\nnets are thrown out of the window if you try it. I guess I still had\nthe 2005 mindset when I designed this. If there is no strong objection\nto $GIT_COMMON_DIR, I suggest we keep it until we sort out the\nsubmodule problem. There are a few options on how to share git repos\nbetween submodules that this explicit separation _might_ help.\n-- \nDuy\n"},{"id":"266342","messageId":"xmqqy4idyyk4.fsf@gitster.dls.corp.google.com","threadId":"39865","inReplyTo":"CACsJy8B5d250xdofWkj0+TXaye=h2fDoyEobA7ktBtw-0sJTwA@mail.gmail.com","subject":"Re: [PATCH v2] Documentation/git: fix stale \"MULTIPLE CHECKOUT MODE\" reference","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-07-18T20:56:43Z","receivedAt":"2015-07-18T20:56:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Duy Nguyen writes:\n\n> The flexibility here is not about extending this feature per se but\n> maybe trying out an entirely different setup. Yes a bunch of safety\n> nets are thrown out of the window if you try it. I guess I still had\n> the 2005 mindset when I designed this. If there is no strong objection\n> to $GIT_COMMON_DIR, I suggest we keep it until we sort out the\n> submodule problem.\n\nOK, let's revisit this after we finish futzing with the submodule part.\n"}]}