notes: implement helpers needed for note copying during rewrite
[gitweb.git] / Documentation / config.txt
index a8e0876a2add7bb53d3194b1f5e0a2031dd19a42..2e02f1b075de1b47cc05e2dc5cbe68526ebc0719 100644 (file)
@@ -64,7 +64,7 @@ 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
 converting value to the canonical form using '--bool' type specifier;
-'git-config' will ensure that the output is "true" or "false".
+'git config' will ensure that the output is "true" or "false".
 
 String values may be entirely or partially enclosed in double quotes.
 You need to enclose variable values in double quotes if you want to
@@ -130,6 +130,14 @@ advice.*::
                Advice shown when linkgit:git-merge[1] refuses to
                merge to avoid overwritting local changes.
                Default: true.
+       resolveConflict::
+               Advices shown by various commands when conflicts
+               prevent the operation from being performed.
+               Default: true.
+       implicitIdentity::
+               Advice on how to set your identity configuration when
+               your information is guessed from the system username and
+               domain name. Default: true.
 --
 
 core.fileMode::
@@ -297,17 +305,24 @@ 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 work tree.
        This can be overridden by the GIT_WORK_TREE environment
        variable and the '--work-tree' command line option. It can be
-       a 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
+       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
        --work-tree, GIT_WORK_TREE and core.worktree is specified,
-       the current working directory is regarded as the top directory
-       of your working tree.
+       the current working directory is regarded as the root of the
+       work 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 "/path/to" directory will
+still use "/different/path" as the root of the work tree and can cause
+great confusion to the users.
 
 core.logAllRefUpdates::
        Enable the reflog. Updates to a ref <ref> is logged to the file
@@ -435,8 +450,8 @@ core.pager::
 
 core.whitespace::
        A comma separated list of common whitespace problems to
-       notice.  'git-diff' will use `color.diff.whitespace` to
-       highlight them, and 'git-apply --whitespace=error' will
+       notice.  'git diff' will use `color.diff.whitespace` to
+       highlight them, and 'git apply --whitespace=error' will
        consider them as errors.  You can prefix `-` to disable
        any of them (e.g. `-trailing-space`):
 +
@@ -485,18 +500,24 @@ check that makes sure that existing object files will not get overwritten.
 core.notesRef::
        When showing commit messages, also show notes which are stored in
        the given ref.  This ref is expected to contain files named
-       after the full SHA-1 of the commit they annotate.
+       after the full SHA-1 of the commit they annotate.  The ref
+       must be fully qualified.
 +
 If such a file exists in the given ref, the referenced blob is read, and
-appended to the commit message, separated by a "Notes:" line.  If the
+appended to the commit message, separated by a "Notes (<refname>):"
+line (shortened to "Notes:" in the case of "refs/notes/commits").  If the
 given ref itself does not exist, it is not an error, but means that no
 notes should be printed.
 +
 This setting defaults to "refs/notes/commits", and can be overridden by
 the `GIT_NOTES_REF` environment variable.
 
+core.sparseCheckout::
+       Enable "sparse checkout" feature. See section "Sparse checkout" in
+       linkgit:git-read-tree[1] for more information.
+
 add.ignore-errors::
-       Tells 'git-add' to continue adding files when some files cannot be
+       Tells 'git add' to continue adding files when some files cannot be
        added due to indexing errors. Equivalent to the '--ignore-errors'
        option of linkgit:git-add[1].
 
@@ -518,19 +539,19 @@ executed from the top-level directory of a repository, which may
 not necessarily be the current directory.
 
 apply.ignorewhitespace::
-       When set to 'change', tells 'git-apply' to ignore changes in
+       When set to 'change', tells 'git apply' to ignore changes in
        whitespace, in the same way as the '--ignore-space-change'
        option.
-       When set to one of: no, none, never, false tells 'git-apply' to
+       When set to one of: no, none, never, false tells 'git apply' to
        respect all whitespace differences.
        See linkgit:git-apply[1].
 
 apply.whitespace::
-       Tells 'git-apply' how to handle whitespaces, in the same way
+       Tells 'git apply' how to handle whitespaces, in the same way
        as the '--whitespace' option. See linkgit:git-apply[1].
 
 branch.autosetupmerge::
-       Tells 'git-branch' and 'git-checkout' to setup new branches
+       Tells 'git branch' and 'git checkout' to set up new branches
        so that linkgit:git-pull[1] will appropriately merge from the
        starting point branch. Note that even if this option is not set,
        this behavior can be chosen per-branch using the `--track`
