Re: [PATCH v2 22/32] checkout: support checking out into a new working directory

From: Marc Branchaud <marcnarc@xiplink.com>
Date: Sep 22, 2014, 21:00 UTC
Message-ID: <54208E01.2060205@xiplink.com>
In-Reply-To: <CACsJy8CH8mQjexFU1jO1orzajiwTXy4wJ022nq1PEY2GLUGAZA@mail.gmail.com>

On 14-09-21 05:50 AM, Duy Nguyen wrote:

Show 6 quoted lines

> On Sun, Sep 21, 2014 at 10:10 AM, Eric Sunshine <sunshine@sunshineco.com> 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.

Show 31 quoted lines

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