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