1CONFIGURATION FILE 2------------------ 3 4The Git configuration file contains a number of variables that affect 5the Git commands' behavior. The files `.git/config` and optionally 6`config.worktree` (see `extensions.worktreeConfig` below) in each 7repository are used to store the configuration for that repository, and 8`$HOME/.gitconfig` is used to store a per-user configuration as 9fallback values for the `.git/config` file. The file `/etc/gitconfig` 10can be used to store a system-wide default configuration. 11 12The configuration variables are used by both the Git plumbing 13and the porcelains. The variables are divided into sections, wherein 14the fully qualified variable name of the variable itself is the last 15dot-separated segment and the section name is everything before the last 16dot. The variable names are case-insensitive, allow only alphanumeric 17characters and `-`, and must start with an alphabetic character. Some 18variables may appear multiple times; we say then that the variable is 19multivalued. 20 21Syntax 22~~~~~~ 23 24The syntax is fairly flexible and permissive; whitespaces are mostly 25ignored. The '#' and ';' characters begin comments to the end of line, 26blank lines are ignored. 27 28The file consists of sections and variables. A section begins with 29the name of the section in square brackets and continues until the next 30section begins. Section names are case-insensitive. Only alphanumeric 31characters, `-` and `.` are allowed in section names. Each variable 32must belong to some section, which means that there must be a section 33header before the first setting of a variable. 34 35Sections can be further divided into subsections. To begin a subsection 36put its name in double quotes, separated by space from the section name, 37in the section header, like in the example below: 38 39-------- 40 [section "subsection"] 41 42-------- 43 44Subsection names are case sensitive and can contain any characters except 45newline and the null byte. Doublequote `"` and backslash can be included 46by escaping them as `\"` and `\\`, respectively. Backslashes preceding 47other characters are dropped when reading; for example, `\t` is read as 48`t` and `\0` is read as `0` Section headers cannot span multiple lines. 49Variables may belong directly to a section or to a given subsection. You 50can have `[section]` if you have `[section "subsection"]`, but you don't 51need to. 52 53There is also a deprecated `[section.subsection]` syntax. With this 54syntax, the subsection name is converted to lower-case and is also 55compared case sensitively. These subsection names follow the same 56restrictions as section names. 57 58All the other lines (and the remainder of the line after the section 59header) are recognized as setting variables, in the form 60'name = value' (or just 'name', which is a short-hand to say that 61the variable is the boolean "true"). 62The variable names are case-insensitive, allow only alphanumeric characters 63and `-`, and must start with an alphabetic character. 64 65A line that defines a value can be continued to the next line by 66ending it with a `\`; the backquote and the end-of-line are 67stripped. Leading whitespaces after 'name =', the remainder of the 68line after the first comment character '#' or ';', and trailing 69whitespaces of the line are discarded unless they are enclosed in 70double quotes. Internal whitespaces within the value are retained 71verbatim. 72 73Inside double quotes, double quote `"` and backslash `\` characters 74must be escaped: use `\"` for `"` and `\\` for `\`. 75 76The following escape sequences (beside `\"` and `\\`) are recognized: 77`\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB) 78and `\b` for backspace (BS). Other char escape sequences (including octal 79escape sequences) are invalid. 80 81 82Includes 83~~~~~~~~ 84 85The `include` and `includeIf` sections allow you to include config 86directives from another source. These sections behave identically to 87each other with the exception that `includeIf` sections may be ignored 88if their condition does not evaluate to true; see "Conditional includes" 89below. 90 91You can include a config file from another by setting the special 92`include.path` (or `includeIf.*.path`) variable to the name of the file 93to be included. The variable takes a pathname as its value, and is 94subject to tilde expansion. These variables can be given multiple times. 95 96The contents of the included file are inserted immediately, as if they 97had been found at the location of the include directive. If the value of the 98variable is a relative path, the path is considered to 99be relative to the configuration file in which the include directive 100was found. See below for examples. 101 102Conditional includes 103~~~~~~~~~~~~~~~~~~~~ 104 105You can include a config file from another conditionally by setting a 106`includeIf.<condition>.path` variable to the name of the file to be 107included. 108 109The condition starts with a keyword followed by a colon and some data 110whose format and meaning depends on the keyword. Supported keywords 111are: 112 113`gitdir`:: 114 115 The data that follows the keyword `gitdir:` is used as a glob 116 pattern. If the location of the .git directory matches the 117 pattern, the include condition is met. 118+ 119The .git location may be auto-discovered, or come from `$GIT_DIR` 120environment variable. If the repository is auto discovered via a .git 121file (e.g. from submodules, or a linked worktree), the .git location 122would be the final location where the .git directory is, not where the 123.git file is. 124+ 125The pattern can contain standard globbing wildcards and two additional 126ones, `**/` and `/**`, that can match multiple path components. Please 127refer to linkgit:gitignore[5] for details. For convenience: 128 129 * If the pattern starts with `~/`, `~` will be substituted with the 130 content of the environment variable `HOME`. 131 132 * If the pattern starts with `./`, it is replaced with the directory 133 containing the current config file. 134 135 * If the pattern does not start with either `~/`, `./` or `/`, `**/` 136 will be automatically prepended. For example, the pattern `foo/bar` 137 becomes `**/foo/bar` and would match `/any/path/to/foo/bar`. 138 139 * If the pattern ends with `/`, `**` will be automatically added. For 140 example, the pattern `foo/` becomes `foo/**`. In other words, it 141 matches "foo" and everything inside, recursively. 142 143`gitdir/i`:: 144 This is the same as `gitdir` except that matching is done 145 case-insensitively (e.g. on case-insensitive file sytems) 146 147`onbranch`:: 148 The data that follows the keyword `onbranch:` is taken to be a 149 pattern with standard globbing wildcards and two additional 150 ones, `**/` and `/**`, that can match multiple path components. 151 If we are in a worktree where the name of the branch that is 152 currently checked out matches the pattern, the include condition 153 is met. 154+ 155If the pattern ends with `/`, `**` will be automatically added. For 156example, the pattern `foo/` becomes `foo/**`. In other words, it matches 157all branches that begin with `foo/`. This is useful if your branches are 158organized hierarchically and you would like to apply a configuration to 159all the branches in that hierarchy. 160 161A few more notes on matching via `gitdir` and `gitdir/i`: 162 163 * Symlinks in `$GIT_DIR` are not resolved before matching. 164 165 * Both the symlink & realpath versions of paths will be matched 166 outside of `$GIT_DIR`. E.g. if ~/git is a symlink to 167 /mnt/storage/git, both `gitdir:~/git` and `gitdir:/mnt/storage/git` 168 will match. 169+ 170This was not the case in the initial release of this feature in 171v2.13.0, which only matched the realpath version. Configuration that 172wants to be compatible with the initial release of this feature needs 173to either specify only the realpath version, or both versions. 174 175 * Note that "../" is not special and will match literally, which is 176 unlikely what you want. 177 178Example 179~~~~~~~ 180 181 # Core variables 182 [core] 183 ; Don't trust file modes 184 filemode = false 185 186 # Our diff algorithm 187 [diff] 188 external = /usr/local/bin/diff-wrapper 189 renames = true 190 191 [branch "devel"] 192 remote = origin 193 merge = refs/heads/devel 194 195 # Proxy settings 196 [core] 197 gitProxy="ssh" for "kernel.org" 198 gitProxy=default-proxy ; for the rest 199 200 [include] 201 path = /path/to/foo.inc ; include by absolute path 202 path = foo.inc ; find "foo.inc" relative to the current file 203 path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory 204 205 ; include if $GIT_DIR is /path/to/foo/.git 206 [includeIf "gitdir:/path/to/foo/.git"] 207 path = /path/to/foo.inc 208 209 ; include for all repositories inside /path/to/group 210 [includeIf "gitdir:/path/to/group/"] 211 path = /path/to/foo.inc 212 213 ; include for all repositories inside $HOME/to/group 214 [includeIf "gitdir:~/to/group/"] 215 path = /path/to/foo.inc 216 217 ; relative paths are always relative to the including 218 ; file (if the condition is true); their location is not 219 ; affected by the condition 220 [includeIf "gitdir:/path/to/group/"] 221 path = foo.inc 222 223 ; include only if we are in a worktree where foo-branch is 224 ; currently checked out 225 [includeIf "onbranch:foo-branch"] 226 path = foo.inc 227 228Values 229~~~~~~ 230 231Values of many variables are treated as a simple string, but there 232are variables that take values of specific types and there are rules 233as to how to spell them. 234 235boolean:: 236 237 When a variable is said to take a boolean value, many 238 synonyms are accepted for 'true' and 'false'; these are all 239 case-insensitive. 240 241 true;; Boolean true literals are `yes`, `on`, `true`, 242 and `1`. Also, a variable defined without `= <value>` 243 is taken as true. 244 245 false;; Boolean false literals are `no`, `off`, `false`, 246 `0` and the empty string. 247+ 248When converting a value to its canonical form using the `--type=bool` type 249specifier, 'git config' will ensure that the output is "true" or 250"false" (spelled in lowercase). 251 252integer:: 253 The value for many variables that specify various sizes can 254 be suffixed with `k`, `M`,... to mean "scale the number by 255 1024", "by 1024x1024", etc. 256 257color:: 258 The value for a variable that takes a color is a list of 259 colors (at most two, one for foreground and one for background) 260 and attributes (as many as you want), separated by spaces. 261+ 262The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`, 263`blue`, `magenta`, `cyan` and `white`. The first color given is the 264foreground; the second is the background. 265+ 266Colors may also be given as numbers between 0 and 255; these use ANSI 267256-color mode (but note that not all terminals may support this). If 268your terminal supports it, you may also specify 24-bit RGB values as 269hex, like `#ff0ab3`. 270+ 271The accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`, 272`italic`, and `strike` (for crossed-out or "strikethrough" letters). 273The position of any attributes with respect to the colors 274(before, after, or in between), doesn't matter. Specific attributes may 275be turned off by prefixing them with `no` or `no-` (e.g., `noreverse`, 276`no-ul`, etc). 277+ 278An empty color string produces no color effect at all. This can be used 279to avoid coloring specific elements without disabling color entirely. 280+ 281For git's pre-defined color slots, the attributes are meant to be reset 282at the beginning of each item in the colored output. So setting 283`color.decorate.branch` to `black` will paint that branch name in a 284plain `black`, even if the previous thing on the same output line (e.g. 285opening parenthesis before the list of branch names in `log --decorate` 286output) is set to be painted with `bold` or some other attribute. 287However, custom log formats may do more complicated and layered 288coloring, and the negated forms may be useful there. 289 290pathname:: 291 A variable that takes a pathname value can be given a 292 string that begins with "`~/`" or "`~user/`", and the usual 293 tilde expansion happens to such a string: `~/` 294 is expanded to the value of `$HOME`, and `~user/` to the 295 specified user's home directory. 296 297 298Variables 299~~~~~~~~~ 300 301Note that this list is non-comprehensive and not necessarily complete. 302For command-specific variables, you will find a more detailed description 303in the appropriate manual page. 304 305Other git-related tools may and do use their own variables. When 306inventing new variables for use in your own tool, make sure their 307names do not conflict with those that are used by Git itself and 308other popular tools, and describe them in your documentation. 309 310include::config/advice.txt[] 311 312include::config/core.txt[] 313 314include::config/add.txt[] 315 316include::config/alias.txt[] 317 318include::config/am.txt[] 319 320include::config/apply.txt[] 321 322include::config/blame.txt[] 323 324include::config/branch.txt[] 325 326include::config/browser.txt[] 327 328include::config/checkout.txt[] 329 330include::config/clean.txt[] 331 332include::config/color.txt[] 333 334include::config/column.txt[] 335 336include::config/commit.txt[] 337 338include::config/credential.txt[] 339 340include::config/completion.txt[] 341 342include::config/diff.txt[] 343 344include::config/difftool.txt[] 345 346include::config/fastimport.txt[] 347 348include::config/fetch.txt[] 349 350include::config/format.txt[] 351 352include::config/filter.txt[] 353 354include::config/fsck.txt[] 355 356include::config/gc.txt[] 357 358include::config/gitcvs.txt[] 359 360include::config/gitweb.txt[] 361 362include::config/grep.txt[] 363 364include::config/gpg.txt[] 365 366include::config/gui.txt[] 367 368include::config/guitool.txt[] 369 370include::config/help.txt[] 371 372include::config/http.txt[] 373 374include::config/i18n.txt[] 375 376include::config/imap.txt[] 377 378include::config/index.txt[] 379 380include::config/init.txt[] 381 382include::config/instaweb.txt[] 383 384include::config/interactive.txt[] 385 386include::config/log.txt[] 387 388include::config/mailinfo.txt[] 389 390include::config/mailmap.txt[] 391 392include::config/man.txt[] 393 394include::config/merge.txt[] 395 396include::config/mergetool.txt[] 397 398include::config/notes.txt[] 399 400include::config/pack.txt[] 401 402include::config/pager.txt[] 403 404include::config/pretty.txt[] 405 406include::config/protocol.txt[] 407 408include::config/pull.txt[] 409 410include::config/push.txt[] 411 412include::config/rebase.txt[] 413 414include::config/receive.txt[] 415 416include::config/remote.txt[] 417 418include::config/remotes.txt[] 419 420include::config/repack.txt[] 421 422include::config/rerere.txt[] 423 424include::config/reset.txt[] 425 426include::config/sendemail.txt[] 427 428include::config/sequencer.txt[] 429 430include::config/showbranch.txt[] 431 432include::config/splitindex.txt[] 433 434include::config/ssh.txt[] 435 436include::config/status.txt[] 437 438include::config/stash.txt[] 439 440include::config/submodule.txt[] 441 442include::config/tag.txt[] 443 444include::config/trace2.txt[] 445 446include::config/transfer.txt[] 447 448include::config/uploadarchive.txt[] 449 450include::config/uploadpack.txt[] 451 452include::config/url.txt[] 453 454include::config/user.txt[] 455 456include::config/versionsort.txt[] 457 458include::config/web.txt[] 459 460include::config/worktree.txt[]