Merge branch 'jl/status-added-submodule-is-never-ignored' into maint
[git/git.git] / Documentation / config.txt
index 2ecce05..c08286e 100644 (file)
@@ -78,8 +78,8 @@ be escaped: use `\"` for `"` and `\\` for `\`.
 
 The following escape sequences (beside `\"` and `\\`) are recognized:
 `\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB)
-and `\b` for backspace (BS).  No other char escape sequence, nor octal
-char sequences are valid.
+and `\b` for backspace (BS).  Other char escape sequences (including octal
+escape sequences) are invalid.
 
 Variable values ending in a `\` are continued on the next line in the
 customary UNIX fashion.
@@ -131,8 +131,13 @@ Variables
 
 Note that this list is non-comprehensive and not necessarily complete.
 For command-specific variables, you will find a more detailed description
-in the appropriate manual page. You will find a description of non-core
-porcelain configuration variables in the respective porcelain documentation.
+in the appropriate manual page.
+
+Other git-related tools may and do use their own variables.  When
+inventing new variables for use in your own tool, make sure their
+names do not conflict with those that are used by Git itself and
+other popular tools, and describe them in your documentation.
+
 
 advice.*::
        These variables control various optional help messages designed to
@@ -142,19 +147,13 @@ advice.*::
 --
        pushUpdateRejected::
                Set this variable to 'false' if you want to disable
-               'pushNonFFCurrent', 'pushNonFFDefault',
+               'pushNonFFCurrent',
                'pushNonFFMatching', 'pushAlreadyExists',
                'pushFetchFirst', and 'pushNeedsForce'
                simultaneously.
        pushNonFFCurrent::
                Advice shown when linkgit:git-push[1] fails due to a
                non-fast-forward update to the current branch.
-       pushNonFFDefault::
-               Advice to set 'push.default' to 'upstream' or 'current'
-               when you ran linkgit:git-push[1] and pushed 'matching
-               refs' by default (i.e. you did not provide an explicit
-               refspec, and no 'push.default' configuration was set)
-               and it resulted in a non-fast-forward error.
        pushNonFFMatching::
                Advice shown when you ran linkgit:git-push[1] and pushed
                'matching refs' explicitly (i.e. you used ':', or
@@ -827,7 +826,7 @@ color.diff::
        commands will only use color when output is to the terminal.
        Defaults to false.
 +
-This does not affect linkgit:git-format-patch[1] nor the
+This does not affect linkgit:git-format-patch[1] or the
 'git-diff-{asterisk}' plumbing commands.  Can be overridden on the
 command line with the `--color[=<when>]` option.
 
@@ -992,6 +991,14 @@ commit.cleanup::
        have to remove the help lines that begin with `#` in the commit log
        template yourself, if you do this).
 
+commit.gpgsign::
+
+       A boolean to specify whether all commits should be GPG signed.
+       Use of this option when doing operations such as rebase can
+       result in a large number of commits being signed. It may be
+       convenient to use an agent to avoid typing your GPG passphrase
+       several times.
+
 commit.status::
        A boolean to enable/disable inclusion of status information in the
        commit message template when using an editor to prepare the commit
@@ -1149,6 +1156,11 @@ filter.<driver>.smudge::
        object to a worktree file upon checkout.  See
        linkgit:gitattributes[5] for details.
 
+gc.aggressiveDepth::
+       The depth parameter used in the delta compression
+       algorithm used by 'git gc --aggressive'.  This defaults
+       to 250.
+
 gc.aggressiveWindow::
        The window size parameter used in the delta compression
        algorithm used by 'git gc --aggressive'.  This defaults
