Subject: Re: [PATCH 3/3] setup: always honor GIT_WORK_TREE and core.worktree

From: Jonathan Nieder <[email-masked]>
Date: Mon, 24 Jan 2011 02:45:53 -0600

Junio C Hamano wrote:

> Something like this (on top of jn/setup-fixes branch queued in
> next)?

For what it's worth,
 Acked-by: Jonathan Nieder <[email-masked]>

> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -317,17 +317,26 @@ false), while all other repositories are assumed to be bare (bare
>  = true).
>  
>  core.worktree::
> -	Set the path to the working tree.  The value will not be
> -	used in combination with repositories found automatically in
> -	a .git directory (i.e. $GIT_DIR is not set).
> +	Set the path to the root of the work tree.

Most manpages seem to stick to the phrase "working tree".  Not sure
if that's worth worrying about --- maybe it would be good to allow or
encourage usage to drift to the term "work tree" that gets used in
many parts of the interface.

>  	This can be overridden by the GIT_WORK_TREE environment
>  	variable and the '--work-tree' command line option. It can be
> +	an absolute path or a relative path to the .git directory,
> +	either specified by --git-dir or GIT_DIR, or automatically
> +	discovered.

Maybe:

	The value can be an absolute path or relative to the path to
	the .git directory, which is either specified by --git-dir or
	GIT_DIR or automatically discovered.

> -	an absolute path or relative path to the directory specified by
> -	--git-dir or GIT_DIR.
> -	Note: If --git-dir or GIT_DIR are specified but none of
> +	If --git-dir or GIT_DIR are specified but none of
>  	--work-tree, GIT_WORK_TREE and core.worktree is specified,
> -	the current working directory is regarded as the top directory
> +	the current working directory is regarded as the top level
>  	of your working tree.

Subject-verb agreement: "--git-dir or GIT_DIR is specified" (s/are/is/)

> ++
> +Note that this variable is honored even when set in a configuration
> +file in a ".git" subdirectory of a directory, and its value differs
> +from the latter directory (e.g. "/path/to/.git/config" has
> +core.worktree set to "/different/path"), which is most likely a
> +misconfiguration.

I think it's clearer without the comma between "directory" and "and"
(otherwise, it's too easy to parse as

	Note that this variable is honored even when set ....
	Its value differs from the latter directory, which is most
	likely a misconfiguration.

).

> +                   Running git commands in "/path/to" directory will
> +still use "/different/path" as the root of the work tree and can cause
> +confusion, unless you know what you are doing (e.g. you are creating a
> +read-only snapshot of the same index to a location different from the
> +repository's usual working tree).

Missing article: s,in "path/to" directory,in the "/path/to" directory,

Comma usage: s/confusion, unless/confusion unless/ to avoid misparsing
this as meaning "will use this work tree unless you know what you are
doing".

> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -291,17 +291,12 @@ help ...`.
>  	path or relative path to current working directory.
>  
>  --work-tree=<path>::
> -	Set the path to the working tree.  The value will not be
> -	used in combination with repositories found automatically in
> -	a .git directory (i.e. $GIT_DIR is not set).
> +	Set the path to the working tree. It can be an absolute path
> +	or relative path to the current working directory.

s/relative path to/path relative to/

>  	This can also be controlled by setting the GIT_WORK_TREE
>  	environment variable and the core.worktree configuration
> +	variable (see core.worktree in linkgit:git-config[1] for a
> +	more detailed discussion).
> -	variable. It can be an absolute path or relative path to
[...]

Nice.