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 147A few more notes on matching via `gitdir` and `gitdir/i`: 148 149 * Symlinks in `$GIT_DIR` are not resolved before matching. 150 151 * Both the symlink & realpath versions of paths will be matched 152 outside of `$GIT_DIR`. E.g. if ~/git is a symlink to 153 /mnt/storage/git, both `gitdir:~/git` and `gitdir:/mnt/storage/git` 154 will match. 155+ 156This was not the case in the initial release of this feature in 157v2.13.0, which only matched the realpath version. Configuration that 158wants to be compatible with the initial release of this feature needs 159to either specify only the realpath version, or both versions. 160 161 * Note that "../" is not special and will match literally, which is 162 unlikely what you want. 163 164Example 165~~~~~~~ 166 167 # Core variables 168 [core] 169 ; Don't trust file modes 170 filemode = false 171 172 # Our diff algorithm 173 [diff] 174 external = /usr/local/bin/diff-wrapper 175 renames = true 176 177 [branch "devel"] 178 remote = origin 179 merge = refs/heads/devel 180 181 # Proxy settings 182 [core] 183 gitProxy="ssh" for "kernel.org" 184 gitProxy=default-proxy ; for the rest 185 186 [include] 187 path = /path/to/foo.inc ; include by absolute path 188 path = foo.inc ; find "foo.inc" relative to the current file 189 path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory 190 191 ; include if $GIT_DIR is /path/to/foo/.git 192 [includeIf "gitdir:/path/to/foo/.git"] 193 path = /path/to/foo.inc 194 195 ; include for all repositories inside /path/to/group 196 [includeIf "gitdir:/path/to/group/"] 197 path = /path/to/foo.inc 198 199 ; include for all repositories inside $HOME/to/group 200 [includeIf "gitdir:~/to/group/"] 201 path = /path/to/foo.inc 202 203 ; relative paths are always relative to the including 204 ; file (if the condition is true); their location is not 205 ; affected by the condition 206 [includeIf "gitdir:/path/to/group/"] 207 path = foo.inc 208 209Values 210~~~~~~ 211 212Values of many variables are treated as a simple string, but there 213are variables that take values of specific types and there are rules 214as to how to spell them. 215 216boolean:: 217 218 When a variable is said to take a boolean value, many 219 synonyms are accepted for 'true' and 'false'; these are all 220 case-insensitive. 221 222 true;; Boolean true literals are `yes`, `on`, `true`, 223 and `1`. Also, a variable defined without `= <value>` 224 is taken as true. 225 226 false;; Boolean false literals are `no`, `off`, `false`, 227 `0` and the empty string. 228+ 229When converting a value to its canonical form using the `--type=bool` type 230specifier, 'git config' will ensure that the output is "true" or 231"false" (spelled in lowercase). 232 233integer:: 234 The value for many variables that specify various sizes can 235 be suffixed with `k`, `M`,... to mean "scale the number by 236 1024", "by 1024x1024", etc. 237 238color:: 239 The value for a variable that takes a color is a list of 240 colors (at most two, one for foreground and one for background) 241 and attributes (as many as you want), separated by spaces. 242+ 243The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`, 244`blue`, `magenta`, `cyan` and `white`. The first color given is the 245foreground; the second is the background. 246+ 247Colors may also be given as numbers between 0 and 255; these use ANSI 248256-color mode (but note that not all terminals may support this). If 249your terminal supports it, you may also specify 24-bit RGB values as 250hex, like `#ff0ab3`. 251+ 252The accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`, 253`italic`, and `strike` (for crossed-out or "strikethrough" letters). 254The position of any attributes with respect to the colors 255(before, after, or in between), doesn't matter. Specific attributes may 256be turned off by prefixing them with `no` or `no-` (e.g., `noreverse`, 257`no-ul`, etc). 258+ 259An empty color string produces no color effect at all. This can be used 260to avoid coloring specific elements without disabling color entirely. 261+ 262For git's pre-defined color slots, the attributes are meant to be reset 263at the beginning of each item in the colored output. So setting 264`color.decorate.branch` to `black` will paint that branch name in a 265plain `black`, even if the previous thing on the same output line (e.g. 266opening parenthesis before the list of branch names in `log --decorate` 267output) is set to be painted with `bold` or some other attribute. 268However, custom log formats may do more complicated and layered 269coloring, and the negated forms may be useful there. 270 271pathname:: 272 A variable that takes a pathname value can be given a 273 string that begins with "`~/`" or "`~user/`", and the usual 274 tilde expansion happens to such a string: `~/` 275 is expanded to the value of `$HOME`, and `~user/` to the 276 specified user's home directory. 277 278 279Variables 280~~~~~~~~~ 281 282Note that this list is non-comprehensive and not necessarily complete. 283For command-specific variables, you will find a more detailed description 284in the appropriate manual page. 285 286Other git-related tools may and do use their own variables. When 287inventing new variables for use in your own tool, make sure their 288names do not conflict with those that are used by Git itself and 289other popular tools, and describe them in your documentation. 290 291include::config/advice.txt[] 292 293include::config/core.txt[] 294 295include::config/add.txt[] 296 297include::config/alias.txt[] 298 299include::config/am.txt[] 300 301include::config/apply.txt[] 302 303include::config/blame.txt[] 304 305include::config/branch.txt[] 306 307include::config/browser.txt[] 308 309include::config/checkout.txt[] 310 311include::config/clean.txt[] 312 313include::config/color.txt[] 314 315include::config/column.txt[] 316 317include::config/commit.txt[] 318 319include::config/credential.txt[] 320 321include::config/completion.txt[] 322 323include::config/diff.txt[] 324 325include::config/difftool.txt[] 326 327include::config/fastimport.txt[] 328 329include::config/fetch.txt[] 330 331include::config/format.txt[] 332 333include::config/filter.txt[] 334 335include::config/fsck.txt[] 336 337include::config/gc.txt[] 338 339include::config/gitcvs.txt[] 340 341include::config/gitweb.txt[] 342 343include::config/grep.txt[] 344 345include::config/gpg.txt[] 346 347include::config/gui.txt[] 348 349include::config/guitool.txt[] 350 351include::config/help.txt[] 352 353include::config/http.txt[] 354 355include::config/i18n.txt[] 356 357include::config/imap.txt[] 358 359include::config/index.txt[] 360 361include::config/init.txt[] 362 363include::config/instaweb.txt[] 364 365include::config/interactive.txt[] 366 367include::config/log.txt[] 368 369include::config/mailinfo.txt[] 370 371include::config/mailmap.txt[] 372 373include::config/man.txt[] 374 375include::config/merge.txt[] 376 377include::config/mergetool.txt[] 378 379include::config/notes.txt[] 380 381include::config/pack.txt[] 382 383include::config/pager.txt[] 384 385include::config/pretty.txt[] 386 387include::config/protocol.txt[] 388 389include::config/pull.txt[] 390 391include::config/push.txt[] 392 393include::config/rebase.txt[] 394 395include::config/receive.txt[] 396 397include::config/remote.txt[] 398 399include::config/remotes.txt[] 400 401include::config/repack.txt[] 402 403include::config/rerere.txt[] 404 405include::config/reset.txt[] 406 407include::config/sendemail.txt[] 408 409include::config/sequencer.txt[] 410 411include::config/showbranch.txt[] 412 413include::config/splitindex.txt[] 414 415include::config/ssh.txt[] 416 417include::config/status.txt[] 418 419include::config/stash.txt[] 420 421include::config/submodule.txt[] 422 423include::config/tag.txt[] 424 425include::config/trace2.txt[] 426 427include::config/transfer.txt[] 428 429include::config/uploadarchive.txt[] 430 431include::config/uploadpack.txt[] 432 433include::config/url.txt[] 434 435include::config/user.txt[] 436 437include::config/versionsort.txt[] 438 439include::config/web.txt[] 440 441include::config/worktree.txt[]