@@ -541,7 +562,7 @@ branch.autosetupmerge::
        branch. This option defaults to true.
 
 branch.autosetuprebase::
-       When a new branch is created with 'git-branch' or 'git-checkout'
+       When a new branch is created with 'git branch' or 'git checkout'
        that tracks another branch, this variable tells git to set
        up pull to rebase instead of merge (see "branch.<name>.rebase").
        When `never`, rebase is never automatically set to true.
@@ -556,24 +577,24 @@ branch.autosetuprebase::
        This option defaults to never.
 
 branch.<name>.remote::
-       When in branch <name>, it tells 'git-fetch' and 'git-push' which
+       When in branch <name>, it tells 'git fetch' and 'git push' which
        remote to fetch from/push to.  It defaults to `origin` if no remote is
        configured. `origin` is also used if you are not on any branch.
 
 branch.<name>.merge::
        Defines, together with branch.<name>.remote, the upstream branch
-       for the given branch. It tells 'git-fetch'/'git-pull' which
-       branch to merge and can also affect 'git-push' (see push.default).
-       When in branch <name>, it tells 'git-fetch' the default
+       for the given branch. It tells 'git fetch'/'git pull' which
+       branch to merge and can also affect 'git push' (see push.default).
+       When in branch <name>, it tells 'git fetch' the default
        refspec to be marked for merging in FETCH_HEAD. The value is
        handled like the remote part of a refspec, and must match a
        ref which is fetched from the remote given by
        "branch.<name>.remote".
-       The merge information is used by 'git-pull' (which at first calls
-       'git-fetch') to lookup the default branch for merging. Without
-       this option, 'git-pull' defaults to merge the first refspec fetched.
+       The merge information is used by 'git pull' (which at first calls
+       'git fetch') to lookup the default branch for merging. Without
+       this option, 'git pull' defaults to merge the first refspec fetched.
        Specify multiple values to get an octopus merge.
-       If you wish to setup 'git-pull' so that it merges into <name> from
+       If you wish to setup 'git pull' so that it merges into <name> from
        another branch in the local repository, you can point
        branch.<name>.merge to the desired branch, and use the special setting
        `.` (a period) for branch.<name>.remote.
@@ -635,24 +656,16 @@ color.diff.<slot>::
        Use customized color for diff colorization.  `<slot>` specifies
        which part of the patch to use the specified color, and is one
        of `plain` (context text), `meta` (metainformation), `frag`
-       (hunk header), `old` (removed lines), `new` (added lines),
-       `commit` (commit headers), or `whitespace` (highlighting
-       whitespace errors). The values of these variables may be specified as
-       in color.branch.<slot>.
+       (hunk header), 'func' (function in hunk header), `old` (removed lines),
+       `new` (added lines), `commit` (commit headers), or `whitespace`
+       (highlighting whitespace errors). The values of these variables may be
+       specified as in color.branch.<slot>.
 
 color.grep::
        When set to `always`, always highlight matches.  When `false` (or
        `never`), never.  When set to `true` or `auto`, use color only
        when the output is written to the terminal.  Defaults to `false`.
 
-color.grep.external::
-       The string value of this variable is passed to an external 'grep'
-       command as a command line option if match highlighting is turned
-       on.  If set to an empty string, no option is passed at all,
-       turning off coloring for external 'grep' calls; this is the default.
-       For GNU grep, set it to `--color=always` to highlight matches even
-       when a pager is used.
-
 color.grep.match::
        Use customized color for matches.  The value of this variable
        may be specified as in color.branch.<slot>.  It is passed using
@@ -666,7 +679,7 @@ color.interactive::
        colors only when the output is to the terminal. Defaults to false.
 
 color.interactive.<slot>::
-       Use customized color for 'git-add --interactive'
+       Use customized color for 'git add --interactive'
        output. `<slot>` may be `prompt`, `header`, `help` or `error`, for
        four distinct types of normal output from interactive
        commands.  The values of these variables may be specified as
@@ -705,20 +718,25 @@ color.ui::
        terminal. When more specific variables of color.* are set, they always
        take precedence over this setting. Defaults to false.
 
+commit.status
+       A boolean to enable/disable inclusion of status information in the
+       commit message template when using an editor to prepare the commit
+       message.  Defaults to true.
+
 commit.template::
        Specify a file to use as the template for new commit messages.
        "{tilde}/" is expanded to the value of `$HOME` and "{tilde}user/" to the
        specified user's home directory.
 
 diff.autorefreshindex::
