Merge branch 'jc/maint-1.7.4-pathspec-stdin-and-cmdline'
[gitweb.git] / Documentation / config.txt
index 4f1e9799321380739afe96dd7ec841b768ae988b..0906499e7d26ac1e808f3a598675a32a7ad72739 100644 (file)
@@ -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,24 +317,26 @@ false), while all other repositories are assumed to be bare (bare
 = true).
 
 core.worktree::
-       Set the path to the root of the work tree.
+       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 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
+       variable and the '--work-tree' command line option.
+       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.
+       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 root of the
-       work tree.
+       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
+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
+misconfiguration.  Running git commands in the "/path/to" directory will
 still use "/different/path" as the root of the work tree and can cause
-great confusion to the users.
+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
@@ -440,8 +442,6 @@ for most projects as source code and other text files can still
 be delta compressed, but larger binary media files won't be.
 +
 Common unit suffixes of 'k', 'm', or 'g' are supported.
-+
-Currently only linkgit:git-fast-import[1] honors this setting.
 
 core.excludesfile::
        In addition to '.gitignore' (per-directory) and
@@ -459,6 +459,12 @@ core.askpass::
        prompt. The external program shall be given a suitable prompt as
        command line argument and write the password on its STDOUT.
 
+core.attributesfile::
+       In addition to '.gitattributes' (per-directory) and
+       '.git/info/attributes', git looks into this file for attributes
+       (see linkgit:gitattributes[5]). Path expansions are made the same
+       way as for `core.excludesfile`.
+
 core.editor::
        Commands such as `commit` and `tag` that lets you edit
        messages by launching an editor uses the value of this
@@ -507,6 +513,9 @@ core.whitespace::
   part of the line terminator, i.e. with it, `trailing-space`
   does not trigger if the character before such a carriage-return
   is not a whitespace (not enabled by default).
+* `tabwidth=<n>` tells how many character positions a tab occupies; this
+  is relevant for `indent-with-non-tab` and when git fixes `tab-in-indent`
+  errors. The default tab width is 8. Allowed values are 1 to 63.
 
 core.fsyncobjectfiles::
        This boolean will enable 'fsync()' when writing object files.
@@ -547,6 +556,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
@@ -599,8 +614,9 @@ branch.autosetupmerge::
        this behavior can be chosen per-branch using the `--track`
        and `--no-track` options. The valid settings are: `false` -- no
        automatic setup is done; `true` -- automatic setup is done when the
-       starting point is a remote branch; `always` -- automatic setup is
-       done when the starting point is either a local branch or remote
+       starting point is a remote-tracking branch; `always` --
+       automatic setup is done when the starting point is either a
+       local branch or remote-tracking
        branch. This option defaults to true.
 
 branch.autosetuprebase::
@@ -611,7 +627,7 @@ branch.autosetuprebase::
        When `local`, rebase is set to true for tracked branches of
        other local branches.
        When `remote`, rebase is set to true for tracked branches of
-       remote branches.
+       remote-tracking branches.
        When `always`, rebase will be set to true for all tracking
        branches.
        See "branch.autosetupmerge" for details on how to set up a
@@ -678,7 +694,7 @@ color.branch::
 color.branch.<slot>::
        Use customized color for branch coloration. `<slot>` is one of
        `current` (the current branch), `local` (a local branch),
