bdccbf7047
356aea6 ("doc: move extensions.worktreeConfig to the right place",
2018-11-14) moved the explanation of extension.worktreeConfig from
config.txt to technical/repository-version.txt. However, the former
still contains a reference to the removed paragraph. We could fix it
referencing the gitrepository-layout man page, which contains the moved
explanation. But the git-worktree man page has additional information
and recommendations for the worktree config file, so let's reference it
instead.
Signed-off-by: Matheus Tavares <matheus.bernardino@usp.br>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
468 lines
14 KiB
Plaintext
468 lines
14 KiB
Plaintext
CONFIGURATION FILE
|
|
------------------
|
|
|
|
The Git configuration file contains a number of variables that affect
|
|
the Git commands' behavior. The files `.git/config` and optionally
|
|
`config.worktree` (see the "CONFIGURATION FILE" section of
|
|
linkgit:git-worktree[1]) in each repository are 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, allow only alphanumeric
|
|
characters and `-`, and must start with an alphabetic character. Some
|
|
variables may appear multiple times; we say then that the variable is
|
|
multivalued.
|
|
|
|
Syntax
|
|
~~~~~~
|
|
|
|
The syntax is fairly flexible and permissive; whitespaces are mostly
|
|
ignored. The '#' and ';' characters begin comments to the end of line,
|
|
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 case-insensitive. Only alphanumeric
|
|
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 the example below:
|
|
|
|
--------
|
|
[section "subsection"]
|
|
|
|
--------
|
|
|
|
Subsection names are case sensitive and can contain any characters except
|
|
newline and the null byte. Doublequote `"` and backslash can be included
|
|
by escaping them as `\"` and `\\`, respectively. Backslashes preceding
|
|
other characters are dropped when reading; for example, `\t` is read as
|
|
`t` and `\0` is read as `0` 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 a deprecated `[section.subsection]` syntax. With this
|
|
syntax, the subsection name is converted to lower-case and is also
|
|
compared case sensitively. These subsection names follow the same
|
|
restrictions as section names.
|
|
|
|
All the other lines (and the remainder of the line after the section
|
|
header) are recognized as setting variables, in the form
|
|
'name = value' (or just 'name', which is a short-hand to say that
|
|
the variable is the boolean "true").
|
|
The variable names are case-insensitive, allow only alphanumeric characters
|
|
and `-`, and must start with an alphabetic character.
|
|
|
|
A line that defines a value can be continued to the next line by
|
|
ending it with a `\`; the backquote and the end-of-line are
|
|
stripped. Leading whitespaces after 'name =', the remainder of the
|
|
line after the first comment character '#' or ';', and trailing
|
|
whitespaces of the line are discarded unless they are enclosed in
|
|
double quotes. Internal whitespaces within the value are retained
|
|
verbatim.
|
|
|
|
Inside double quotes, double quote `"` and backslash `\` characters
|
|
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). Other char escape sequences (including octal
|
|
escape sequences) are invalid.
|
|
|
|
|
|
Includes
|
|
~~~~~~~~
|
|
|
|
The `include` and `includeIf` sections allow you to include config
|
|
directives from another source. These sections behave identically to
|
|
each other with the exception that `includeIf` sections may be ignored
|
|
if their condition does not evaluate to true; see "Conditional includes"
|
|
below.
|
|
|
|
You can include a config file from another by setting the special
|
|
`include.path` (or `includeIf.*.path`) variable to the name of the file
|
|
to be included. The variable takes a pathname as its value, and is
|
|
subject to tilde expansion. These variables can be given multiple times.
|
|
|
|
The contents of the included file are inserted immediately, as if they
|
|
had been found at the location of the include directive. If the value of the
|
|
variable is a relative path, the path is considered to
|
|
be relative to the configuration file in which the include directive
|
|
was found. See below for examples.
|
|
|
|
Conditional includes
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
You can include a config file from another conditionally by setting a
|
|
`includeIf.<condition>.path` variable to the name of the file to be
|
|
included.
|
|
|
|
The condition starts with a keyword followed by a colon and some data
|
|
whose format and meaning depends on the keyword. Supported keywords
|
|
are:
|
|
|
|
`gitdir`::
|
|
|
|
The data that follows the keyword `gitdir:` is used as a glob
|
|
pattern. If the location of the .git directory matches the
|
|
pattern, the include condition is met.
|
|
+
|
|
The .git location may be auto-discovered, or come from `$GIT_DIR`
|
|
environment variable. If the repository is auto discovered via a .git
|
|
file (e.g. from submodules, or a linked worktree), the .git location
|
|
would be the final location where the .git directory is, not where the
|
|
.git file is.
|
|
+
|
|
The pattern can contain standard globbing wildcards and two additional
|
|
ones, `**/` and `/**`, that can match multiple path components. Please
|
|
refer to linkgit:gitignore[5] for details. For convenience:
|
|
|
|
* If the pattern starts with `~/`, `~` will be substituted with the
|
|
content of the environment variable `HOME`.
|
|
|
|
* If the pattern starts with `./`, it is replaced with the directory
|
|
containing the current config file.
|
|
|
|
* If the pattern does not start with either `~/`, `./` or `/`, `**/`
|
|
will be automatically prepended. For example, the pattern `foo/bar`
|
|
becomes `**/foo/bar` and would match `/any/path/to/foo/bar`.
|
|
|
|
* If the pattern ends with `/`, `**` will be automatically added. For
|
|
example, the pattern `foo/` becomes `foo/**`. In other words, it
|
|
matches "foo" and everything inside, recursively.
|
|
|
|
`gitdir/i`::
|
|
This is the same as `gitdir` except that matching is done
|
|
case-insensitively (e.g. on case-insensitive file systems)
|
|
|
|
`onbranch`::
|
|
The data that follows the keyword `onbranch:` is taken to be a
|
|
pattern with standard globbing wildcards and two additional
|
|
ones, `**/` and `/**`, that can match multiple path components.
|
|
If we are in a worktree where the name of the branch that is
|
|
currently checked out matches the pattern, the include condition
|
|
is met.
|
|
+
|
|
If the pattern ends with `/`, `**` will be automatically added. For
|
|
example, the pattern `foo/` becomes `foo/**`. In other words, it matches
|
|
all branches that begin with `foo/`. This is useful if your branches are
|
|
organized hierarchically and you would like to apply a configuration to
|
|
all the branches in that hierarchy.
|
|
|
|
A few more notes on matching via `gitdir` and `gitdir/i`:
|
|
|
|
* Symlinks in `$GIT_DIR` are not resolved before matching.
|
|
|
|
* Both the symlink & realpath versions of paths will be matched
|
|
outside of `$GIT_DIR`. E.g. if ~/git is a symlink to
|
|
/mnt/storage/git, both `gitdir:~/git` and `gitdir:/mnt/storage/git`
|
|
will match.
|
|
+
|
|
This was not the case in the initial release of this feature in
|
|
v2.13.0, which only matched the realpath version. Configuration that
|
|
wants to be compatible with the initial release of this feature needs
|
|
to either specify only the realpath version, or both versions.
|
|
|
|
* Note that "../" is not special and will match literally, which is
|
|
unlikely what you want.
|
|
|
|
Example
|
|
~~~~~~~
|
|
|
|
----
|
|
# Core variables
|
|
[core]
|
|
; Don't trust file modes
|
|
filemode = false
|
|
|
|
# Our diff algorithm
|
|
[diff]
|
|
external = /usr/local/bin/diff-wrapper
|
|
renames = true
|
|
|
|
[branch "devel"]
|
|
remote = origin
|
|
merge = refs/heads/devel
|
|
|
|
# Proxy settings
|
|
[core]
|
|
gitProxy="ssh" for "kernel.org"
|
|
gitProxy=default-proxy ; for the rest
|
|
|
|
[include]
|
|
path = /path/to/foo.inc ; include by absolute path
|
|
path = foo.inc ; find "foo.inc" relative to the current file
|
|
path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory
|
|
|
|
; include if $GIT_DIR is /path/to/foo/.git
|
|
[includeIf "gitdir:/path/to/foo/.git"]
|
|
path = /path/to/foo.inc
|
|
|
|
; include for all repositories inside /path/to/group
|
|
[includeIf "gitdir:/path/to/group/"]
|
|
path = /path/to/foo.inc
|
|
|
|
; include for all repositories inside $HOME/to/group
|
|
[includeIf "gitdir:~/to/group/"]
|
|
path = /path/to/foo.inc
|
|
|
|
; relative paths are always relative to the including
|
|
; file (if the condition is true); their location is not
|
|
; affected by the condition
|
|
[includeIf "gitdir:/path/to/group/"]
|
|
path = foo.inc
|
|
----
|
|
|
|
; include only if we are in a worktree where foo-branch is
|
|
; currently checked out
|
|
[includeIf "onbranch:foo-branch"]
|
|
path = foo.inc
|
|
|
|
Values
|
|
~~~~~~
|
|
|
|
Values of many variables are treated as a simple string, but there
|
|
are variables that take values of specific types and there are rules
|
|
as to how to spell them.
|
|
|
|
boolean::
|
|
|
|
When a variable is said to take a boolean value, many
|
|
synonyms are accepted for 'true' and 'false'; these are all
|
|
case-insensitive.
|
|
|
|
true;; Boolean true literals are `yes`, `on`, `true`,
|
|
and `1`. Also, a variable defined without `= <value>`
|
|
is taken as true.
|
|
|
|
false;; Boolean false literals are `no`, `off`, `false`,
|
|
`0` and the empty string.
|
|
+
|
|
When converting a value to its canonical form using the `--type=bool` type
|
|
specifier, 'git config' will ensure that the output is "true" or
|
|
"false" (spelled in lowercase).
|
|
|
|
integer::
|
|
The value for many variables that specify various sizes can
|
|
be suffixed with `k`, `M`,... to mean "scale the number by
|
|
1024", "by 1024x1024", etc.
|
|
|
|
color::
|
|
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. All the basic colors except
|
|
`normal` have a bright variant that can be speficied by prefixing the
|
|
color with `bright`, like `brightred`.
|
|
+
|
|
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).
|
|
+
|
|
An empty color string produces no color effect at all. This can be used
|
|
to avoid coloring specific elements without disabling color entirely.
|
|
+
|
|
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
|
|
string that begins with "`~/`" or "`~user/`", and the usual
|
|
tilde expansion happens to such a string: `~/`
|
|
is expanded to the value of `$HOME`, and `~user/` to the
|
|
specified user's home directory.
|
|
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
include::config/advice.txt[]
|
|
|
|
include::config/core.txt[]
|
|
|
|
include::config/add.txt[]
|
|
|
|
include::config/alias.txt[]
|
|
|
|
include::config/am.txt[]
|
|
|
|
include::config/apply.txt[]
|
|
|
|
include::config/blame.txt[]
|
|
|
|
include::config/branch.txt[]
|
|
|
|
include::config/browser.txt[]
|
|
|
|
include::config/checkout.txt[]
|
|
|
|
include::config/clean.txt[]
|
|
|
|
include::config/color.txt[]
|
|
|
|
include::config/column.txt[]
|
|
|
|
include::config/commit.txt[]
|
|
|
|
include::config/credential.txt[]
|
|
|
|
include::config/completion.txt[]
|
|
|
|
include::config/diff.txt[]
|
|
|
|
include::config/difftool.txt[]
|
|
|
|
include::config/fastimport.txt[]
|
|
|
|
include::config/feature.txt[]
|
|
|
|
include::config/fetch.txt[]
|
|
|
|
include::config/format.txt[]
|
|
|
|
include::config/filter.txt[]
|
|
|
|
include::config/fsck.txt[]
|
|
|
|
include::config/gc.txt[]
|
|
|
|
include::config/gitcvs.txt[]
|
|
|
|
include::config/gitweb.txt[]
|
|
|
|
include::config/grep.txt[]
|
|
|
|
include::config/gpg.txt[]
|
|
|
|
include::config/gui.txt[]
|
|
|
|
include::config/guitool.txt[]
|
|
|
|
include::config/help.txt[]
|
|
|
|
include::config/http.txt[]
|
|
|
|
include::config/i18n.txt[]
|
|
|
|
include::config/imap.txt[]
|
|
|
|
include::config/index.txt[]
|
|
|
|
include::config/init.txt[]
|
|
|
|
include::config/instaweb.txt[]
|
|
|
|
include::config/interactive.txt[]
|
|
|
|
include::config/log.txt[]
|
|
|
|
include::config/mailinfo.txt[]
|
|
|
|
include::config/mailmap.txt[]
|
|
|
|
include::config/man.txt[]
|
|
|
|
include::config/merge.txt[]
|
|
|
|
include::config/mergetool.txt[]
|
|
|
|
include::config/notes.txt[]
|
|
|
|
include::config/pack.txt[]
|
|
|
|
include::config/pager.txt[]
|
|
|
|
include::config/pretty.txt[]
|
|
|
|
include::config/protocol.txt[]
|
|
|
|
include::config/pull.txt[]
|
|
|
|
include::config/push.txt[]
|
|
|
|
include::config/rebase.txt[]
|
|
|
|
include::config/receive.txt[]
|
|
|
|
include::config/remote.txt[]
|
|
|
|
include::config/remotes.txt[]
|
|
|
|
include::config/repack.txt[]
|
|
|
|
include::config/rerere.txt[]
|
|
|
|
include::config/reset.txt[]
|
|
|
|
include::config/sendemail.txt[]
|
|
|
|
include::config/sequencer.txt[]
|
|
|
|
include::config/showbranch.txt[]
|
|
|
|
include::config/splitindex.txt[]
|
|
|
|
include::config/ssh.txt[]
|
|
|
|
include::config/status.txt[]
|
|
|
|
include::config/stash.txt[]
|
|
|
|
include::config/submodule.txt[]
|
|
|
|
include::config/tag.txt[]
|
|
|
|
include::config/trace2.txt[]
|
|
|
|
include::config/transfer.txt[]
|
|
|
|
include::config/uploadarchive.txt[]
|
|
|
|
include::config/uploadpack.txt[]
|
|
|
|
include::config/url.txt[]
|
|
|
|
include::config/user.txt[]
|
|
|
|
include::config/versionsort.txt[]
|
|
|
|
include::config/web.txt[]
|
|
|
|
include::config/worktree.txt[]
|