Documentation updates for 'GIT_WORK_TREE without GIT_DIR' historical usecase

Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config.txt b/Documentation/config.txt
index ff7c225467b5da3263b6e8f8924adefeea404a8a..c5e183516a104e6efb7ed597fb4498d75560ab68 100644 (file)
--- 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 working 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
+       variable and the '--work-tree' command line option.
+       The value can 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.
+       If --git-dir or GIT_DIR is 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 the "/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 4e5fe4d4b53f3706be2f7daa72beb20f376de603..0dac7aab573b68e447eebd9102179b309030b62f 100644 (file)
--- 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 a path relative 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