Merge branch 'bc/object-id'
[gitweb.git] / Documentation / config.txt
index 4f41840fdc0fed4ad5cf469032c7f76811dd61f0..32f065ca6a9382ba7b496d9c6606a72941dc0c1f 100644 (file)
@@ -140,7 +140,7 @@ boolean::
        false;; Boolean false can be spelled as `no`, `off`,
                `false`, or `0`.
 +
-When converting value to the canonical form using '--bool' type
+When converting value to the canonical form using `--bool` type
 specifier; 'git config' will ensure that the output is "true" or
 "false" (spelled in lowercase).
 
@@ -150,27 +150,34 @@ integer::
        1024", "by 1024x1024", etc.
 
 color::
-       The value for a variables that takes a color is a list of
-       colors (at most two) and attributes (at most one), separated
-       by spaces.  The colors accepted are `normal`, `black`,
-       `red`, `green`, `yellow`, `blue`, `magenta`, `cyan` and
-       `white`; the attributes are `bold`, `dim`, `ul`, `blink` and
-       `reverse`.  The first color given is the foreground; the
-       second is the background.  The position of the attribute, if
-       any, doesn't matter. Attributes may be turned off specifically
-       by prefixing them with `no` (e.g., `noreverse`, `noul`, etc).
-+
-Colors (foreground and background) may also be given as numbers between
-0 and 255; these use ANSI 256-color mode (but note that not all
-terminals may support this).  If your terminal supports it, you may also
-specify 24-bit RGB values as hex, like `#ff0ab3`.
-+
-The attributes are meant to be reset at the beginning of each item
-in the colored output, so setting color.decorate.branch to `black`
-will paint that branch name in a plain `black`, even if the previous
-thing on the same output line (e.g. opening parenthesis before the
-list of branch names in `log --decorate` output) is set to be
-painted with `bold` or some other attribute.
+       The value for a variable that takes a color is a list of
+       colors (at most two, one for foreground and one for background)
+       and attributes (as many as you want), separated by spaces.
++
+The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`,
+`blue`, `magenta`, `cyan` and `white`.  The first color given is the
+foreground; the second is the background.
++
+Colors may also be given as numbers between 0 and 255; these use ANSI
+256-color mode (but note that not all terminals may support this).  If
+your terminal supports it, you may also specify 24-bit RGB values as
+hex, like `#ff0ab3`.
++
+The accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`,
+`italic`, and `strike` (for crossed-out or "strikethrough" letters).
+The position of any attributes with respect to the colors
+(before, after, or in between), doesn't matter. Specific attributes may
+be turned off by prefixing them with `no` or `no-` (e.g., `noreverse`,
+`no-ul`, etc).
++
+For git's pre-defined color slots, the attributes are meant to be reset
+at the beginning of each item in the colored output. So setting
+`color.decorate.branch` to `black` will paint that branch name in a
+plain `black`, even if the previous thing on the same output line (e.g.
+opening parenthesis before the list of branch names in `log --decorate`
+output) is set to be painted with `bold` or some other attribute.
+However, custom log formats may do more complicated and layered
+coloring, and the negated forms may be useful there.
 
 pathname::
        A variable that takes a pathname value can be given a
@@ -405,13 +412,11 @@ file with mixed line endings would be reported by the `core.safecrlf`
 mechanism.
 
 core.autocrlf::
-       Setting this variable to "true" is almost the same as setting
-       the `text` attribute to "auto" on all files except that text
-       files are not guaranteed to be normalized: files that contain
-       `CRLF` in the repository will not be touched.  Use this
-       setting if you want to have `CRLF` line endings in your
-       working directory even though the repository does not have
-       normalized line endings.  This variable can be set to 'input',
+       Setting this variable to "true" is the same as setting
+       the `text` attribute to "auto" on all files and core.eol to "crlf".
+       Set to true if you want to have `CRLF` line endings in your
+       working directory and the repository has LF line endings.
+       This variable can be set to 'input',
        in which case no output conversion is performed.
 
 core.symlinks::
@@ -443,6 +448,13 @@ specify that no proxy be used for a given domain pattern.
 This is useful for excluding servers inside a firewall from
 proxy use, while defaulting to a common proxy for external domains.
 
+core.sshCommand::
+       If this variable is set, `git fetch` and `git push` will
+       use the specified command instead of `ssh` when they need to
+       connect to a remote system. The command is in the same form as
+       the `GIT_SSH_COMMAND` environment variable and is overridden
+       when the environment variable is set.
+
 core.ignoreStat::
        If true, Git will avoid using lstat() calls to detect if files have
        changed by setting the "assume-unchanged" bit for those tracked files
@@ -481,7 +493,7 @@ core.worktree::
        If `GIT_COMMON_DIR` environment variable is set, core.worktree
        is ignored and not used for determining the root of working tree.
        This can be overridden by the `GIT_WORK_TREE` environment
-       variable and the '--work-tree' command-line option.
+       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.
@@ -779,7 +791,7 @@ core.abbrev::
 add.ignoreErrors::
 add.ignore-errors (deprecated)::
        Tells 'git add' to continue adding files when some files cannot be
-       added due to indexing errors. Equivalent to the '--ignore-errors'
+       added due to indexing errors. Equivalent to the `--ignore-errors`
        option of linkgit:git-add[1].  `add.ignore-errors` is deprecated,
        as it does not follow the usual naming convention for configuration
        variables.
@@ -805,9 +817,9 @@ from the original current directory. See linkgit:git-rev-parse[1].
 
 am.keepcr::
        If true, git-am will call git-mailsplit for patches in mbox format
-       with parameter '--keep-cr'. In this case git-mailsplit will
+       with parameter `--keep-cr`. In this case git-mailsplit will
        not remove `\r` from lines ending with `\r\n`. Can be overridden
-       by giving '--no-keep-cr' from the command line.
+       by giving `--no-keep-cr` from the command line.
        See linkgit:git-am[1], linkgit:git-mailsplit[1].
 
 am.threeWay::
@@ -820,7 +832,7 @@ am.threeWay::
 
 apply.ignoreWhitespace::
        When set to 'change', tells 'git apply' to ignore changes in
-       whitespace, in the same way as the '--ignore-space-change'
+       whitespace, in the same way as the `--ignore-space-change`
        option.
        When set to one of: no, none, never, false tells 'git apply' to
        respect all whitespace differences.
@@ -828,7 +840,7 @@ apply.ignoreWhitespace::
 
 apply.whitespace::
        Tells 'git apply' how to handle whitespaces, in the same way
-       as the '--whitespace' option. See linkgit:git-apply[1].
+       as the `--whitespace` option. See linkgit:git-apply[1].
 
 branch.autoSetupMerge::
        Tells 'git branch' and 'git checkout' to set up new branches
@@ -930,7 +942,7 @@ browser.<tool>.cmd::
 
 browser.<tool>.path::
        Override the path for the given tool that may be used to
-       browse HTML help (see '-w' option in linkgit:git-help[1]) or a
+       browse HTML help (see `-w` option in linkgit:git-help[1]) or a
        working repository in gitweb (see linkgit:git-instaweb[1]).
 
 clean.requireForce::
@@ -1189,6 +1201,15 @@ difftool.<tool>.cmd::
 difftool.prompt::
        Prompt before each invocation of the diff tool.
 
+fastimport.unpackLimit::
+       If the number of objects imported by linkgit:git-fast-import[1]
+       is below this limit, then the objects will be unpacked into
+       loose object files.  However if the number of imported objects
+       equals or exceeds this limit then the pack will be stored as a
+       pack.  Storing the pack from a fast-import can make the import
+       operation complete faster, especially on slow filesystems.  If
+       not set, the value of `transfer.unpackLimit` is used instead.
+
 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
@@ -1220,6 +1241,11 @@ fetch.prune::
        If true, fetch will automatically behave as if the `--prune`
        option was given on the command line.  See also `remote.<name>.prune`.
 
+fetch.output::
+       Control how ref update status is printed. Valid values are
+       `full` and `compact`. Default value is `full`. See section
+       OUTPUT in linkgit:git-fetch[1] for detail.
+
 format.attach::
        Enable multipart/mixed attachments as the default for
        'format-patch'.  The value can also be a double quoted string
@@ -1227,6 +1253,16 @@ format.attach::
        value as the boundary.  See the --attach option in
        linkgit:git-format-patch[1].
 
+format.from::
+       Provides the default value for the `--from` option to format-patch.
+       Accepts a boolean value, or a name and email address.  If false,
+       format-patch defaults to `--no-from`, using commit authors directly in
+       the "From:" field of patch mails.  If true, format-patch defaults to
+       `--from`, using your committer identity in the "From:" field of patch
+       mails and including a "From:" field in the body of the patch mail if
+       different.  If set to a non-boolean value, format-patch uses that
+       value instead of your committer identity.  Defaults to false.
+
 format.numbered::
        A boolean which can enable or disable sequence numbers in patch
        subjects.  It defaults to "auto" which enables it only if there
@@ -1420,9 +1456,9 @@ gitcvs.logFile::
 
 gitcvs.usecrlfattr::
        If true, the server will look up the end-of-line conversion
-       attributes for files to determine the '-k' modes to use. If
+       attributes for files to determine the `-k` modes to use. If
        the attributes force Git to treat a file as text,
-       the '-k' mode will be left blank so CVS clients will
+       the `-k` mode will be left blank so CVS clients will
        treat it as text. If they suppress text conversion, the file
        will be set with '-kb' mode, which suppresses any newline munging
        the client might otherwise do. If the attributes do not allow
@@ -1492,16 +1528,16 @@ gitweb.snapshot::
        See linkgit:gitweb.conf[5] for description.
 
 grep.lineNumber::
-       If set to true, enable '-n' option by default.
+       If set to true, enable `-n` option by default.
 
 grep.patternType::
        Set the default matching behavior. Using a value of 'basic', 'extended',
-       'fixed', or 'perl' will enable the '--basic-regexp', '--extended-regexp',
-       '--fixed-strings', or '--perl-regexp' option accordingly, while the
+       'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,
+       `--fixed-strings`, or `--perl-regexp` option accordingly, while the
        value 'default' will return to the default matching behavior.
 
 grep.extendedRegexp::
-       If set to true, enable '--extended-regexp' option by default. This
+       If set to true, enable `--extended-regexp` option by default. This
        option is ignored when the `grep.patternType` option is set to a value
        other than 'default'.
 
@@ -1958,7 +1994,7 @@ log.decorate::
        specified, the full ref name (including prefix) will be printed.
        If 'auto' is specified, then if the output is going to a terminal,
        the ref names are shown as if 'short' were given, otherwise no ref
-       names are shown. This is the same as the '--decorate' option
+       names are shown. This is the same as the `--decorate` option
        of the `git log`.
 
 log.follow::
@@ -2341,16 +2377,16 @@ new default).
 --
 
 push.followTags::
-       If set to true enable '--follow-tags' option by default.  You
+       If set to true enable `--follow-tags` option by default.  You
        may override this configuration at time of push by specifying
-       '--no-follow-tags'.
+       `--no-follow-tags`.
 
 push.gpgSign::
        May be set to a boolean value, or the string 'if-asked'. A true
-       value causes all pushes to be GPG signed, as if '--signed' is
+       value causes all pushes to be GPG signed, as if `--signed` is
        passed to linkgit:git-push[1]. The string 'if-asked' causes
        pushes to be signed if the server supports it, as if
-       '--signed=if-asked' is passed to 'git push'. A false value may
+       `--signed=if-asked` is passed to 'git push'. A false value may
        override a value from a lower-priority config file. An explicit
        command-line flag always overrides this config option.
 
@@ -2373,7 +2409,7 @@ rebase.stat::
        rebase. False by default.
 
 rebase.autoSquash::
-       If set to true enable '--autosquash' option by default.
+       If set to true enable `--autosquash` option by default.
 
 rebase.autoStash::
        When set to true, automatically create a temporary stash
@@ -2401,8 +2437,13 @@ rebase.instructionFormat
 
 receive.advertiseAtomic::
        By default, git-receive-pack will advertise the atomic push
-       capability to its clients. If you don't want to this capability
-       to be advertised, set this variable to false.
+       capability to its clients. If you don't want to advertise this
+       capability, set this variable to false.
+
+receive.advertisePushOptions::
+       By default, git-receive-pack will advertise the push options
+       capability to its clients. If you don't want to advertise this
+       capability, set this variable to false.
 
 receive.autogc::
        By default, git-receive-pack will run "git-gc --auto" after
@@ -2457,6 +2498,15 @@ receive.fsck.skipList::
        can be safely ignored such as invalid committer email addresses.
        Note: corrupt objects cannot be skipped with this setting.
 
+receive.keepAlive::
+       After receiving the pack from the client, `receive-pack` may
+       produce no output (if `--quiet` was specified) while processing
+       the pack, causing some networks to drop the TCP connection.
+       With this option set, if `receive-pack` does not transmit
+       any data in this phase for `receive.keepAlive` seconds, it will
+       send a short keepalive packet.  The default is 5 seconds; set
+       to 0 to disable keepalives entirely.
+
 receive.unpackLimit::
        If the number of objects received in a push is below this
        limit then the objects will be unpacked into loose object
@@ -2467,6 +2517,12 @@ receive.unpackLimit::
        especially on slow filesystems.  If not set, the value of
        `transfer.unpackLimit` is used instead.
 
+receive.maxInputSize::
+       If the size of the incoming pack stream is larger than this
+       limit, then git-receive-pack will error out, instead of
+       accepting the pack file. If not set or set to 0, then the size
+       is unlimited.
+
 receive.denyDeletes::
        If set to true, git-receive-pack will deny a ref update that deletes
        the ref. Use this to prevent such a ref deletion via a push.
@@ -2797,6 +2853,18 @@ submodule.fetchJobs::
        in parallel. A value of 0 will give some reasonable default.
        If unset, it defaults to 1.
 
+submodule.alternateLocation::
+       Specifies how the submodules obtain alternates when submodules are
+       cloned. Possible values are `no`, `superproject`.
+       By default `no` is assumed, which doesn't add references. When the
+       value is set to `superproject` the submodule to be cloned computes
+       its alternates location relative to the superprojects alternate.
+
+submodule.alternateErrorStrategy
+       Specifies how to treat errors with the alternates for a submodule
+       as computed via `submodule.alternateLocation`. Possible values are
+       `ignore`, `info`, `die`. Default is `die`.
+
 tag.forceSignAnnotated::
        A boolean to specify whether annotated tags created should be GPG signed.
        If `--annotate` is specified on the command line, it takes
@@ -2883,6 +2951,21 @@ uploadpack.keepAlive::
        `uploadpack.keepAlive` seconds. Setting this option to 0
        disables keepalive packets entirely. The default is 5 seconds.
 
+uploadpack.packObjectsHook::
+       If this option is set, when `upload-pack` would run
+       `git pack-objects` to create a packfile for a client, it will
+       run this shell command instead.  The `pack-objects` command and
+       arguments it _would_ have run (including the `git pack-objects`
+       at the beginning) are appended to the shell command. The stdin
+       and stdout of the hook are treated as if `pack-objects` itself
+       was run. I.e., `upload-pack` will feed input intended for
+       `pack-objects` to the hook, and expects a completed packfile on
+       stdout.
++
+Note that this configuration variable is ignored if it is seen in the
+repository-level config (this is a safety measure against fetching from
+untrusted repositories).
+
 url.<base>.insteadOf::
        Any URL that starts with this value will be rewritten to
        start, instead, with <base>. In cases where some site serves a