@@ -1167,6 +1179,10 @@ gc.autopacklimit::
        --auto` consolidates them into one larger pack.  The
        default value is 50.  Setting this to 0 disables it.
 
+gc.autodetach::
+       Make `git gc --auto` return immediately andrun in background
+       if the system supports it. Default is true.
+
 gc.packrefs::
        Running `git pack-refs` in a repository renders it
        unclonable by Git versions prior to 1.5.1.2 over dumb
@@ -1324,6 +1340,10 @@ gui.diffcontext::
        Specifies how many context lines should be used in calls to diff
        made by the linkgit:git-gui[1]. The default is "5".
 
+gui.displayuntracked::
+       Determines if linkgit::git-gui[1] shows untracked files
+       in the file list. The default is "true".
+
 gui.encoding::
        Specifies the default encoding to use for displaying of
        file contents in linkgit:git-gui[1] and linkgit:gitk[1].
@@ -1601,6 +1621,10 @@ imap::
        The configuration variables in the 'imap' section are described
        in linkgit:git-imap-send[1].
 
+index.version::
+       Specify the version with which new index files should be
+       initialized.  This does not affect existing repositories.
+
 init.templatedir::
        Specify the directory from which templates will be copied.
        (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
@@ -1633,7 +1657,7 @@ interactive.singlekey::
        linkgit:git-add[1], linkgit:git-checkout[1], linkgit:git-commit[1],
        linkgit:git-reset[1], and linkgit:git-stash[1]. Note that this
        setting is silently ignored if portable keystroke input
-       is not available.
+       is not available; requires the Perl module Term::ReadKey.
 
 log.abbrevCommit::
        If true, makes linkgit:git-log[1], linkgit:git-show[1], and
@@ -1862,6 +1886,31 @@ pack.packSizeLimit::
        Common unit suffixes of 'k', 'm', or 'g' are
        supported.
 
+pack.useBitmaps::
+       When true, git will use pack bitmaps (if available) when packing
+       to stdout (e.g., during the server side of a fetch). Defaults to
+       true. You should not generally need to turn this off unless
+       you are debugging pack bitmaps.
+
+pack.writebitmaps::
+       When true, git will write a bitmap index when packing all
+       objects to disk (e.g., when `git repack -a` is run).  This
+       index can speed up the "counting objects" phase of subsequent
+       packs created for clones and fetches, at the cost of some disk
+       space and extra time spent on the initial repack.  Defaults to
+       false.
+
+pack.writeBitmapHashCache::
+       When true, git will include a "hash cache" section in the bitmap
+       index (if one is written). This cache can be used to feed git's
+       delta heuristics, potentially leading to better deltas between
+       bitmapped and non-bitmapped objects (e.g., when serving a fetch
+       between an older, bitmapped pack and objects that have been
+       pushed since the last gc). The downside is that it consumes 4
+       bytes per object of disk space, and that JGit's bitmap
+       implementation does not understand it, causing it to complain if
+       Git and JGit are used on the same repository. Defaults to false.
+
 pager.<cmd>::
        If the value is boolean, turns on or off pagination of the
        output of a particular Git subcommand when writing to a tty.
@@ -1881,6 +1930,16 @@ pretty.<name>::
        Note that an alias with the same name as a built-in format
        will be silently ignored.
 
+pull.ff::
+       By default, Git does not create an extra merge commit when merging
+       a commit that is a descendant of the current commit. Instead, the
+       tip of the current branch is fast-forwarded. When set to `false`,
+       this variable tells Git to create an extra merge commit in such
+       a case (equivalent to giving the `--no-ff` option from the command
+       line). When set to `only`, only such fast-forward merges are
+       allowed (equivalent to giving the `--ff-only` option from the
+       command line).
+
 pull.rebase::
        When true, rebase branches on top of the fetched branch, instead
        of merging the default branch from the default remote when "git
@@ -1933,7 +1992,7 @@ When pushing to a remote that is different from the remote you normally
 pull from, work as `current`.  This is the safest option and is suited
 for beginners.
 +
-This mode will become the default in Git 2.0.
+This mode has become the default in Git 2.0.
 
 * `matching` - push all branches having the same name on both ends.
   This makes the repository you are pushing to remember the set of
@@ -1952,8 +2011,8 @@ suitable for pushing into a shared central repository, as other
 people may add new branches there, or update the tip of existing
 branches outside your control.
 +
-This is currently the default, but Git 2.0 will change the default
-to `simple`.
+This used to be the default, but not since Git 2.0 (`simple` is the
+new default).
 
 --
 
@@ -2111,6 +2170,13 @@ repack.usedeltabaseoffset::
        "false" and repack. Access from old Git versions over the
        native protocol are unaffected by this option.
 
+repack.packKeptObjects::
+       If set to true, makes `git repack` act as if
+       `--pack-kept-objects` was passed. See linkgit:git-repack[1] for
+       details. Defaults to `false` normally, but `true` if a bitmap
+       index is being written (either via `--write-bitmap-index` or
+       `pack.writeBitmaps`).
+
 rerere.autoupdate::
        When set to true, `git-rerere` updates the index with the
        resulting contents after it cleanly resolves conflicts using
@@ -2295,6 +2361,13 @@ transfer.unpackLimit::
        not set, the value of this variable is used instead.
        The default value is 100.
 
+uploadarchive.allowUnreachable::
+       If true, allow clients to use `git archive --remote` to request
+       any tree, whether reachable from the ref tips or not. See the
+       discussion in the `SECURITY` section of
+       linkgit:git-upload-archive[1] for more details. Defaults to
+       `false`.
+
 uploadpack.hiderefs::
        String(s) `upload-pack` uses to decide which refs to omit
        from its initial advertisement.  Use more than one