summaryrefslogtreecommitdiff
path: root/Documentation/config.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/config.txt')
-rw-r--r--Documentation/config.txt187
1 files changed, 150 insertions, 37 deletions
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 6af58ff3aa..2c031620c5 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -2,15 +2,15 @@ CONFIGURATION FILE
------------------
The git configuration file contains a number of variables that affect
-the git command's behavior. `.git/config` file for each repository
-is used to store the information for that repository, and
-`$HOME/.gitconfig` is used to store per user information to give
-fallback values for `.git/config` file. The file `/etc/gitconfig`
-can be used to store system-wide defaults.
-
-They can be used by both the git plumbing
-and the porcelains. The variables are divided into sections, where
-in the fully qualified variable name the variable itself is the last
+the git command's behavior. The `.git/config` file in each repository
+is used to store the configuration for that repository, and
+`$HOME/.gitconfig` is used to store a per-user configuration as
+fallback values for the `.git/config` file. The file `/etc/gitconfig`
+can be used to store a system-wide default configuration.
+
+The configuration variables are used by both the git plumbing
+and the porcelains. The variables are divided into sections, wherein
+the fully qualified variable name of the variable itself is the last
dot-separated segment and the section name is everything before the last
dot. The variable names are case-insensitive and only alphanumeric
characters are allowed. Some variables may appear multiple times.
@@ -25,35 +25,35 @@ blank lines are ignored.
The file consists of sections and variables. A section begins with
the name of the section in square brackets and continues until the next
section begins. Section names are not case sensitive. Only alphanumeric
-characters, '`-`' and '`.`' are allowed in section names. Each variable
-must belong to some section, which means that there must be section
-header before first setting of a variable.
+characters, `-` and `.` are allowed in section names. Each variable
+must belong to some section, which means that there must be a section
+header before the first setting of a variable.
Sections can be further divided into subsections. To begin a subsection
put its name in double quotes, separated by space from the section name,
-in the section header, like in example below:
+in the section header, like in the example below:
--------
[section "subsection"]
--------
-Subsection names can contain any characters except newline (doublequote
-'`"`' and backslash have to be escaped as '`\"`' and '`\\`',
-respectively) and are case sensitive. Section header cannot span multiple
+Subsection names are case sensitive and can contain any characters except
+newline (doublequote `"` and backslash have to be escaped as `\"` and `\\`,
+respectively). Section headers cannot span multiple
lines. Variables may belong directly to a section or to a given subsection.
You can have `[section]` if you have `[section "subsection"]`, but you
don't need to.
-There is also (case insensitive) alternative `[section.subsection]` syntax.
-In this syntax subsection names follow the same restrictions as for section
-name.
+There is also a case insensitive alternative `[section.subsection]` syntax.
+In this syntax, subsection names follow the same restrictions as for section
+names.
All the other lines are recognized as setting variables, in the form
'name = value'. If there is no equal sign on the line, the entire line
is taken as 'name' and the variable is recognized as boolean "true".
The variable names are case-insensitive and only alphanumeric
-characters and '`-`' are allowed. There can be more than one value
+characters and `-` are allowed. There can be more than one value
for a given variable; we say then that variable is multivalued.
Leading and trailing whitespace in a variable value is discarded.
@@ -61,26 +61,26 @@ 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 or true/false. Case is not significant in boolean values, when
+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".
String values may be entirely or partially enclosed in double quotes.
-You need to enclose variable value in double quotes if you want to
-preserve leading or trailing whitespace, or if variable value contains
-beginning of comment characters (if it contains '#' or ';').
-Double quote '`"`' and backslash '`\`' characters in variable value must
-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
+You need to enclose variable values in double quotes if you want to
+preserve leading or trailing whitespace, or if the variable value contains
+comment characters (i.e. it contains '#' or ';').
+Double quote `"` and backslash `\` characters in variable values must
+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.
-Variable value ending in a '`\`' is continued on the next line in the
+Variable values ending in a `\` are continued on the next line in the
customary UNIX fashion.
-Some variables may require special value format.
+Some variables may require a special value format.
Example
~~~~~~~
@@ -221,6 +221,11 @@ core.gitProxy::
Can be overridden by the 'GIT_PROXY_COMMAND' environment variable
(which always applies universally, without the special "for"
handling).
++
+The special string `none` can be used as the proxy command to
+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.ignoreStat::
If true, commands which modify both the working tree and the index
@@ -384,9 +389,9 @@ core.pager::
to override git's default settings this way, you need
to be explicit. For example, to disable the S option
in a backward compatible manner, set `core.pager`
- to "`less -+$LESS -FRX`". This will be passed to the
+ to `less -+$LESS -FRX`. This will be passed to the
shell by git, which will translate the final command to
- "`LESS=FRSX less -+FRSX -FRX`".
+ `LESS=FRSX less -+FRSX -FRX`.
core.whitespace::
A comma separated list of common whitespace problems to
@@ -424,6 +429,15 @@ relatively high IO latencies. With this set to 'true', git will do the
index comparison to the filesystem data in parallel, allowing
overlapping IO's.
+core.createObject::
+ You can set this to 'link', in which case a hardlink followed by
+ a delete of the source are used to make sure that object creation
+ will not overwrite existing objects.
++
+On some file system/operating system combinations, this is unreliable.
+Set this config setting to 'rename' there; However, This will remove the
+check that makes sure that existing object files will not get overwritten.
+
alias.*::
Command aliases for the linkgit:git[1] command wrapper - e.g.
after defining "alias.last = cat-file commit HEAD", the invocation
@@ -470,10 +484,14 @@ branch.autosetuprebase::
This option defaults to never.
branch.<name>.remote::
- When in branch <name>, it tells 'git-fetch' which remote to fetch.
- If this option is not given, 'git-fetch' defaults to remote "origin".
+ 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
refspec to be marked for merging in FETCH_HEAD. The value is
handled like the remote part of a refspec, and must match a
@@ -550,6 +568,25 @@ color.diff.<slot>::
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
+ the environment variables 'GREP_COLOR' and 'GREP_COLORS' when
+ calling an external 'grep'.
+
color.interactive::
When set to `always`, always use colors for interactive prompts
and displays (such as those used by "git-add --interactive").
@@ -567,6 +604,12 @@ color.pager::
A boolean to enable/disable colored output when the pager is in
use (default is true).
+color.showbranch::
+ A boolean to enable/disable color in the output of
+ linkgit:git-show-branch[1]. May be set to `always`,
+ `false` (or `never`) or `auto` (or `true`), in which case colors are used
+ only when the output is to a terminal. Defaults to false.
+
color.status::
A boolean to enable/disable color in the output of
linkgit:git-status[1]. May be set to `always`,
@@ -641,6 +684,27 @@ diff.suppressBlankEmpty::
A boolean to inhibit the standard behavior of printing a space
before each empty output line. Defaults to false.
+diff.tool::
+ Controls which diff tool is used. `diff.tool` overrides
+ `merge.tool` when used by linkgit:git-difftool[1] and has
+ the same valid values as `merge.tool` minus "tortoisemerge"
+ and plus "kompare".
+
+difftool.<tool>.path::
+ Override the path for the given tool. This is useful in case
+ your tool is not in the PATH.
+
+difftool.<tool>.cmd::
+ Specify the command to invoke the specified diff tool.
+ The specified command is evaluated in shell with the following
+ variables available: 'LOCAL' is set to the name of the temporary
+ file containing the contents of the diff pre-image and 'REMOTE'
+ is set to the name of the temporary file containing the contents
+ of the diff post-image.
+
+difftool.prompt::
+ Prompt before each invocation of the diff tool.
+
diff.wordRegex::
A POSIX Extended Regular Expression used to determine what is a "word"
when performing word-by-word difference calculations. Character
@@ -658,6 +722,13 @@ fetch.unpackLimit::
especially on slow filesystems. If not set, the value of
`transfer.unpackLimit` is used instead.
+format.attach::
+ Enable multipart/mixed attachments as the default for
+ 'format-patch'. The value can also be a double quoted string
+ which will enable attachments as the default and set the
+ value as the boundary. See the --attach option in
+ linkgit:git-format-patch[1].
+
format.numbered::
A boolean which can enable or disable sequence numbers in patch
subjects. It defaults to "auto" which enables it only if there
@@ -669,6 +740,14 @@ format.headers::
Additional email headers to include in a patch to be submitted
by mail. See linkgit:git-format-patch[1].
+format.cc::
+ Additional "Cc:" headers to include in a patch to be submitted
+ by mail. See the --cc option in linkgit:git-format-patch[1].
+
+format.subjectprefix::
+ The default for format-patch is to output files with the '[PATCH]'
+ subject prefix. Use this variable to change that prefix.
+
format.suffix::
The default for format-patch is to output files with the suffix
`.patch`. Use this variable to change that suffix (make sure to
@@ -679,6 +758,23 @@ format.pretty::
See linkgit:git-log[1], linkgit:git-show[1],
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,
+ 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.
+ A true boolean value is the same as `shallow`, and a false
+ value disables threading.
+
+format.signoff::
+ A boolean value which lets you enable the `-s/--signoff` option of
+ format-patch by default. *Note:* Adding the Signed-off-by: line to a
+ patch should be a conscious act and means that you certify you have
+ the rights to submit this work under the same open source license.
+ Please see the 'SubmittingPatches' document for further discussion.
+
gc.aggressiveWindow::
The window size parameter used in the delta compression
algorithm used by 'git-gc --aggressive'. This defaults
@@ -1153,7 +1249,7 @@ pager.<cmd>::
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`".
+ all commands, set `core.pager` or `GIT_PAGER` to `cat`.
pull.octopus::
The default merge strategy to use when pulling multiple branches
@@ -1162,6 +1258,23 @@ pull.octopus::
pull.twohead::
The default merge strategy to use when pulling a single branch.
+push.default::
+ Defines the action git push should take if no refspec is given
+ on the command line, no refspec is configured in the remote, and
+ no refspec is implied by any of the options given on the command
+ line. Possible values are:
++
+* `nothing` do not push anything.
+* `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.
+* `current` push the current branch to a branch of the same name.
+
+rebase.stat::
+ Whether to show a diffstat of what changed upstream since the last
+ rebase. False by default.
+
receive.fsckObjects::
If it is set to true, git-receive-pack will check all received
objects. It will abort in the case of a malformed object or a