-       When using 'git-diff' to compare with work tree
+       When using 'git diff' to compare with work tree
        files, do not consider stat-only change as changed.
        Instead, silently run `git update-index --refresh` to
        update the cached stat information for paths whose
        contents in the work tree match the contents in the
        index.  This option defaults to true.  Note that this
-       affects only 'git-diff' Porcelain, and not lower level
-       'diff' commands, such as 'git-diff-files'.
+       affects only 'git diff' Porcelain, and not lower level
+       'diff' commands such as 'git diff-files'.
 
 diff.external::
        If this config variable is set, diff generation is not
@@ -730,24 +748,24 @@ diff.external::
        your files, you might want to use linkgit:gitattributes[5] instead.
 
 diff.mnemonicprefix::
-       If set, 'git-diff' uses a prefix pair that is different from the
+       If set, 'git diff' uses a prefix pair that is different from the
        standard "a/" and "b/" depending on what is being compared.  When
        this configuration is in effect, reverse diff output also swaps
        the order of the prefixes:
-'git-diff';;
+`git diff`;;
        compares the (i)ndex and the (w)ork tree;
-'git-diff HEAD';;
+`git diff HEAD`;;
         compares a (c)ommit and the (w)ork tree;
-'git diff --cached';;
+`git diff --cached`;;
        compares a (c)ommit and the (i)ndex;
-'git-diff HEAD:file1 file2';;
+`git diff HEAD:file1 file2`;;
        compares an (o)bject and a (w)ork tree entity;
-'git diff --no-index a b';;
+`git diff --no-index a b`;;
        compares two non-git things (1) and (2).
 
 diff.renameLimit::
        The number of files to consider when performing the copy/rename
-       detection; equivalent to the 'git-diff' option '-l'.
+       detection; equivalent to the 'git diff' option '-l'.
 
 diff.renames::
        Tells git to detect renames.  If set to any boolean value, it
@@ -833,9 +851,9 @@ format.pretty::
        linkgit:git-whatchanged[1].
 
 format.thread::
-       The default threading style for 'git-format-patch'.  Can be
-       either a boolean value, `shallow` or `deep`.  `shallow`
-       threading makes every mail a reply to the head of the series,
+       The default threading style for 'git format-patch'.  Can be
+       a boolean value, or `shallow` or `deep`.  `shallow` threading
+       makes every mail a reply to the head of the series,
        where the head is chosen from the cover letter, the
        `\--in-reply-to`, and the first patch mail, in this order.
        `deep` threading makes every mail a reply to the previous one.
@@ -851,7 +869,7 @@ format.signoff::
 
 gc.aggressiveWindow::
        The window size parameter used in the delta compression
-       algorithm used by 'git-gc --aggressive'.  This defaults
+       algorithm used by 'git gc --aggressive'.  This defaults
        to 10.
 
 gc.auto::
@@ -868,39 +886,36 @@ gc.autopacklimit::
        default value is 50.  Setting this to 0 disables it.
 
 gc.packrefs::
-       'git-gc' does not run `git pack-refs` in a bare repository by
-       default so that older dumb-transport clients can still fetch
-       from the repository.  Setting this to `true` lets 'git-gc'
-       to run `git pack-refs`.  Setting this to `false` tells
-       'git-gc' never to run `git pack-refs`. The default setting is
-       `notbare`. Enable it only when you know you do not have to
-       support such clients.  The default setting will change to `true`
-       at some stage, and setting this to `false` will continue to
-       prevent `git pack-refs` from being run from 'git-gc'.
+       Running `git pack-refs` in a repository renders it
+       unclonable by Git versions prior to 1.5.1.2 over dumb
+       transports such as HTTP.  This variable determines whether
+       'git gc' runs `git pack-refs`. This can be set to `nobare`
+       to enable it within all non-bare repos or it can be set to a
+       boolean value.  The default is `true`.
 
 gc.pruneexpire::
-       When 'git-gc' is run, it will call 'prune --expire 2.weeks.ago'.
+       When 'git gc' is run, it will call 'prune --expire 2.weeks.ago'.
        Override the grace period with this config variable.  The value
        "now" may be used to disable this  grace period and always prune
        unreachable objects immediately.
 
 gc.reflogexpire::
-       'git-reflog expire' removes reflog entries older than
+       'git reflog expire' removes reflog entries older than
        this time; defaults to 90 days.
 
 gc.reflogexpireunreachable::
-       'git-reflog expire' removes reflog entries older than
+       'git reflog expire' removes reflog entries older than
        this time and are not reachable from the current tip;
        defaults to 30 days.
 
 gc.rerereresolved::
        Records of conflicted merge you resolved earlier are
