Git 2.14.2
[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]
d49483f0
JT
14 [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]
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
7f0a02be
AH
78foo.bar= ...`) sets `foo.bar` to the empty string which ` git config
79--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
463a849d 106--no-pager::
2de9b711 107 Do not pipe Git output into a pager.
463a849d 108
6acbcb92
JS
109--git-dir=<path>::
110 Set the path to the repository. This can also be controlled by
47d81b5c 111 setting the `GIT_DIR` environment variable. It can be an absolute
302cc11a 112 path or relative path to current working directory.
6acbcb92 113
892c41b9 114--work-tree=<path>::
ea472c1e
JH
115 Set the path to the working tree. It can be an absolute path
116 or a path relative to the current working directory.
892c41b9
ML
117 This can also be controlled by setting the GIT_WORK_TREE
118 environment variable and the core.worktree configuration
ea472c1e
JH
119 variable (see core.worktree in linkgit:git-config[1] for a
120 more detailed discussion).
892c41b9 121
d49483f0 122--namespace=<path>::
2de9b711 123 Set the Git namespace. See linkgit:gitnamespaces[7] for more
d49483f0
JT
124 details. Equivalent to setting the `GIT_NAMESPACE` environment
125 variable.
126
74866d75
BW
127--super-prefix=<path>::
128 Currently for internal use only. Set a prefix which gives a path from
129 above a repository down to its root. One use is to give submodules
130 context about the superproject that invoked it.
131
6acbcb92 132--bare::
9277d602
JH
133 Treat the repository as a bare repository. If GIT_DIR
134 environment is not set, it is set to the current working
135 directory.
136
b0fa7ab5 137--no-replace-objects::
2de9b711 138 Do not use replacement refs to replace Git objects. See
b0fa7ab5
CC
139 linkgit:git-replace[1] for more information.
140
823ab40f 141--literal-pathspecs::
a16bf9dd
NTND
142 Treat pathspecs literally (i.e. no globbing, no pathspec magic).
143 This is equivalent to setting the `GIT_LITERAL_PATHSPECS` environment
823ab40f
JK
144 variable to `1`.
145
6fb02165 146--glob-pathspecs::
bd30c2e4
NTND
147 Add "glob" magic to all pathspec. This is equivalent to setting
148 the `GIT_GLOB_PATHSPECS` environment variable to `1`. Disabling
149 globbing on individual pathspecs can be done using pathspec
150 magic ":(literal)"
151
6fb02165 152--noglob-pathspecs::
bd30c2e4
NTND
153 Add "literal" magic to all pathspec. This is equivalent to setting
154 the `GIT_NOGLOB_PATHSPECS` environment variable to `1`. Enabling
155 globbing on individual pathspecs can be done using pathspec
156 magic ":(glob)"
9755afbd 157
6fb02165 158--icase-pathspecs::
93d93537
NTND
159 Add "icase" magic to all pathspec. This is equivalent to setting
160 the `GIT_ICASE_PATHSPECS` environment variable to `1`.
9755afbd 161
23091e95
BF
162GIT COMMANDS
163------------
9755afbd 164
2de9b711 165We divide Git into high level ("porcelain") commands and low level
23091e95 166("plumbing") commands.
8b15e2fb 167
23091e95
BF
168High-level commands (porcelain)
169-------------------------------
170
171We separate the porcelain commands into the main commands and some
172ancillary user utilities.
173
174Main porcelain commands
175~~~~~~~~~~~~~~~~~~~~~~~
905197de 176
377e8139 177include::cmds-mainporcelain.txt[]
e31bb3bb 178
90933efb 179Ancillary Commands
23091e95 180~~~~~~~~~~~~~~~~~~
2f2de9b4
JH
181Manipulators:
182
377e8139 183include::cmds-ancillarymanipulators.txt[]
204ee6a9 184
90933efb 185Interrogators:
204ee6a9 186
377e8139 187include::cmds-ancillaryinterrogators.txt[]
7fc9d69f 188
89bf2077
JH
189
190Interacting with Others
191~~~~~~~~~~~~~~~~~~~~~~~
192
193These commands are to interact with foreign SCM and with other
194people via patch over e-mail.
195
196include::cmds-foreignscminterface.txt[]
197
198
b1f33d62
RR
199Low-level commands (plumbing)
200-----------------------------
201
2de9b711 202Although Git includes its
b1f33d62
RR
203own porcelain layer, its low-level commands are sufficient to support
204development of alternative porcelains. Developers of such porcelains
5162e697
DM
205might start by reading about linkgit:git-update-index[1] and
206linkgit:git-read-tree[1].
b1f33d62 207
89bf2077
JH
208The interface (input, output, set of options and the semantics)
209to these low-level commands are meant to be a lot more stable
210than Porcelain level commands, because these commands are
211primarily for scripted use. The interface to Porcelain commands
212on the other hand are subject to change in order to improve the
213end user experience.
214
215The following description divides
216the low-level commands into commands that manipulate objects (in
b1f33d62
RR
217the repository, index, and working tree), commands that interrogate and
218compare objects, and commands that move objects and references between
219repositories.
220
89bf2077 221
b1f33d62
RR
222Manipulation commands
223~~~~~~~~~~~~~~~~~~~~~
b1f33d62 224
377e8139 225include::cmds-plumbingmanipulators.txt[]
b1f33d62
RR
226
227
228Interrogation commands
229~~~~~~~~~~~~~~~~~~~~~~
230
377e8139 231include::cmds-plumbinginterrogators.txt[]
b1f33d62
RR
232
233In general, the interrogate commands do not touch the files in
234the working tree.
235
236
237Synching repositories
238~~~~~~~~~~~~~~~~~~~~~
239
377e8139 240include::cmds-synchingrepositories.txt[]
b1f33d62 241
57f6ec02 242The following are helper commands used by the above; end users
89bf2077
JH
243typically do not use them directly.
244
245include::cmds-synchelpers.txt[]
246
247
248Internal helper commands
249~~~~~~~~~~~~~~~~~~~~~~~~
250
251These are internal helper commands used by other commands; end
252users typically do not use them directly.
253
254include::cmds-purehelpers.txt[]
255
b1f33d62 256
5773c9f2
JH
257Configuration Mechanism
258-----------------------
259
c0179c0d
MM
260Git uses a simple text format to store customizations that are per
261repository and are per user. Such a configuration file may look
262like this:
5773c9f2
JH
263
264------------
265#
2fa090b6 266# A '#' or ';' character indicates a comment.
5773c9f2
JH
267#
268
269; core variables
270[core]
271 ; Don't trust file modes
272 filemode = false
273
274; user identity
275[user]
276 name = "Junio C Hamano"
c0179c0d 277 email = "gitster@pobox.com"
5773c9f2
JH
278
279------------
280
281Various commands read from the configuration file and adjust
06300d97 282their operation accordingly. See linkgit:git-config[1] for a
c0179c0d 283list and more details about the configuration mechanism.
5773c9f2
JH
284
285
6c84e2e0 286Identifier Terminology
2cf565c5
DG
287----------------------
288<object>::
2fa090b6 289 Indicates the object name for any type of object.
2cf565c5
DG
290
291<blob>::
2fa090b6 292 Indicates a blob object name.
2cf565c5
DG
293
294<tree>::
2fa090b6 295 Indicates a tree object name.
2cf565c5
DG
296
297<commit>::
2fa090b6 298 Indicates a commit object name.
2cf565c5
DG
299
300<tree-ish>::
2fa090b6 301 Indicates a tree, commit or tag object name. A
6c84e2e0
DG
302 command that takes a <tree-ish> argument ultimately wants to
303 operate on a <tree> object but automatically dereferences
304 <commit> and <tag> objects that point at a <tree>.
2cf565c5 305
043d7605
TT
306<commit-ish>::
307 Indicates a commit or tag object name. A
308 command that takes a <commit-ish> argument ultimately wants to
309 operate on a <commit> object but automatically dereferences
310 <tag> objects that point at a <commit>.
311
2cf565c5
DG
312<type>::
313 Indicates that an object type is required.
2fa090b6 314 Currently one of: `blob`, `tree`, `commit`, or `tag`.
2cf565c5
DG
315
316<file>::
2fa090b6
JH
317 Indicates a filename - almost always relative to the
318 root of the tree structure `GIT_INDEX_FILE` describes.
2cf565c5 319
c1bdacf9
DG
320Symbolic Identifiers
321--------------------
2de9b711 322Any Git command accepting any <object> can also use the following
6c84e2e0 323symbolic notation:
c1bdacf9
DG
324
325HEAD::
0abcfbff 326 indicates the head of the current branch.
2fa090b6 327
c1bdacf9 328<tag>::
2fa090b6 329 a valid tag 'name'
0abcfbff 330 (i.e. a `refs/tags/<tag>` reference).
2fa090b6 331
c1bdacf9 332<head>::
2fa090b6 333 a valid head 'name'
0abcfbff 334 (i.e. a `refs/heads/<head>` reference).
2fa090b6 335
d47107d8 336For a more complete list of ways to spell object names, see
9d83e382 337"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
d47107d8 338
c1bdacf9
DG
339
340File/Directory Structure
341------------------------
c1bdacf9 342
6998e4db 343Please see the linkgit:gitrepository-layout[5] document.
c1bdacf9 344
6998e4db 345Read linkgit:githooks[5] for more details about each hook.
6250ad1e 346
c1bdacf9 347Higher level SCMs may provide and manage additional information in the
2fa090b6 348`$GIT_DIR`.
c1bdacf9 349
a1d4aa74 350
2cf565c5
DG
351Terminology
352-----------
6998e4db 353Please see linkgit:gitglossary[7].
2cf565c5
DG
354
355
356Environment Variables
357---------------------
2de9b711 358Various Git commands use the following environment variables:
2cf565c5 359
2de9b711 360The Git Repository
c1bdacf9 361~~~~~~~~~~~~~~~~~~
2de9b711 362These environment variables apply to 'all' core Git commands. Nb: it
c1bdacf9 363is worth noting that they may be used/overridden by SCMS sitting above
f25b98e6 364Git so take care if using a foreign front-end.
c1bdacf9 365
eee7f4a2 366`GIT_INDEX_FILE`::
c1bdacf9 367 This environment allows the specification of an alternate
5f3aa197
LS
368 index file. If not specified, the default of `$GIT_DIR/index`
369 is used.
c1bdacf9 370
eee7f4a2 371`GIT_INDEX_VERSION`::
136347d7
TG
372 This environment variable allows the specification of an index
373 version for new repositories. It won't affect existing index
70320541
NTND
374 files. By default index file version 2 or 3 is used. See
375 linkgit:git-update-index[1] for more information.
136347d7 376
eee7f4a2 377`GIT_OBJECT_DIRECTORY`::
c1bdacf9
DG
378 If the object storage directory is specified via this
379 environment variable then the sha1 directories are created
380 underneath - otherwise the default `$GIT_DIR/objects`
381 directory is used.
382
eee7f4a2 383`GIT_ALTERNATE_OBJECT_DIRECTORIES`::
2de9b711 384 Due to the immutable nature of Git objects, old objects can be
c1bdacf9 385 archived into shared, read-only directories. This variable
80ba074f 386 specifies a ":" separated (on Windows ";" separated) list
2de9b711 387 of Git object directories which can be used to search for Git
80ba074f 388 objects. New objects will not be written to these directories.
cf3c6352
JK
389+
390 Entries that begin with `"` (double-quote) will be interpreted
391 as C-style quoted paths, removing leading and trailing
392 double-quotes and respecting backslash escapes. E.g., the value
393 `"path-with-\"-and-:-in-it":vanilla-path` has two paths:
394 `path-with-"-and-:-in-it` and `vanilla-path`.
c1bdacf9 395
eee7f4a2
TR
396`GIT_DIR`::
397 If the `GIT_DIR` environment variable is set then it
2fa090b6
JH
398 specifies a path to use instead of the default `.git`
399 for the base of the repository.
bcf9626a 400 The `--git-dir` command-line option also sets this value.
c1bdacf9 401
eee7f4a2 402`GIT_WORK_TREE`::
a758a349 403 Set the path to the root of the working tree.
bcf9626a 404 This can also be controlled by the `--work-tree` command-line
892c41b9
ML
405 option and the core.worktree configuration variable.
406
eee7f4a2 407`GIT_NAMESPACE`::
2de9b711 408 Set the Git namespace; see linkgit:gitnamespaces[7] for details.
bcf9626a 409 The `--namespace` command-line option also sets this value.
d49483f0 410
eee7f4a2 411`GIT_CEILING_DIRECTORIES`::
7ec30aaa 412 This should be a colon-separated list of absolute paths. If
3e07d268 413 set, it is a list of directories that Git should not chdir up
7ec30aaa
MH
414 into while looking for a repository directory (useful for
415 excluding slow-loading network directories). It will not
416 exclude the current working directory or a GIT_DIR set on the
417 command line or in the environment. Normally, Git has to read
418 the entries in this list and resolve any symlink that
419 might be present in order to compare them with the current
420 directory. However, if even this access is slow, you
421 can add an empty entry to the list to tell Git that the
422 subsequent entries are not symlinks and needn't be resolved;
423 e.g.,
eee7f4a2 424 `GIT_CEILING_DIRECTORIES=/maybe/symlink::/very/slow/non/symlink`.
0454dd93 425
eee7f4a2 426`GIT_DISCOVERY_ACROSS_FILESYSTEM`::
e6405517 427 When run in a directory that does not have ".git" repository
2de9b711 428 directory, Git tries to find such a directory in the parent
e6405517
JH
429 directories to find the top of the working tree, but by default it
430 does not cross filesystem boundaries. This environment variable
2de9b711 431 can be set to true to tell Git not to stop at filesystem
eee7f4a2
TR
432 boundaries. Like `GIT_CEILING_DIRECTORIES`, this will not affect
433 an explicit repository directory set via `GIT_DIR` or on the
cf87463e 434 command line.
8030e442 435
eee7f4a2 436`GIT_COMMON_DIR`::
c7b3a3d2
NTND
437 If this variable is set to a path, non-worktree files that are
438 normally in $GIT_DIR will be taken from this path
439 instead. Worktree-specific files such as HEAD or index are
529fef20 440 taken from $GIT_DIR. See linkgit:gitrepository-layout[5] and
1eaca7a5 441 linkgit:git-worktree[1] for
c7b3a3d2
NTND
442 details. This variable has lower precedence than other path
443 variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY...
444
2de9b711 445Git Commits
c1bdacf9 446~~~~~~~~~~~
eee7f4a2
TR
447`GIT_AUTHOR_NAME`::
448`GIT_AUTHOR_EMAIL`::
449`GIT_AUTHOR_DATE`::
450`GIT_COMMITTER_NAME`::
451`GIT_COMMITTER_EMAIL`::
452`GIT_COMMITTER_DATE`::
28a94f88 453'EMAIL'::
5162e697 454 see linkgit:git-commit-tree[1]
c1bdacf9 455
2de9b711 456Git Diffs
c1bdacf9 457~~~~~~~~~
eee7f4a2 458`GIT_DIFF_OPTS`::
fde97d8a
SE
459 Only valid setting is "--unified=??" or "-u??" to set the
460 number of context lines shown when a unified diff is created.
461 This takes precedence over any "-U" or "--unified" option
2de9b711 462 value passed on the Git diff command line.
fde97d8a 463
eee7f4a2
TR
464`GIT_EXTERNAL_DIFF`::
465 When the environment variable `GIT_EXTERNAL_DIFF` is set, the
fde97d8a
SE
466 program named by it is called, instead of the diff invocation
467 described above. For a path that is added, removed, or modified,
eee7f4a2 468 `GIT_EXTERNAL_DIFF` is called with 7 parameters:
fde97d8a
SE
469
470 path old-file old-hex old-mode new-file new-hex new-mode
471+
472where:
473
474 <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
475 contents of <old|new>,
d5fa1f1a 476 <old|new>-hex:: are the 40-hexdigit SHA-1 hashes,
fde97d8a 477 <old|new>-mode:: are the octal representation of the file modes.
fde97d8a
SE
478+
479The file parameters can point at the user's working file
480(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
481when a new file is added), or a temporary file (e.g. `old-file` in the
eee7f4a2
TR
482index). `GIT_EXTERNAL_DIFF` should not worry about unlinking the
483temporary file --- it is removed when `GIT_EXTERNAL_DIFF` exits.
fde97d8a 484+
eee7f4a2 485For a path that is unmerged, `GIT_EXTERNAL_DIFF` is called with 1
fde97d8a 486parameter, <path>.
ee7fb0b1 487+
eee7f4a2
TR
488For each path `GIT_EXTERNAL_DIFF` is called, two environment variables,
489`GIT_DIFF_PATH_COUNTER` and `GIT_DIFF_PATH_TOTAL` are set.
ee7fb0b1 490
eee7f4a2 491`GIT_DIFF_PATH_COUNTER`::
ee7fb0b1
ZK
492 A 1-based counter incremented by one for every path.
493
eee7f4a2 494`GIT_DIFF_PATH_TOTAL`::
ee7fb0b1 495 The total number of paths.
2cf565c5 496
575ba9d6
ML
497other
498~~~~~
eee7f4a2 499`GIT_MERGE_VERBOSITY`::
dbddb714
JN
500 A number controlling the amount of output shown by
501 the recursive merge strategy. Overrides merge.verbosity.
5162e697 502 See linkgit:git-merge[1]
dbddb714 503
eee7f4a2 504`GIT_PAGER`::
a7738c77 505 This environment variable overrides `$PAGER`. If it is set
2de9b711 506 to an empty string or to the value "cat", Git will not launch
ab54cd6c
JN
507 a pager. See also the `core.pager` option in
508 linkgit:git-config[1].
c27d205a 509
eee7f4a2 510`GIT_EDITOR`::
36384c97 511 This environment variable overrides `$EDITOR` and `$VISUAL`.
2de9b711 512 It is used by several Git commands when, on interactive mode,
36384c97
RSM
513 an editor is to be launched. See also linkgit:git-var[1]
514 and the `core.editor` option in linkgit:git-config[1].
515
eee7f4a2
TR
516`GIT_SSH`::
517`GIT_SSH_COMMAND`::
39942766
TQ
518 If either of these environment variables is set then 'git fetch'
519 and 'git push' will use the specified command instead of 'ssh'
520 when they need to connect to a remote system.
521 The command will be given exactly two or four arguments: the
522 'username@host' (or just 'host') from the URL and the shell
523 command to execute on that remote system, optionally preceded by
23f8239b 524 `-p` (literally) and the 'port' from the URL when it specifies
39942766 525 something other than the default SSH port.
d5538b41 526+
39942766
TQ
527`$GIT_SSH_COMMAND` takes precedence over `$GIT_SSH`, and is interpreted
528by the shell, which allows additional arguments to be included.
529`$GIT_SSH` on the other hand must be just the path to a program
530(which can be a wrapper shell script, if additional arguments are
531needed).
d5538b41
SP
532+
533Usually it is easier to configure any desired options through your
534personal `.ssh/config` file. Please consult your ssh documentation
535for further details.
536
dd33e077
SF
537`GIT_SSH_VARIANT`::
538 If this environment variable is set, it overrides Git's autodetection
539 whether `GIT_SSH`/`GIT_SSH_COMMAND`/`core.sshCommand` refer to OpenSSH,
540 plink or tortoiseplink. This variable overrides the config setting
541 `ssh.variant` that serves the same purpose.
542
eee7f4a2 543`GIT_ASKPASS`::
2de9b711 544 If this environment variable is set, then Git commands which need to
453842c9 545 acquire passwords or passphrases (e.g. for HTTP or IMAP authentication)
06ab60c0 546 will call this program with a suitable prompt as command-line argument
ae9f6311 547 and read the password from its STDOUT. See also the `core.askPass`
453842c9
KF
548 option in linkgit:git-config[1].
549
eee7f4a2 550`GIT_TERMINAL_PROMPT`::
e652c0eb
JK
551 If this environment variable is set to `0`, git will not prompt
552 on the terminal (e.g., when asking for HTTP authentication).
553
eee7f4a2 554`GIT_CONFIG_NOSYSTEM`::
e8ef401c
JN
555 Whether to skip reading settings from the system-wide
556 `$(prefix)/etc/gitconfig` file. This environment variable can
557 be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a
558 predictable environment for a picky script, or you can set it
559 temporarily to avoid using a buggy `/etc/gitconfig` file while
560 waiting for someone with sufficient permissions to fix it.
561
eee7f4a2 562`GIT_FLUSH`::
06f59e9f 563 If this environment variable is set to "1", then commands such
0b444cdb 564 as 'git blame' (in incremental mode), 'git rev-list', 'git log',
627a8b8d 565 'git check-attr' and 'git check-ignore' will
f1ed7fea
AS
566 force a flush of the output stream after each record have been
567 flushed. If this
06f59e9f
TT
568 variable is set to "0", the output of these commands will be done
569 using completely buffered I/O. If this environment variable is
2de9b711 570 not set, Git will choose buffered or record-oriented flushing
06f59e9f
TT
571 based on whether stdout appears to be redirected to a file or not.
572
eee7f4a2 573`GIT_TRACE`::
eb9250df
KB
574 Enables general trace messages, e.g. alias expansion, built-in
575 command execution and external command execution.
576+
577If this variable is set to "1", "2" or "true" (comparison
578is case insensitive), trace messages will be printed to
579stderr.
580+
581If the variable is set to an integer value greater than 2
582and lower than 10 (strictly) then Git will interpret this
583value as an open file descriptor and will try to write the
584trace messages into this file descriptor.
585+
586Alternatively, if the variable is set to an absolute path
587(starting with a '/' character), Git will interpret this
588as a file path and will try to write the trace messages
589into it.
590+
591Unsetting the variable, or setting it to empty, "0" or
592"false" (case insensitive) disables trace messages.
575ba9d6 593
eee7f4a2 594`GIT_TRACE_PACK_ACCESS`::
67dc598e 595 Enables trace messages for all accesses to any packs. For each
b12ca963
NTND
596 access, the pack file name and an offset in the pack is
597 recorded. This may be helpful for troubleshooting some
598 pack-related performance problems.
eee7f4a2 599 See `GIT_TRACE` for available trace output options.
b12ca963 600
eee7f4a2 601`GIT_TRACE_PACKET`::
eb9250df
KB
602 Enables trace messages for all packets coming in or out of a
603 given program. This can help with debugging object negotiation
604 or other protocol issues. Tracing is turned off at a packet
eee7f4a2
TR
605 starting with "PACK" (but see `GIT_TRACE_PACKFILE` below).
606 See `GIT_TRACE` for available trace output options.
eb9250df 607
eee7f4a2 608`GIT_TRACE_PACKFILE`::
32359838
JK
609 Enables tracing of packfiles sent or received by a
610 given program. Unlike other trace output, this trace is
611 verbatim: no headers, and no quoting of binary data. You almost
612 certainly want to direct into a file (e.g.,
613 `GIT_TRACE_PACKFILE=/tmp/my.pack`) rather than displaying it on
614 the terminal or mixing it with other trace output.
615+
616Note that this is currently only implemented for the client side
617of clones and fetches.
618
eee7f4a2 619`GIT_TRACE_PERFORMANCE`::
578da039
KB
620 Enables performance related trace messages, e.g. total execution
621 time of each Git command.
eee7f4a2 622 See `GIT_TRACE` for available trace output options.
578da039 623
eee7f4a2 624`GIT_TRACE_SETUP`::
eb9250df
KB
625 Enables trace messages printing the .git, working tree and current
626 working directory after Git has completed its setup phase.
eee7f4a2 627 See `GIT_TRACE` for available trace output options.
eb9250df 628
eee7f4a2 629`GIT_TRACE_SHALLOW`::
eb9250df
KB
630 Enables trace messages that can help debugging fetching /
631 cloning of shallow repositories.
eee7f4a2 632 See `GIT_TRACE` for available trace output options.
1dd278ce 633
2f84df2c 634`GIT_TRACE_CURL`::
74c682d3
EP
635 Enables a curl full trace dump of all incoming and outgoing data,
636 including descriptive information, of the git transport protocol.
2f84df2c
JH
637 This is similar to doing curl `--trace-ascii` on the command line.
638 This option overrides setting the `GIT_CURL_VERBOSE` environment
74c682d3 639 variable.
2f84df2c 640 See `GIT_TRACE` for available trace output options.
74c682d3 641
eee7f4a2 642`GIT_LITERAL_PATHSPECS`::
2de9b711 643 Setting this variable to `1` will cause Git to treat all
823ab40f
JK
644 pathspecs literally, rather than as glob patterns. For example,
645 running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search
646 for commits that touch the path `*.c`, not any paths that the
647 glob `*.c` matches. You might want this if you are feeding
2de9b711 648 literal paths to Git (e.g., paths previously given to you by
823ab40f
JK
649 `git ls-tree`, `--raw` diff output, etc).
650
eee7f4a2 651`GIT_GLOB_PATHSPECS`::
bd30c2e4
NTND
652 Setting this variable to `1` will cause Git to treat all
653 pathspecs as glob patterns (aka "glob" magic).
654
eee7f4a2 655`GIT_NOGLOB_PATHSPECS`::
bd30c2e4
NTND
656 Setting this variable to `1` will cause Git to treat all
657 pathspecs as literal (aka "literal" magic).
658
eee7f4a2 659`GIT_ICASE_PATHSPECS`::
93d93537
NTND
660 Setting this variable to `1` will cause Git to treat all
661 pathspecs as case-insensitive.
662
eee7f4a2 663`GIT_REFLOG_ACTION`::
c3e2d189
JH
664 When a ref is updated, reflog entries are created to keep
665 track of the reason why the ref was updated (which is
666 typically the name of the high-level command that updated
667 the ref), in addition to the old and new values of the ref.
668 A scripted Porcelain command can use set_reflog_action
669 helper function in `git-sh-setup` to set its name to this
670 variable when it is invoked as the top level command by the
671 end user, to be recorded in the body of the reflog.
672
eee7f4a2 673`GIT_REF_PARANOIA`::
49672f26
JK
674 If set to `1`, include broken or badly named refs when iterating
675 over lists of refs. In a normal, non-corrupted repository, this
676 does nothing. However, enabling it may help git to detect and
677 abort some operations in the presence of broken refs. Git sets
678 this variable automatically when performing destructive
679 operations like linkgit:git-prune[1]. You should not need to set
680 it yourself unless you want to be paranoid about making sure
681 an operation has touched every ref (e.g., because you are
682 cloning a repository to make a backup).
683
eee7f4a2 684`GIT_ALLOW_PROTOCOL`::
f1762d77
BW
685 If set to a colon-separated list of protocols, behave as if
686 `protocol.allow` is set to `never`, and each of the listed
687 protocols has `protocol.<name>.allow` set to `always`
688 (overriding any existing configuration). In other words, any
689 protocol not mentioned will be disallowed (i.e., this is a
690 whitelist, not a blacklist). See the description of
691 `protocol.allow` in linkgit:git-config[1] for more details.
692
693`GIT_PROTOCOL_FROM_USER`::
694 Set to 0 to prevent protocols used by fetch/push/clone which are
695 configured to the `user` state. This is useful to restrict recursive
696 submodule initialization from an untrusted repository or for programs
697 which feed potentially-untrusted URLS to git commands. See
698 linkgit:git-config[1] for more details.
823ab40f 699
8db9307c
JH
700Discussion[[Discussion]]
701------------------------
40dac517
BF
702
703More detail on the following is available from the
2de9b711 704link:user-manual.html#git-concepts[Git concepts chapter of the
6998e4db 705user-manual] and linkgit:gitcore-tutorial[7].
40dac517 706
2de9b711 707A Git project normally consists of a working directory with a ".git"
40dac517
BF
708subdirectory at the top level. The .git directory contains, among other
709things, a compressed object database representing the complete history
710of the project, an "index" file which links that history to the current
711contents of the working tree, and named pointers into that history such
712as tags and branch heads.
713
714The object database contains objects of three main types: blobs, which
715hold file data; trees, which point to blobs and other trees to build up
02ff6250 716directory hierarchies; and commits, which each reference a single tree
40dac517
BF
717and some number of parent commits.
718
719The commit, equivalent to what other systems call a "changeset" or
720"version", represents a step in the project's history, and each parent
721represents an immediately preceding step. Commits with more than one
722parent represent merges of independent lines of development.
723
d5fa1f1a 724All objects are named by the SHA-1 hash of their contents, normally
40dac517
BF
725written as a string of 40 hex digits. Such names are globally unique.
726The entire history leading up to a commit can be vouched for by signing
727just that commit. A fourth object type, the tag, is provided for this
728purpose.
729
730When first created, objects are stored in individual files, but for
731efficiency may later be compressed together into "pack files".
732
733Named pointers called refs mark interesting points in history. A ref
d5fa1f1a
TA
734may contain the SHA-1 name of an object or the name of another ref. Refs
735with names beginning `ref/head/` contain the SHA-1 name of the most
736recent commit (or "head") of a branch under development. SHA-1 names of
40dac517
BF
737tags of interest are stored under `ref/tags/`. A special ref named
738`HEAD` contains the name of the currently checked-out branch.
739
740The index file is initialized with a list of all paths and, for each
741path, a blob object and a set of attributes. The blob object represents
742the contents of the file as of the head of the current branch. The
743attributes (last modified time, size, etc.) are taken from the
744corresponding file in the working tree. Subsequent changes to the
745working tree can be found by comparing these attributes. The index may
746be updated with new content, and new commits may be created from the
747content stored in the index.
748
749The index is also capable of storing multiple entries (called "stages")
750for a given pathname. These stages are used to hold the various
751unmerged version of a file when a merge is in progress.
6c84e2e0 752
7687ae98
JH
753FURTHER DOCUMENTATION
754---------------------
755
756See the references in the "description" section to get started
2de9b711 757using Git. The following is probably more detail than necessary
7687ae98
JH
758for a first-time user.
759
2de9b711 760The link:user-manual.html#git-concepts[Git concepts chapter of the
7687ae98 761user-manual] and linkgit:gitcore-tutorial[7] both provide
2de9b711 762introductions to the underlying Git architecture.
7687ae98
JH
763
764See linkgit:gitworkflows[7] for an overview of recommended workflows.
765
766See also the link:howto-index.html[howto] documents for some useful
767examples.
768
769The internals are documented in the
48a8c26c 770link:technical/api-index.html[Git API documentation].
7687ae98
JH
771
772Users migrating from CVS may also want to
773read linkgit:gitcvs-migration[7].
774
775
cb22bc44
AE
776Authors
777-------
48bb914e 778Git was started by Linus Torvalds, and is currently maintained by Junio
2de9b711 779C Hamano. Numerous contributions have come from the Git mailing list
405869d0 780<git@vger.kernel.org>. http://www.openhub.net/p/git/contributors/summary
6ecc01f2
JH
781gives you a more complete list of contributors.
782
783If you have a clone of git.git itself, the
d8f708f8
JK
784output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you
785the authors for specific parts of the project.
2cf565c5 786
c97ca277
JH
787Reporting Bugs
788--------------
789
790Report bugs to the Git mailing list <git@vger.kernel.org> where the
791development and maintenance is primarily done. You do not have to be
792subscribed to the list to send a message there.
793
497c8331
CC
794SEE ALSO
795--------
796linkgit:gittutorial[7], linkgit:gittutorial-2[7],
673151a9 797linkgit:giteveryday[7], linkgit:gitcvs-migration[7],
497c8331 798linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
801a011d
TR
799linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],
800linkgit:gitworkflows[7]
497c8331 801
2cf565c5
DG
802GIT
803---
9e1f0a85 804Part of the linkgit:git[1] suite