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