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

Nguyen Thai Ngoc Duy [off-list ref] writes:

On Sat, Jan 22, 2011 at 3:58 AM, Junio C Hamano [off-list ref] wrote:

quoted

I was re-reading this thread, and changed my mind; I think we should have
this series to avoid unnecessary regression, with or without clarifying
(5), before 1.7.4 final.

Sorry for late response. If we no longer consider this work-around,
perhaps git.txt and config.txt should be updated to reflect it?

I am Ok with us considering this as a "work-around"; as long as we keep it
alive, the label does not matter much.

And the necessity of documentation updates you raised is really a good
point.  Something like this (on top of jn/setup-fixes branch queued in
next)?


 Documentation/config.txt |   23 ++++++++++++++++-------
 Documentation/git.txt    |   13 ++++---------
 2 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index ff7c225..72b74c4 100644
--- 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.
 	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 relative path to the directory specified by
-	--git-dir or GIT_DIR.
-	Note: If --git-dir or GIT_DIR are specified but none of
+	an absolute path or a relative path to the .git directory,
+	either specified by --git-dir or GIT_DIR, or automatically
+	discovered.
+	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.
++
+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.  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).
 
 core.logAllRefUpdates::
 	Enable the reflog. Updates to a ref <ref> is logged to the file

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 4e5fe4d..245d84f 100644
--- 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.
 	This can also be controlled by setting the GIT_WORK_TREE
 	environment variable and the core.worktree configuration
-	variable. It can be an absolute path or relative path to
-	current working directory.
-	Note: 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
-	of your working tree.
+	variable (see core.worktree in linkgit:git-config[1] for a
+	more detailed discussion).
 
 --bare::
 	Treat the repository as a bare repository.  If GIT_DIR

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 [off-list ref]

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

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.