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

From: Marc Branchaud <[email-masked]>
Date: Mon, 22 Sep 2014 17:00:49 -0400

On 14-09-21 05:50 AM, Duy Nguyen wrote:
> On Sun, Sep 21, 2014 at 10:10 AM, Eric Sunshine <[email-masked]> 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
>  --------
> 
> 
>