Merge branch 'lt/default-abbrev' into maint

[thirdparty/git.git] / Documentation / config.txt

diff --git a/Documentation/config.txt b/Documentation/config.txt
index ff7c225467b5da3263b6e8f8924adefeea404a8a..52ffbf4efb8d17c22893112208c5864d4c19741d 100644 (file)
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -62,7 +62,7 @@ Internal whitespace within a variable value is retained verbatim.
 
 The values following the equals sign in variable assign are all either
 a string, an integer, or a boolean.  Boolean values may be given as yes/no,
-0/1, true/false or on/off.  Case is not significant in boolean values, when
+1/0, true/false or on/off.  Case is not significant in boolean values, when
 converting value to the canonical form using '--bool' type specifier;
 'git config' will ensure that the output is "true" or "false".
 
@@ -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
@@ -367,15 +376,6 @@ core.warnAmbiguousRefs::
        If true, git will warn you if the ref name you passed it is ambiguous
        and might match multiple refs in the .git/refs/ tree. True by default.
 
-core.abbrevguard::
-       Even though git makes sure that it uses enough hexdigits to show
-       an abbreviated object name unambiguously, as more objects are
-       added to the repository over time, a short name that used to be
-       unique will stop being unique.  Git uses this many extra hexdigits
-       that are more than necessary to make the object name currently
-       unique, in the hope that its output will stay unique a bit longer.
-       Defaults to 0.
-
 core.compression::
        An integer -1..9, indicating a default compression level.
        -1 is the zlib default. 0 means no compression,
@@ -558,6 +558,12 @@ core.sparseCheckout::
        Enable "sparse checkout" feature. See section "Sparse checkout" in
        linkgit:git-read-tree[1] for more information.
 
+core.abbrev::
+       Set the length object names are abbreviated to.  If unspecified,
+       many commands abbreviate to 7 hexdigits, which may not be enough
+       for abbreviated object names to stay unique for sufficiently long
+       time.
+
 add.ignore-errors::
 add.ignoreErrors::
        Tells 'git add' to continue adding files when some files cannot be
@@ -1582,7 +1588,8 @@ push.default::
 * `matching` - push all matching branches.
   All branches having the same name in both ends are considered to be
   matching. This is the default.
-* `tracking` - push the current branch to its upstream branch.
+* `upstream` - push the current branch to its upstream branch.
+* `tracking` - deprecated synonym for `upstream`.
 * `current` - push the current branch to a branch of the same name.
 
 rebase.stat::