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