-       `remote` (a tracking branch in refs/remotes/), `plain` (other
+       `remote` (a remote-tracking branch in refs/remotes/), `plain` (other
        refs).
 +
 The value for these configuration variables is a list of colors (at most
@@ -706,7 +722,7 @@ color.diff.<slot>::
 color.decorate.<slot>::
        Use customized color for 'git log --decorate' output.  `<slot>` is one
        of `branch`, `remoteBranch`, `tag`, `stash` or `HEAD` for local
-       branches, remote tracking branches, tags, stash and HEAD, respectively.
+       branches, remote-tracking branches, tags, stash and HEAD, respectively.
 
 color.grep::
        When set to `always`, always highlight matches.  When `false` (or
@@ -771,7 +787,8 @@ color.status.<slot>::
        one of `header` (the header text of the status message),
        `added` or `updated` (files which are added but not committed),
        `changed` (files which are changed but not added in the index),
-       `untracked` (files which are not tracked by git), or
+       `untracked` (files which are not tracked by git),
+       `branch` (the current branch), or
        `nobranch` (the color the 'no branch' warning is shown in, defaulting
        to red). The values of these variables may be specified as in
        color.branch.<slot>.
@@ -877,6 +894,15 @@ diff.wordRegex::
        sequences that match the regular expression are "words", all other
        characters are *ignorable* whitespace.
 
+fetch.recurseSubmodules::
+       This option can be either set to a boolean value or to 'on-demand'.
+       Setting it to a boolean changes the behavior of fetch and pull to
+       unconditionally recurse into submodules when set to true or to not
+       recurse at all when set to false. When set to 'on-demand' (the default
+       value), fetch and pull will only recurse into a populated submodule
+       when its superproject retrieves a commit that updates the submodule's
+       reference.
+
 fetch.unpackLimit::
        If the number of objects fetched over the git native
        transfer is below this
@@ -1074,6 +1100,12 @@ All gitcvs variables except for 'gitcvs.usecrlfattr' and
 is one of "ext" and "pserver") to make them apply only for the given
 access method.
 
+grep.lineNumber::
+       If set to true, enable '-n' option by default.
+
+grep.extendedRegexp::
+       If set to true, enable '--extended-regexp' option by default.
+
 gui.commitmsgwidth::
        Defines how wide the commit message window is in the
        linkgit:git-gui[1]. "75" is the default.
@@ -1100,7 +1132,7 @@ gui.newbranchtemplate::
        linkgit:git-gui[1].
 
 gui.pruneduringfetch::
-       "true" if linkgit:git-gui[1] should prune tracking branches when
+       "true" if linkgit:git-gui[1] should prune remote-tracking branches when
        performing a fetch. The default value is "false".
 
 gui.trustmtime::
@@ -1529,11 +1561,13 @@ pack.packSizeLimit::
        supported.
 
 pager.<cmd>::
-       Allows turning on or off pagination of the output of a
-       particular git subcommand when writing to a tty.  If
-       `\--paginate` or `\--no-pager` is specified on the command line,
-       it takes precedence over this option.  To disable pagination for
-       all commands, set `core.pager` or `GIT_PAGER` to `cat`.
+       If the value is boolean, turns on or off pagination of the
+       output of a particular git subcommand when writing to a tty.
+       Otherwise, turns on pagination for the subcommand using the
+       pager specified by the value of `pager.<cmd>`.  If `\--paginate`
+       or `\--no-pager` is specified on the command line, it takes
+       precedence over this option.  To disable pagination for all
+       commands, set `core.pager` or `GIT_PAGER` to `cat`.
 
 pretty.<name>::
        Alias for a --pretty= format string, as specified in
@@ -1562,7 +1596,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::
@@ -1735,6 +1770,7 @@ sendemail.to::
 sendemail.smtpdomain::
 sendemail.smtpserver::
 sendemail.smtpserverport::
+sendemail.smtpserveroption::
 sendemail.smtpuser::
 sendemail.thread::
 sendemail.validate::
@@ -1788,6 +1824,13 @@ submodule.<name>.update::
        URL and other values found in the `.gitmodules` file.  See
        linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.
 
+submodule.<name>.fetchRecurseSubmodules::
+       This option can be used to control recursive fetching of this
+       submodule. It can be overridden by using the --[no-]recurse-submodules
+       command line option to "git fetch" and "git pull".
+       This setting will override that from in the linkgit:gitmodules[5]
+       file.
+
 submodule.<name>.ignore::
        Defines under what circumstances "git status" and the diff family show
        a submodule as modified. When set to "all", it will never be considered