-       kept for this many days when 'git-rerere gc' is run.
+       kept for this many days when 'git rerere gc' is run.
        The default is 60 days.  See linkgit:git-rerere[1].
 
 gc.rerereunresolved::
        Records of conflicted merge you have not resolved are
-       kept for this many days when 'git-rerere gc' is run.
+       kept for this many days when 'git rerere gc' is run.
        The default is 15 days.  See linkgit:git-rerere[1].
 
 gitcvs.commitmsgannotation::
@@ -1008,7 +1023,7 @@ gui.spellingdictionary::
        off.
 
 gui.fastcopyblame::
-       If true, 'git gui blame' uses '-C' instead of '-C -C' for original
+       If true, 'git gui blame' uses `-C` instead of `-C -C` for original
        location detection. It makes blame significantly faster on huge
        repositories at the expense of less thorough copy detection.
 
@@ -1132,6 +1147,12 @@ http.maxRequests::
        How many HTTP requests to launch in parallel. Can be overridden
        by the 'GIT_HTTP_MAX_REQUESTS' environment variable. Default is 5.
 
+http.minSessions::
+       The number of curl sessions (counted across slots) to be kept across
+       requests. They will not be ended with curl_easy_cleanup() until
+       http_cleanup() is invoked. If USE_CURL_MULTI is not defined, this
+       value will be capped at 1. Defaults to 1.
+
 http.postBuffer::
        Maximum size in bytes of the buffer used by smart HTTP
        transports when POSTing data to the remote system.
@@ -1161,7 +1182,7 @@ i18n.commitEncoding::
 
 i18n.logOutputEncoding::
        Character encoding the commit messages are converted to when
-       running 'git-log' and friends.
+       running 'git log' and friends.
 
 imap::
        The configuration variables in the 'imap' section are described
@@ -1195,7 +1216,7 @@ interactive.singlekey::
 
 log.date::
        Set default date-time mode for the log command. Setting log.date
-       value is similar to using 'git-log'\'s --date option. The value is one of the
+       value is similar to using 'git log'\'s --date option. The value is one of the
        following alternatives: {relative,local,default,iso,rfc,short}.
        See linkgit:git-log[1].
 
@@ -1267,6 +1288,53 @@ mergetool.keepTemporaries::
 mergetool.prompt::
        Prompt before each invocation of the merge resolution program.
 
+notes.displayRef::
+       The (fully qualified) refname from which to show notes when
+       showing commit messages.  The value of this variable can be set
+       to a glob, in which case notes from all matching refs will be
+       shown.  You may also specify this configuration variable
+       several times.  A warning will be issued for refs that do not
+       exist, but a glob that does not match any refs is silently
+       ignored.
++
+This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`
+environment variable, which must be a colon separated list of refs or
+globs.
++
+The effective value of "core.notesRef" (possibly overridden by
+GIT_NOTES_REF) is also implicitly added to the list of refs to be
+displayed.
+
+notes.rewrite.<command>::
+       When rewriting commits with <command> (currently `amend` or
+       `rebase`) and this variable is set to `true`, git
+       automatically copies your notes from the original to the
+       rewritten commit.  Defaults to `true`, but see
+       "notes.rewriteRef" below.
++
+This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
+environment variable, which must be a colon separated list of refs or
+globs.
+
+notes.rewriteMode::
+       When copying notes during a rewrite (see the
+       "notes.rewrite.<command>" option), determines what to do if
+       the target commit already has a note.  Must be one of
+       `overwrite`, `concatenate`, or `ignore`.  Defaults to
+       `concatenate`.
++
+This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
+environment variable.
+
+notes.rewriteRef::
+       When copying notes during a rewrite, specifies the (fully
+       qualified) ref whose notes should be copied.  The ref may be a
+       glob, in which case notes in all matching refs will be copied.
+       You may also specify this configuration several times.
++
+Does not have a default value; you must configure this variable to
+enable note rewriting.
+
 pack.window::
        The size of the window used by linkgit:git-pack-objects[1] when no
        window size is given on the command line. Defaults to 10.
@@ -1461,6 +1529,10 @@ remote.<name>.tagopt::
        Setting this value to \--no-tags disables automatic tag following when
        fetching from remote <name>
 
+remote.<name>.vcs::
+       Setting this to a value <vcs> will cause git to interact with
+       the remote with the git-remote-<vcs> helper.
+
 remotes.<group>::
        The list of remotes which are fetched by "git remote update
        <group>".  See linkgit:git-remote[1].