On 14-09-21 05:50 AM, Duy Nguyen wrote: > On Sun, Sep 21, 2014 at 10:10 AM, Eric Sunshine <sunshine@xxxxxxxxxxxxxx> wrote: >> Would it make sense for this "rule of thumb" summary to be presented >> first, and then the explanation of that rule after, rather than the >> reverse as is currently the case? > > You mean like this? *shrug* To me it seems better to leave it at the end here. If we really want people to follow this advice, it should appear where GIT_DIR is officially documented. I think this is the Environment Variables section of the Documentation/git.txt file. Probably GIT_COMMON_DIR should also be documented there. (Sorry, I don't have time to whip up a patch right now.) M. > diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt > index c101575..fd77631 100644 > --- a/Documentation/git-checkout.txt > +++ b/Documentation/git-checkout.txt > @@ -420,6 +420,11 @@ $GIT_COMMON_DIR is set to point back to the main > working tree's $GIT_DIR > (e.g. `/path/main/.git`). These settings are made in a `.git` file located at > the top directory of the linked working tree. > > +See linkgit:gitrepository-layout[5] for more information. The rule of > +thumb is do not make any assumption about whether a path belongs to > +$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something > +inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. > + > Path resolution via `git rev-parse --git-path` uses either > $GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the > linked working tree `git rev-parse --git-path HEAD` returns > @@ -429,11 +434,6 @@ rev-parse --git-path refs/heads/master` uses > $GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`, > since refs are shared across all working trees. > > -See linkgit:gitrepository-layout[5] for more information. The rule of > -thumb is do not make any assumption about whether a path belongs to > -$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something > -inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. > - > EXAMPLES > -------- > > > -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html