trace2: document the supported values of GIT_TRACE2* env variables
[git/git.git] / Documentation / git.txt
CommitLineData
9e1f0a85 1git(1)
2cf565c5 2======
2cf565c5
DG
3
4NAME
5----
6git - the stupid content tracker
7
8
9SYNOPSIS
10--------
8b70004b 11[verse]
44e1e4d6 12'git' [--version] [--help] [-C <path>] [-c <name>=<value>]
68e4b552 13 [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
7213c288 14 [-p|--paginate|-P|--no-pager] [--no-replace-objects] [--bare]
d49483f0 15 [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
74866d75 16 [--super-prefix=<path>]
68e4b552 17 <command> [<args>]
2cf565c5
DG
18
19DESCRIPTION
20-----------
23091e95
BF
21Git is a fast, scalable, distributed revision control system with an
22unusually rich command set that provides both high-level operations
23and full access to internals.
24
6998e4db 25See linkgit:gittutorial[7] to get started, then see
673151a9 26linkgit:giteveryday[7] for a useful minimum set of
7687ae98
JH
27commands. The link:user-manual.html[Git User's Manual] has a more
28in-depth introduction.
cb22bc44 29
7687ae98 30After you mastered the basic concepts, you can come back to this
2de9b711
TA
31page to learn what commands Git offers. You can learn more about
32individual Git commands with "git help command". linkgit:gitcli[7]
06ab60c0 33manual page gives you an overview of the command-line command syntax.
4514ad4f 34
f7935827
JN
35A formatted and hyperlinked copy of the latest Git documentation
36can be viewed at `https://git.github.io/htmldocs/git.html`.
34b604af 37
26cfcfbf 38
cb22bc44
AE
39OPTIONS
40-------
41--version::
2de9b711 42 Prints the Git suite version that the 'git' program came from.
cb22bc44
AE
43
44--help::
a87cd02c 45 Prints the synopsis and a list of the most commonly used
bcf9626a 46 commands. If the option `--all` or `-a` is given then all
2de9b711 47 available commands are printed. If a Git command is named this
0f6f195b 48 option will bring up the manual page for that command.
45533d26
CC
49+
50Other options are available to control how the manual page is
5162e697 51displayed. See linkgit:git-help[1] for more information,
db5d6666
JN
52because `git --help ...` is converted internally into `git
53help ...`.
cb22bc44 54
44e1e4d6
NR
55-C <path>::
56 Run as if git was started in '<path>' instead of the current working
57 directory. When multiple `-C` options are given, each subsequent
58 non-absolute `-C <path>` is interpreted relative to the preceding `-C
59 <path>`.
60+
61This option affects options that expect path name like `--git-dir` and
62`--work-tree` in that their interpretations of the path names would be
63made relative to the working directory caused by the `-C` option. For
64example the following invocations are equivalent:
65
66 git --git-dir=a.git --work-tree=b -C c status
67 git --git-dir=c/a.git --work-tree=c/b status
68
8b1fa778
AR
69-c <name>=<value>::
70 Pass a configuration parameter to the command. The value
71 given will override values from configuration files.
72 The <name> is expected in the same format as listed by
73 'git config' (subkeys separated by dots).
a789ca70
JH
74+
75Note that omitting the `=` in `git -c foo.bar ...` is allowed and sets
76`foo.bar` to the boolean true value (just like `[foo]bar` would in a
77config file). Including the equals but with an empty value (like `git -c
5e633326 78foo.bar= ...`) sets `foo.bar` to the empty string which `git config
ed3bb3df 79--type=bool` will convert to `false`.
8b1fa778 80
62b4698e 81--exec-path[=<path>]::
2de9b711 82 Path to wherever your core Git programs are installed.
cb22bc44 83 This can also be controlled by setting the GIT_EXEC_PATH
56992f76 84 environment variable. If no path is given, 'git' will print
cb22bc44
AE
85 the current setting and then exit.
86
89a56bfb 87--html-path::
2de9b711 88 Print the path, without trailing slash, where Git's HTML
239b5ed9 89 documentation is installed and exit.
89a56bfb 90
f2dd8c37 91--man-path::
239b5ed9 92 Print the manpath (see `man(1)`) for the man pages for
2de9b711 93 this version of Git and exit.
f2dd8c37
JS
94
95--info-path::
239b5ed9 96 Print the path where the Info files documenting this
2de9b711 97 version of Git are installed and exit.
89a56bfb 98
3240240f
SB
99-p::
100--paginate::
06300d97
JN
101 Pipe all output into 'less' (or if set, $PAGER) if standard
102 output is a terminal. This overrides the `pager.<cmd>`
103 configuration options (see the "Configuration Mechanism" section
104 below).
6acbcb92 105
7213c288 106-P::
463a849d 107--no-pager::
2de9b711 108 Do not pipe Git output into a pager.
463a849d 109
6acbcb92
JS
110--git-dir=<path>::
111 Set the path to the repository. This can also be controlled by
47d81b5c 112 setting the `GIT_DIR` environment variable. It can be an absolute
302cc11a 113 path or relative path to current working directory.
6acbcb92 114
892c41b9 115--work-tree=<path>::
ea472c1e
JH
116 Set the path to the working tree. It can be an absolute path
117 or a path relative to the current working directory.
892c41b9
ML
118 This can also be controlled by setting the GIT_WORK_TREE
119 environment variable and the core.worktree configuration
ea472c1e
JH
120 variable (see core.worktree in linkgit:git-config[1] for a
121 more detailed discussion).
892c41b9 122
d49483f0 123--namespace=<path>::
2de9b711 124 Set the Git namespace. See linkgit:gitnamespaces[7] for more
d49483f0
JT
125 details. Equivalent to setting the `GIT_NAMESPACE` environment
126 variable.
127
74866d75
BW
128--super-prefix=<path>::
129 Currently for internal use only. Set a prefix which gives a path from
130 above a repository down to its root. One use is to give submodules
131 context about the superproject that invoked it.
132
6acbcb92 133--bare::
9277d602
JH
134 Treat the repository as a bare repository. If GIT_DIR
135 environment is not set, it is set to the current working
136 directory.
137
b0fa7ab5 138--no-replace-objects::
2de9b711 139 Do not use replacement refs to replace Git objects. See
b0fa7ab5
CC
140 linkgit:git-replace[1] for more information.
141
823ab40f 142--literal-pathspecs::
a16bf9dd
NTND
143 Treat pathspecs literally (i.e. no globbing, no pathspec magic).
144 This is equivalent to setting the `GIT_LITERAL_PATHSPECS` environment
823ab40f
JK
145 variable to `1`.
146
6fb02165 147--glob-pathspecs::
bd30c2e4
NTND
148 Add "glob" magic to all pathspec. This is equivalent to setting
149 the `GIT_GLOB_PATHSPECS` environment variable to `1`. Disabling
150 globbing on individual pathspecs can be done using pathspec
151 magic ":(literal)"
152
6fb02165 153--noglob-pathspecs::
bd30c2e4
NTND
154 Add "literal" magic to all pathspec. This is equivalent to setting
155 the `GIT_NOGLOB_PATHSPECS` environment variable to `1`. Enabling
156 globbing on individual pathspecs can be done using pathspec
157 magic ":(glob)"
9755afbd 158
6fb02165 159--icase-pathspecs::
93d93537
NTND
160 Add "icase" magic to all pathspec. This is equivalent to setting
161 the `GIT_ICASE_PATHSPECS` environment variable to `1`.
9755afbd 162
27344d6a
JK
163--no-optional-locks::
164 Do not perform optional operations that require locks. This is
165 equivalent to setting the `GIT_OPTIONAL_LOCKS` to `0`.
166
0089521c
NTND
167--list-cmds=group[,group...]::
168 List commands by group. This is an internal/experimental
169 option and may change or be removed in the future. Supported
170 groups are: builtins, parseopt (builtin commands that use
6bb2dc0b 171 parse-options), main (all commands in libexec directory),
3c777767 172 others (all other commands in `$PATH` that have git- prefix),
e11dca10 173 list-<category> (see categories in command-list.txt),
6532f374
NTND
174 nohelpers (exclude helper commands), alias and config
175 (retrieve command list from config variable completion.commands)
0089521c 176
23091e95
BF
177GIT COMMANDS
178------------
9755afbd 179
2de9b711 180We divide Git into high level ("porcelain") commands and low level
23091e95 181("plumbing") commands.
8b15e2fb 182
23091e95
BF
183High-level commands (porcelain)
184-------------------------------
185
186We separate the porcelain commands into the main commands and some
187ancillary user utilities.
188
189Main porcelain commands
190~~~~~~~~~~~~~~~~~~~~~~~
905197de 191
377e8139 192include::cmds-mainporcelain.txt[]
e31bb3bb 193
90933efb 194Ancillary Commands
23091e95 195~~~~~~~~~~~~~~~~~~
2f2de9b4
JH
196Manipulators:
197
377e8139 198include::cmds-ancillarymanipulators.txt[]
204ee6a9 199
90933efb 200Interrogators:
204ee6a9 201
377e8139 202include::cmds-ancillaryinterrogators.txt[]
7fc9d69f 203
89bf2077
JH
204
205Interacting with Others
206~~~~~~~~~~~~~~~~~~~~~~~
207
208These commands are to interact with foreign SCM and with other
209people via patch over e-mail.
210
211include::cmds-foreignscminterface.txt[]
212
213
b1f33d62
RR
214Low-level commands (plumbing)
215-----------------------------
216
2de9b711 217Although Git includes its
b1f33d62
RR
218own porcelain layer, its low-level commands are sufficient to support
219development of alternative porcelains. Developers of such porcelains
5162e697
DM
220might start by reading about linkgit:git-update-index[1] and
221linkgit:git-read-tree[1].
b1f33d62 222
89bf2077
JH
223The interface (input, output, set of options and the semantics)
224to these low-level commands are meant to be a lot more stable
225than Porcelain level commands, because these commands are
226primarily for scripted use. The interface to Porcelain commands
227on the other hand are subject to change in order to improve the
228end user experience.
229
230The following description divides
231the low-level commands into commands that manipulate objects (in
b1f33d62
RR
232the repository, index, and working tree), commands that interrogate and
233compare objects, and commands that move objects and references between
234repositories.
235
89bf2077 236
b1f33d62
RR
237Manipulation commands
238~~~~~~~~~~~~~~~~~~~~~
b1f33d62 239
377e8139 240include::cmds-plumbingmanipulators.txt[]
b1f33d62
RR
241
242
243Interrogation commands
244~~~~~~~~~~~~~~~~~~~~~~
245
377e8139 246include::cmds-plumbinginterrogators.txt[]
b1f33d62
RR
247
248In general, the interrogate commands do not touch the files in
249the working tree.
250
251
252Synching repositories
253~~~~~~~~~~~~~~~~~~~~~
254
377e8139 255include::cmds-synchingrepositories.txt[]
b1f33d62 256
57f6ec02 257The following are helper commands used by the above; end users
89bf2077
JH
258typically do not use them directly.
259
260include::cmds-synchelpers.txt[]
261
262
263Internal helper commands
264~~~~~~~~~~~~~~~~~~~~~~~~
265
266These are internal helper commands used by other commands; end
267users typically do not use them directly.
268
269include::cmds-purehelpers.txt[]
270
b1f33d62 271
5773c9f2
JH
272Configuration Mechanism
273-----------------------
274
c0179c0d
MM
275Git uses a simple text format to store customizations that are per
276repository and are per user. Such a configuration file may look
277like this:
5773c9f2
JH
278
279------------
280#
2fa090b6 281# A '#' or ';' character indicates a comment.
5773c9f2
JH
282#
283
284; core variables
285[core]
286 ; Don't trust file modes
287 filemode = false
288
289; user identity
290[user]
291 name = "Junio C Hamano"
c0179c0d 292 email = "gitster@pobox.com"
5773c9f2
JH
293
294------------
295
296Various commands read from the configuration file and adjust
06300d97 297their operation accordingly. See linkgit:git-config[1] for a
c0179c0d 298list and more details about the configuration mechanism.
5773c9f2
JH
299
300
6c84e2e0 301Identifier Terminology
2cf565c5
DG
302----------------------
303<object>::
2fa090b6 304 Indicates the object name for any type of object.
2cf565c5
DG
305
306<blob>::
2fa090b6 307 Indicates a blob object name.
2cf565c5
DG
308
309<tree>::
2fa090b6 310 Indicates a tree object name.
2cf565c5
DG
311
312<commit>::
2fa090b6 313 Indicates a commit object name.
2cf565c5
DG
314
315<tree-ish>::
2fa090b6 316 Indicates a tree, commit or tag object name. A
6c84e2e0
DG
317 command that takes a <tree-ish> argument ultimately wants to
318 operate on a <tree> object but automatically dereferences
319 <commit> and <tag> objects that point at a <tree>.
2cf565c5 320
043d7605
TT
321<commit-ish>::
322 Indicates a commit or tag object name. A
323 command that takes a <commit-ish> argument ultimately wants to
324 operate on a <commit> object but automatically dereferences
325 <tag> objects that point at a <commit>.
326
2cf565c5
DG
327<type>::
328 Indicates that an object type is required.
2fa090b6 329 Currently one of: `blob`, `tree`, `commit`, or `tag`.
2cf565c5
DG
330
331<file>::
2fa090b6
JH
332 Indicates a filename - almost always relative to the
333 root of the tree structure `GIT_INDEX_FILE` describes.
2cf565c5 334
c1bdacf9
DG
335Symbolic Identifiers
336--------------------
2de9b711 337Any Git command accepting any <object> can also use the following
6c84e2e0 338symbolic notation:
c1bdacf9
DG
339
340HEAD::
0abcfbff 341 indicates the head of the current branch.
2fa090b6 342
c1bdacf9 343<tag>::
2fa090b6 344 a valid tag 'name'
0abcfbff 345 (i.e. a `refs/tags/<tag>` reference).
2fa090b6 346
c1bdacf9 347<head>::
2fa090b6 348 a valid head 'name'
0abcfbff 349 (i.e. a `refs/heads/<head>` reference).
2fa090b6 350
d47107d8 351For a more complete list of ways to spell object names, see
9d83e382 352"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
d47107d8 353
c1bdacf9
DG
354
355File/Directory Structure
356------------------------
c1bdacf9 357
6998e4db 358Please see the linkgit:gitrepository-layout[5] document.
c1bdacf9 359
6998e4db 360Read linkgit:githooks[5] for more details about each hook.
6250ad1e 361
c1bdacf9 362Higher level SCMs may provide and manage additional information in the
2fa090b6 363`$GIT_DIR`.
c1bdacf9 364
a1d4aa74 365
2cf565c5
DG
366Terminology
367-----------
6998e4db 368Please see linkgit:gitglossary[7].
2cf565c5
DG
369
370
371Environment Variables
372---------------------
2de9b711 373Various Git commands use the following environment variables:
2cf565c5 374
2de9b711 375The Git Repository
c1bdacf9 376~~~~~~~~~~~~~~~~~~
2de9b711 377These environment variables apply to 'all' core Git commands. Nb: it
c1bdacf9 378is worth noting that they may be used/overridden by SCMS sitting above
f25b98e6 379Git so take care if using a foreign front-end.
c1bdacf9 380
eee7f4a2 381`GIT_INDEX_FILE`::
c1bdacf9 382 This environment allows the specification of an alternate
5f3aa197
LS
383 index file. If not specified, the default of `$GIT_DIR/index`
384 is used.
c1bdacf9 385
eee7f4a2 386`GIT_INDEX_VERSION`::
136347d7
TG
387 This environment variable allows the specification of an index
388 version for new repositories. It won't affect existing index
70320541
NTND
389 files. By default index file version 2 or 3 is used. See
390 linkgit:git-update-index[1] for more information.
136347d7 391
eee7f4a2 392`GIT_OBJECT_DIRECTORY`::
c1bdacf9
DG
393 If the object storage directory is specified via this
394 environment variable then the sha1 directories are created
395 underneath - otherwise the default `$GIT_DIR/objects`
396 directory is used.
397
eee7f4a2 398`GIT_ALTERNATE_OBJECT_DIRECTORIES`::
2de9b711 399 Due to the immutable nature of Git objects, old objects can be
c1bdacf9 400 archived into shared, read-only directories. This variable
80ba074f 401 specifies a ":" separated (on Windows ";" separated) list
2de9b711 402 of Git object directories which can be used to search for Git
80ba074f 403 objects. New objects will not be written to these directories.
cf3c6352 404+
ad471949
AH
405Entries that begin with `"` (double-quote) will be interpreted
406as C-style quoted paths, removing leading and trailing
407double-quotes and respecting backslash escapes. E.g., the value
408`"path-with-\"-and-:-in-it":vanilla-path` has two paths:
409`path-with-"-and-:-in-it` and `vanilla-path`.
c1bdacf9 410
eee7f4a2
TR
411`GIT_DIR`::
412 If the `GIT_DIR` environment variable is set then it
2fa090b6
JH
413 specifies a path to use instead of the default `.git`
414 for the base of the repository.
bcf9626a 415 The `--git-dir` command-line option also sets this value.
c1bdacf9 416
eee7f4a2 417`GIT_WORK_TREE`::
a758a349 418 Set the path to the root of the working tree.
bcf9626a 419 This can also be controlled by the `--work-tree` command-line
892c41b9
ML
420 option and the core.worktree configuration variable.
421
eee7f4a2 422`GIT_NAMESPACE`::
2de9b711 423 Set the Git namespace; see linkgit:gitnamespaces[7] for details.
bcf9626a 424 The `--namespace` command-line option also sets this value.
d49483f0 425
eee7f4a2 426`GIT_CEILING_DIRECTORIES`::
7ec30aaa 427 This should be a colon-separated list of absolute paths. If
3e07d268 428 set, it is a list of directories that Git should not chdir up
7ec30aaa
MH
429 into while looking for a repository directory (useful for
430 excluding slow-loading network directories). It will not
431 exclude the current working directory or a GIT_DIR set on the
432 command line or in the environment. Normally, Git has to read
433 the entries in this list and resolve any symlink that
434 might be present in order to compare them with the current
435 directory. However, if even this access is slow, you
436 can add an empty entry to the list to tell Git that the
437 subsequent entries are not symlinks and needn't be resolved;
438 e.g.,
eee7f4a2 439 `GIT_CEILING_DIRECTORIES=/maybe/symlink::/very/slow/non/symlink`.
0454dd93 440
eee7f4a2 441`GIT_DISCOVERY_ACROSS_FILESYSTEM`::
e6405517 442 When run in a directory that does not have ".git" repository
2de9b711 443 directory, Git tries to find such a directory in the parent
e6405517
JH
444 directories to find the top of the working tree, but by default it
445 does not cross filesystem boundaries. This environment variable
2de9b711 446 can be set to true to tell Git not to stop at filesystem
eee7f4a2
TR
447 boundaries. Like `GIT_CEILING_DIRECTORIES`, this will not affect
448 an explicit repository directory set via `GIT_DIR` or on the
cf87463e 449 command line.
8030e442 450
eee7f4a2 451`GIT_COMMON_DIR`::
c7b3a3d2
NTND
452 If this variable is set to a path, non-worktree files that are
453 normally in $GIT_DIR will be taken from this path
454 instead. Worktree-specific files such as HEAD or index are
529fef20 455 taken from $GIT_DIR. See linkgit:gitrepository-layout[5] and
1eaca7a5 456 linkgit:git-worktree[1] for
c7b3a3d2
NTND
457 details. This variable has lower precedence than other path
458 variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY...
459
2de9b711 460Git Commits
c1bdacf9 461~~~~~~~~~~~
eee7f4a2
TR
462`GIT_AUTHOR_NAME`::
463`GIT_AUTHOR_EMAIL`::
464`GIT_AUTHOR_DATE`::
465`GIT_COMMITTER_NAME`::
466`GIT_COMMITTER_EMAIL`::
467`GIT_COMMITTER_DATE`::
28a94f88 468'EMAIL'::
5162e697 469 see linkgit:git-commit-tree[1]
c1bdacf9 470
2de9b711 471Git Diffs
c1bdacf9 472~~~~~~~~~
eee7f4a2 473`GIT_DIFF_OPTS`::
fde97d8a
SE
474 Only valid setting is "--unified=??" or "-u??" to set the
475 number of context lines shown when a unified diff is created.
476 This takes precedence over any "-U" or "--unified" option
2de9b711 477 value passed on the Git diff command line.
fde97d8a 478
eee7f4a2
TR
479`GIT_EXTERNAL_DIFF`::
480 When the environment variable `GIT_EXTERNAL_DIFF` is set, the
fde97d8a
SE
481 program named by it is called, instead of the diff invocation
482 described above. For a path that is added, removed, or modified,
eee7f4a2 483 `GIT_EXTERNAL_DIFF` is called with 7 parameters:
fde97d8a
SE
484
485 path old-file old-hex old-mode new-file new-hex new-mode
486+
487where:
488
489 <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
490 contents of <old|new>,
d5fa1f1a 491 <old|new>-hex:: are the 40-hexdigit SHA-1 hashes,
fde97d8a 492 <old|new>-mode:: are the octal representation of the file modes.
fde97d8a
SE
493+
494The file parameters can point at the user's working file
495(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
496when a new file is added), or a temporary file (e.g. `old-file` in the
eee7f4a2
TR
497index). `GIT_EXTERNAL_DIFF` should not worry about unlinking the
498temporary file --- it is removed when `GIT_EXTERNAL_DIFF` exits.
fde97d8a 499+
eee7f4a2 500For a path that is unmerged, `GIT_EXTERNAL_DIFF` is called with 1
fde97d8a 501parameter, <path>.
ee7fb0b1 502+
eee7f4a2
TR
503For each path `GIT_EXTERNAL_DIFF` is called, two environment variables,
504`GIT_DIFF_PATH_COUNTER` and `GIT_DIFF_PATH_TOTAL` are set.
ee7fb0b1 505
eee7f4a2 506`GIT_DIFF_PATH_COUNTER`::
ee7fb0b1
ZK
507 A 1-based counter incremented by one for every path.
508
eee7f4a2 509`GIT_DIFF_PATH_TOTAL`::
ee7fb0b1 510 The total number of paths.
2cf565c5 511
575ba9d6
ML
512other
513~~~~~
eee7f4a2 514`GIT_MERGE_VERBOSITY`::
dbddb714
JN
515 A number controlling the amount of output shown by
516 the recursive merge strategy. Overrides merge.verbosity.
5162e697 517 See linkgit:git-merge[1]
dbddb714 518
eee7f4a2 519`GIT_PAGER`::
a7738c77 520 This environment variable overrides `$PAGER`. If it is set
2de9b711 521 to an empty string or to the value "cat", Git will not launch
ab54cd6c
JN
522 a pager. See also the `core.pager` option in
523 linkgit:git-config[1].
c27d205a 524
eee7f4a2 525`GIT_EDITOR`::
36384c97 526 This environment variable overrides `$EDITOR` and `$VISUAL`.
2de9b711 527 It is used by several Git commands when, on interactive mode,
36384c97
RSM
528 an editor is to be launched. See also linkgit:git-var[1]
529 and the `core.editor` option in linkgit:git-config[1].
530
eee7f4a2
TR
531`GIT_SSH`::
532`GIT_SSH_COMMAND`::
39942766
TQ
533 If either of these environment variables is set then 'git fetch'
534 and 'git push' will use the specified command instead of 'ssh'
535 when they need to connect to a remote system.
94b8ae5a
BW
536 The command-line parameters passed to the configured command are
537 determined by the ssh variant. See `ssh.variant` option in
538 linkgit:git-config[1] for details.
d5538b41 539+
39942766
TQ
540`$GIT_SSH_COMMAND` takes precedence over `$GIT_SSH`, and is interpreted
541by the shell, which allows additional arguments to be included.
542`$GIT_SSH` on the other hand must be just the path to a program
543(which can be a wrapper shell script, if additional arguments are
544needed).
d5538b41
SP
545+
546Usually it is easier to configure any desired options through your
547personal `.ssh/config` file. Please consult your ssh documentation
548for further details.
549
dd33e077
SF
550`GIT_SSH_VARIANT`::
551 If this environment variable is set, it overrides Git's autodetection
552 whether `GIT_SSH`/`GIT_SSH_COMMAND`/`core.sshCommand` refer to OpenSSH,
553 plink or tortoiseplink. This variable overrides the config setting
554 `ssh.variant` that serves the same purpose.
555
eee7f4a2 556`GIT_ASKPASS`::
2de9b711 557 If this environment variable is set, then Git commands which need to
453842c9 558 acquire passwords or passphrases (e.g. for HTTP or IMAP authentication)
06ab60c0 559 will call this program with a suitable prompt as command-line argument
ae9f6311 560 and read the password from its STDOUT. See also the `core.askPass`
453842c9
KF
561 option in linkgit:git-config[1].
562
eee7f4a2 563`GIT_TERMINAL_PROMPT`::
e652c0eb
JK
564 If this environment variable is set to `0`, git will not prompt
565 on the terminal (e.g., when asking for HTTP authentication).
566
eee7f4a2 567`GIT_CONFIG_NOSYSTEM`::
e8ef401c
JN
568 Whether to skip reading settings from the system-wide
569 `$(prefix)/etc/gitconfig` file. This environment variable can
570 be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a
571 predictable environment for a picky script, or you can set it
572 temporarily to avoid using a buggy `/etc/gitconfig` file while
573 waiting for someone with sufficient permissions to fix it.
574
eee7f4a2 575`GIT_FLUSH`::
06f59e9f 576 If this environment variable is set to "1", then commands such
0b444cdb 577 as 'git blame' (in incremental mode), 'git rev-list', 'git log',
627a8b8d 578 'git check-attr' and 'git check-ignore' will
f1ed7fea
AS
579 force a flush of the output stream after each record have been
580 flushed. If this
06f59e9f
TT
581 variable is set to "0", the output of these commands will be done
582 using completely buffered I/O. If this environment variable is
2de9b711 583 not set, Git will choose buffered or record-oriented flushing
06f59e9f
TT
584 based on whether stdout appears to be redirected to a file or not.
585
eee7f4a2 586`GIT_TRACE`::
eb9250df
KB
587 Enables general trace messages, e.g. alias expansion, built-in
588 command execution and external command execution.
589+
590If this variable is set to "1", "2" or "true" (comparison
591is case insensitive), trace messages will be printed to
592stderr.
593+
594If the variable is set to an integer value greater than 2
595and lower than 10 (strictly) then Git will interpret this
596value as an open file descriptor and will try to write the
597trace messages into this file descriptor.
598+
599Alternatively, if the variable is set to an absolute path
600(starting with a '/' character), Git will interpret this
fa0aeea7
SG
601as a file path and will try to append the trace messages
602to it.
eb9250df
KB
603+
604Unsetting the variable, or setting it to empty, "0" or
605"false" (case insensitive) disables trace messages.
575ba9d6 606
bd76afd1
AV
607`GIT_TRACE_FSMONITOR`::
608 Enables trace messages for the filesystem monitor extension.
609 See `GIT_TRACE` for available trace output options.
610
eee7f4a2 611`GIT_TRACE_PACK_ACCESS`::
67dc598e 612 Enables trace messages for all accesses to any packs. For each
b12ca963
NTND
613 access, the pack file name and an offset in the pack is
614 recorded. This may be helpful for troubleshooting some
615 pack-related performance problems.
eee7f4a2 616 See `GIT_TRACE` for available trace output options.
b12ca963 617
eee7f4a2 618`GIT_TRACE_PACKET`::
eb9250df
KB
619 Enables trace messages for all packets coming in or out of a
620 given program. This can help with debugging object negotiation
621 or other protocol issues. Tracing is turned off at a packet
eee7f4a2
TR
622 starting with "PACK" (but see `GIT_TRACE_PACKFILE` below).
623 See `GIT_TRACE` for available trace output options.
eb9250df 624
eee7f4a2 625`GIT_TRACE_PACKFILE`::
32359838
JK
626 Enables tracing of packfiles sent or received by a
627 given program. Unlike other trace output, this trace is
628 verbatim: no headers, and no quoting of binary data. You almost
629 certainly want to direct into a file (e.g.,
630 `GIT_TRACE_PACKFILE=/tmp/my.pack`) rather than displaying it on
631 the terminal or mixing it with other trace output.
632+
633Note that this is currently only implemented for the client side
634of clones and fetches.
635
eee7f4a2 636`GIT_TRACE_PERFORMANCE`::
578da039
KB
637 Enables performance related trace messages, e.g. total execution
638 time of each Git command.
eee7f4a2 639 See `GIT_TRACE` for available trace output options.
578da039 640
eee7f4a2 641`GIT_TRACE_SETUP`::
eb9250df
KB
642 Enables trace messages printing the .git, working tree and current
643 working directory after Git has completed its setup phase.
eee7f4a2 644 See `GIT_TRACE` for available trace output options.
eb9250df 645
eee7f4a2 646`GIT_TRACE_SHALLOW`::
eb9250df
KB
647 Enables trace messages that can help debugging fetching /
648 cloning of shallow repositories.
eee7f4a2 649 See `GIT_TRACE` for available trace output options.
1dd278ce 650
2f84df2c 651`GIT_TRACE_CURL`::
74c682d3
EP
652 Enables a curl full trace dump of all incoming and outgoing data,
653 including descriptive information, of the git transport protocol.
2f84df2c
JH
654 This is similar to doing curl `--trace-ascii` on the command line.
655 This option overrides setting the `GIT_CURL_VERBOSE` environment
74c682d3 656 variable.
2f84df2c 657 See `GIT_TRACE` for available trace output options.
74c682d3 658
8ba18e6f
JT
659`GIT_TRACE_CURL_NO_DATA`::
660 When a curl trace is enabled (see `GIT_TRACE_CURL` above), do not dump
661 data (that is, only dump info lines and headers).
662
e4b75d6a 663`GIT_TRACE2`::
04b7e86e 664 Enables more detailed trace messages from the "trace2" library.
e4b75d6a 665 Output from `GIT_TRACE2` is a simple text-based format for human
04b7e86e
DS
666 readability.
667+
4e0d3aa1
SG
668If this variable is set to "1", "2" or "true" (comparison
669is case insensitive), trace messages will be printed to
670stderr.
671+
672If the variable is set to an integer value greater than 2
673and lower than 10 (strictly) then Git will interpret this
674value as an open file descriptor and will try to write the
675trace messages into this file descriptor.
676+
677Alternatively, if the variable is set to an absolute path
678(starting with a '/' character), Git will interpret this
679as a file path and will try to append the trace messages
680to it. If the path already exists and is a directory, the
681trace messages will be written to files (one per process)
682in that directory, named according to the last component
683of the SID and an optional counter (to avoid filename
684collisions).
685+
686In addition, if the variable is set to
687`af_unix:[<socket_type>:]<absolute-pathname>`, Git will try
688to open the path as a Unix Domain Socket. The socket type
689can be either `stream` or `dgram`.
690+
691Unsetting the variable, or setting it to empty, "0" or
692"false" (case insensitive) disables trace messages.
693+
694See link:technical/api-trace2.html[Trace2 documentation]
695for full details.
696
04b7e86e 697
e4b75d6a 698`GIT_TRACE2_EVENT`::
04b7e86e 699 This setting writes a JSON-based format that is suited for machine
4e0d3aa1
SG
700 interpretation.
701 See `GIT_TRACE2` for available trace output options and
702 link:technical/api-trace2.html[Trace2 documentation] for full details.
04b7e86e 703
e4b75d6a
SG
704`GIT_TRACE2_PERF`::
705 In addition to the text-based messages available in `GIT_TRACE2`, this
04b7e86e 706 setting writes a column-based format for understanding nesting
4e0d3aa1
SG
707 regions.
708 See `GIT_TRACE2` for available trace output options and
709 link:technical/api-trace2.html[Trace2 documentation] for full details.
04b7e86e 710
83411783
JT
711`GIT_REDACT_COOKIES`::
712 This can be set to a comma-separated list of strings. When a curl trace
713 is enabled (see `GIT_TRACE_CURL` above), whenever a "Cookies:" header
714 sent by the client is dumped, values of cookies whose key is in that
715 list (case-sensitive) are redacted.
716
eee7f4a2 717`GIT_LITERAL_PATHSPECS`::
2de9b711 718 Setting this variable to `1` will cause Git to treat all
823ab40f
JK
719 pathspecs literally, rather than as glob patterns. For example,
720 running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search
721 for commits that touch the path `*.c`, not any paths that the
722 glob `*.c` matches. You might want this if you are feeding
2de9b711 723 literal paths to Git (e.g., paths previously given to you by
823ab40f
JK
724 `git ls-tree`, `--raw` diff output, etc).
725
eee7f4a2 726`GIT_GLOB_PATHSPECS`::
bd30c2e4
NTND
727 Setting this variable to `1` will cause Git to treat all
728 pathspecs as glob patterns (aka "glob" magic).
729
eee7f4a2 730`GIT_NOGLOB_PATHSPECS`::
bd30c2e4
NTND
731 Setting this variable to `1` will cause Git to treat all
732 pathspecs as literal (aka "literal" magic).
733
eee7f4a2 734`GIT_ICASE_PATHSPECS`::
93d93537
NTND
735 Setting this variable to `1` will cause Git to treat all
736 pathspecs as case-insensitive.
737
eee7f4a2 738`GIT_REFLOG_ACTION`::
c3e2d189
JH
739 When a ref is updated, reflog entries are created to keep
740 track of the reason why the ref was updated (which is
741 typically the name of the high-level command that updated
742 the ref), in addition to the old and new values of the ref.
743 A scripted Porcelain command can use set_reflog_action
744 helper function in `git-sh-setup` to set its name to this
745 variable when it is invoked as the top level command by the
746 end user, to be recorded in the body of the reflog.
747
eee7f4a2 748`GIT_REF_PARANOIA`::
49672f26
JK
749 If set to `1`, include broken or badly named refs when iterating
750 over lists of refs. In a normal, non-corrupted repository, this
751 does nothing. However, enabling it may help git to detect and
752 abort some operations in the presence of broken refs. Git sets
753 this variable automatically when performing destructive
754 operations like linkgit:git-prune[1]. You should not need to set
755 it yourself unless you want to be paranoid about making sure
756 an operation has touched every ref (e.g., because you are
757 cloning a repository to make a backup).
758
eee7f4a2 759`GIT_ALLOW_PROTOCOL`::
f1762d77
BW
760 If set to a colon-separated list of protocols, behave as if
761 `protocol.allow` is set to `never`, and each of the listed
762 protocols has `protocol.<name>.allow` set to `always`
763 (overriding any existing configuration). In other words, any
764 protocol not mentioned will be disallowed (i.e., this is a
765 whitelist, not a blacklist). See the description of
766 `protocol.allow` in linkgit:git-config[1] for more details.
767
768`GIT_PROTOCOL_FROM_USER`::
769 Set to 0 to prevent protocols used by fetch/push/clone which are
770 configured to the `user` state. This is useful to restrict recursive
771 submodule initialization from an untrusted repository or for programs
772 which feed potentially-untrusted URLS to git commands. See
773 linkgit:git-config[1] for more details.
823ab40f 774
373d70ef
BW
775`GIT_PROTOCOL`::
776 For internal use only. Used in handshaking the wire protocol.
777 Contains a colon ':' separated list of keys with optional values
778 'key[=value]'. Presence of unknown keys and values must be
779 ignored.
780
27344d6a
JK
781`GIT_OPTIONAL_LOCKS`::
782 If set to `0`, Git will complete any requested operation without
783 performing any optional sub-operations that require taking a lock.
784 For example, this will prevent `git status` from refreshing the
785 index as a side effect. This is useful for processes running in
786 the background which do not want to cause lock contention with
787 other operations on the repository. Defaults to `1`.
788
b2f55717
JS
789`GIT_REDIRECT_STDIN`::
790`GIT_REDIRECT_STDOUT`::
791`GIT_REDIRECT_STDERR`::
792 Windows-only: allow redirecting the standard input/output/error
793 handles to paths specified by the environment variables. This is
794 particularly useful in multi-threaded applications where the
795 canonical way to pass standard handles via `CreateProcess()` is
796 not an option because it would require the handles to be marked
797 inheritable (and consequently *every* spawned process would
798 inherit them, possibly blocking regular Git operations). The
799 primary intended use case is to use named pipes for communication
800 (e.g. `\\.\pipe\my-git-stdin-123`).
801+
802Two special values are supported: `off` will simply close the
803corresponding standard handle, and if `GIT_REDIRECT_STDERR` is
804`2>&1`, standard error will be redirected to the same handle as
805standard output.
806
a2cd709d
AR
807`GIT_PRINT_SHA1_ELLIPSIS` (deprecated)::
808 If set to `yes`, print an ellipsis following an
809 (abbreviated) SHA-1 value. This affects indications of
810 detached HEADs (linkgit:git-checkout[1]) and the raw
811 diff output (linkgit:git-diff[1]). Printing an
812 ellipsis in the cases mentioned is no longer considered
813 adequate and support for it is likely to be removed in the
814 foreseeable future (along with the variable).
815
8db9307c
JH
816Discussion[[Discussion]]
817------------------------
40dac517
BF
818
819More detail on the following is available from the
2de9b711 820link:user-manual.html#git-concepts[Git concepts chapter of the
6998e4db 821user-manual] and linkgit:gitcore-tutorial[7].
40dac517 822
2de9b711 823A Git project normally consists of a working directory with a ".git"
40dac517
BF
824subdirectory at the top level. The .git directory contains, among other
825things, a compressed object database representing the complete history
826of the project, an "index" file which links that history to the current
827contents of the working tree, and named pointers into that history such
828as tags and branch heads.
829
830The object database contains objects of three main types: blobs, which
831hold file data; trees, which point to blobs and other trees to build up
02ff6250 832directory hierarchies; and commits, which each reference a single tree
40dac517
BF
833and some number of parent commits.
834
835The commit, equivalent to what other systems call a "changeset" or
836"version", represents a step in the project's history, and each parent
837represents an immediately preceding step. Commits with more than one
838parent represent merges of independent lines of development.
839
d5fa1f1a 840All objects are named by the SHA-1 hash of their contents, normally
40dac517
BF
841written as a string of 40 hex digits. Such names are globally unique.
842The entire history leading up to a commit can be vouched for by signing
843just that commit. A fourth object type, the tag, is provided for this
844purpose.
845
846When first created, objects are stored in individual files, but for
847efficiency may later be compressed together into "pack files".
848
849Named pointers called refs mark interesting points in history. A ref
d5fa1f1a
TA
850may contain the SHA-1 name of an object or the name of another ref. Refs
851with names beginning `ref/head/` contain the SHA-1 name of the most
852recent commit (or "head") of a branch under development. SHA-1 names of
40dac517
BF
853tags of interest are stored under `ref/tags/`. A special ref named
854`HEAD` contains the name of the currently checked-out branch.
855
856The index file is initialized with a list of all paths and, for each
857path, a blob object and a set of attributes. The blob object represents
858the contents of the file as of the head of the current branch. The
859attributes (last modified time, size, etc.) are taken from the
860corresponding file in the working tree. Subsequent changes to the
861working tree can be found by comparing these attributes. The index may
862be updated with new content, and new commits may be created from the
863content stored in the index.
864
865The index is also capable of storing multiple entries (called "stages")
866for a given pathname. These stages are used to hold the various
867unmerged version of a file when a merge is in progress.
6c84e2e0 868
7687ae98
JH
869FURTHER DOCUMENTATION
870---------------------
871
872See the references in the "description" section to get started
2de9b711 873using Git. The following is probably more detail than necessary
7687ae98
JH
874for a first-time user.
875
2de9b711 876The link:user-manual.html#git-concepts[Git concepts chapter of the
7687ae98 877user-manual] and linkgit:gitcore-tutorial[7] both provide
2de9b711 878introductions to the underlying Git architecture.
7687ae98
JH
879
880See linkgit:gitworkflows[7] for an overview of recommended workflows.
881
882See also the link:howto-index.html[howto] documents for some useful
883examples.
884
885The internals are documented in the
48a8c26c 886link:technical/api-index.html[Git API documentation].
7687ae98
JH
887
888Users migrating from CVS may also want to
889read linkgit:gitcvs-migration[7].
890
891
cb22bc44
AE
892Authors
893-------
48bb914e 894Git was started by Linus Torvalds, and is currently maintained by Junio
2de9b711 895C Hamano. Numerous contributions have come from the Git mailing list
405869d0 896<git@vger.kernel.org>. http://www.openhub.net/p/git/contributors/summary
6ecc01f2
JH
897gives you a more complete list of contributors.
898
899If you have a clone of git.git itself, the
d8f708f8
JK
900output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you
901the authors for specific parts of the project.
2cf565c5 902
c97ca277
JH
903Reporting Bugs
904--------------
905
906Report bugs to the Git mailing list <git@vger.kernel.org> where the
907development and maintenance is primarily done. You do not have to be
c56170a0
JN
908subscribed to the list to send a message there. See the list archive
909at https://public-inbox.org/git for previous bug reports and other
910discussions.
c97ca277 911
2caa7b8d
ÆAB
912Issues which are security relevant should be disclosed privately to
913the Git Security mailing list <git-security@googlegroups.com>.
914
497c8331
CC
915SEE ALSO
916--------
917linkgit:gittutorial[7], linkgit:gittutorial-2[7],
673151a9 918linkgit:giteveryday[7], linkgit:gitcvs-migration[7],
497c8331 919linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
801a011d
TR
920linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],
921linkgit:gitworkflows[7]
497c8331 922
2cf565c5
DG
923GIT
924---
9e1f0a85 925Part of the linkgit:git[1] suite