The second batch post 2.26 cycle
[git.git] / Documentation / git.txt
blob9d6769e95ab1d356e6c8b07671ac11446a2acc96
1 git(1)
2 ======
4 NAME
5 ----
6 git - the stupid content tracker
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>]
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.
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.
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.
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.
40 OPTIONS
41 -------
42 --version::
43         Prints the Git suite version that the 'git' program came from.
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.
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 ...`.
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.
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:
68     git --git-dir=a.git --work-tree=b -C c status
69     git --git-dir=c/a.git --work-tree=c/b status
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).
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`.
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.
89 --html-path::
90         Print the path, without trailing slash, where Git's HTML
91         documentation is installed and exit.
93 --man-path::
94         Print the manpath (see `man(1)`) for the man pages for
95         this version of Git and exit.
97 --info-path::
98         Print the path where the Info files documenting this
99         version of Git are installed and exit.
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).
108 -P::
109 --no-pager::
110         Do not pipe Git output into a pager.
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.
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)
128 If you just want to run git as if it was started in `<path>` then use
129 `git -C <path>`.
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).
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.
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.
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.
154 --no-replace-objects::
155         Do not use replacement refs to replace Git objects. See
156         linkgit:git-replace[1] for more information.
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`.
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)"
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)"
175 --icase-pathspecs::
176         Add "icase" magic to all pathspec. This is equivalent to setting
177         the `GIT_ICASE_PATHSPECS` environment variable to `1`.
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`.
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)
193 GIT COMMANDS
194 ------------
196 We divide Git into high level ("porcelain") commands and low level
197 ("plumbing") commands.
199 High-level commands (porcelain)
200 -------------------------------
202 We separate the porcelain commands into the main commands and some
203 ancillary user utilities.
205 Main porcelain commands
206 ~~~~~~~~~~~~~~~~~~~~~~~
208 include::cmds-mainporcelain.txt[]
210 Ancillary Commands
211 ~~~~~~~~~~~~~~~~~~
212 Manipulators:
214 include::cmds-ancillarymanipulators.txt[]
216 Interrogators:
218 include::cmds-ancillaryinterrogators.txt[]
221 Interacting with Others
222 ~~~~~~~~~~~~~~~~~~~~~~~
224 These commands are to interact with foreign SCM and with other
225 people via patch over e-mail.
227 include::cmds-foreignscminterface.txt[]
229 Reset, restore and revert
230 ~~~~~~~~~~~~~~~~~~~~~~~~~
231 There are three commands with similar names: `git reset`,
232 `git restore` and `git revert`.
234 * linkgit:git-revert[1] is about making a new commit that reverts the
235   changes made by other commits.
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.
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.
246 `git reset` can also be used to restore the index, overlapping with
247 `git restore`.
250 Low-level commands (plumbing)
251 -----------------------------
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].
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.
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.
273 Manipulation commands
274 ~~~~~~~~~~~~~~~~~~~~~
276 include::cmds-plumbingmanipulators.txt[]
279 Interrogation commands
280 ~~~~~~~~~~~~~~~~~~~~~~
282 include::cmds-plumbinginterrogators.txt[]
284 In general, the interrogate commands do not touch the files in
285 the working tree.
288 Syncing repositories
289 ~~~~~~~~~~~~~~~~~~~~
291 include::cmds-synchingrepositories.txt[]
293 The following are helper commands used by the above; end users
294 typically do not use them directly.
296 include::cmds-synchelpers.txt[]
299 Internal helper commands
300 ~~~~~~~~~~~~~~~~~~~~~~~~
302 These are internal helper commands used by other commands; end
303 users typically do not use them directly.
305 include::cmds-purehelpers.txt[]
308 Configuration Mechanism
309 -----------------------
311 Git uses a simple text format to store customizations that are per
312 repository and are per user.  Such a configuration file may look
313 like this:
315 ------------
317 # A '#' or ';' character indicates a comment.
320 ; core variables
321 [core]
322         ; Don't trust file modes
323         filemode = false
325 ; user identity
326 [user]
327         name = "Junio C Hamano"
328         email = "gitster@pobox.com"
330 ------------
332 Various commands read from the configuration file and adjust
333 their operation accordingly.  See linkgit:git-config[1] for a
334 list and more details about the configuration mechanism.
337 Identifier Terminology
338 ----------------------
339 <object>::
340         Indicates the object name for any type of object.
342 <blob>::
343         Indicates a blob object name.
345 <tree>::
346         Indicates a tree object name.
348 <commit>::
349         Indicates a commit object name.
351 <tree-ish>::
352         Indicates a tree, commit or tag object name.  A
353         command that takes a <tree-ish> argument ultimately wants to
354         operate on a <tree> object but automatically dereferences
355         <commit> and <tag> objects that point at a <tree>.
357 <commit-ish>::
358         Indicates a commit or tag object name.  A
359         command that takes a <commit-ish> argument ultimately wants to
360         operate on a <commit> object but automatically dereferences
361         <tag> objects that point at a <commit>.
363 <type>::
364         Indicates that an object type is required.
365         Currently one of: `blob`, `tree`, `commit`, or `tag`.
367 <file>::
368         Indicates a filename - almost always relative to the
369         root of the tree structure `GIT_INDEX_FILE` describes.
371 Symbolic Identifiers
372 --------------------
373 Any Git command accepting any <object> can also use the following
374 symbolic notation:
376 HEAD::
377         indicates the head of the current branch.
379 <tag>::
380         a valid tag 'name'
381         (i.e. a `refs/tags/<tag>` reference).
383 <head>::
384         a valid head 'name'
385         (i.e. a `refs/heads/<head>` reference).
387 For a more complete list of ways to spell object names, see
388 "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
391 File/Directory Structure
392 ------------------------
394 Please see the linkgit:gitrepository-layout[5] document.
396 Read linkgit:githooks[5] for more details about each hook.
398 Higher level SCMs may provide and manage additional information in the
399 `$GIT_DIR`.
402 Terminology
403 -----------
404 Please see linkgit:gitglossary[7].
407 Environment Variables
408 ---------------------
409 Various Git commands use the following environment variables:
411 The Git Repository
412 ~~~~~~~~~~~~~~~~~~
413 These environment variables apply to 'all' core Git commands. Nb: it
414 is worth noting that they may be used/overridden by SCMS sitting above
415 Git so take care if using a foreign front-end.
417 `GIT_INDEX_FILE`::
418         This environment allows the specification of an alternate
419         index file. If not specified, the default of `$GIT_DIR/index`
420         is used.
422 `GIT_INDEX_VERSION`::
423         This environment variable allows the specification of an index
424         version for new repositories.  It won't affect existing index
425         files.  By default index file version 2 or 3 is used. See
426         linkgit:git-update-index[1] for more information.
428 `GIT_OBJECT_DIRECTORY`::
429         If the object storage directory is specified via this
430         environment variable then the sha1 directories are created
431         underneath - otherwise the default `$GIT_DIR/objects`
432         directory is used.
434 `GIT_ALTERNATE_OBJECT_DIRECTORIES`::
435         Due to the immutable nature of Git objects, old objects can be
436         archived into shared, read-only directories. This variable
437         specifies a ":" separated (on Windows ";" separated) list
438         of Git object directories which can be used to search for Git
439         objects. New objects will not be written to these directories.
441 Entries that begin with `"` (double-quote) will be interpreted
442 as C-style quoted paths, removing leading and trailing
443 double-quotes and respecting backslash escapes. E.g., the value
444 `"path-with-\"-and-:-in-it":vanilla-path` has two paths:
445 `path-with-"-and-:-in-it` and `vanilla-path`.
447 `GIT_DIR`::
448         If the `GIT_DIR` environment variable is set then it
449         specifies a path to use instead of the default `.git`
450         for the base of the repository.
451         The `--git-dir` command-line option also sets this value.
453 `GIT_WORK_TREE`::
454         Set the path to the root of the working tree.
455         This can also be controlled by the `--work-tree` command-line
456         option and the core.worktree configuration variable.
458 `GIT_NAMESPACE`::
459         Set the Git namespace; see linkgit:gitnamespaces[7] for details.
460         The `--namespace` command-line option also sets this value.
462 `GIT_CEILING_DIRECTORIES`::
463         This should be a colon-separated list of absolute paths.  If
464         set, it is a list of directories that Git should not chdir up
465         into while looking for a repository directory (useful for
466         excluding slow-loading network directories).  It will not
467         exclude the current working directory or a GIT_DIR set on the
468         command line or in the environment.  Normally, Git has to read
469         the entries in this list and resolve any symlink that
470         might be present in order to compare them with the current
471         directory.  However, if even this access is slow, you
472         can add an empty entry to the list to tell Git that the
473         subsequent entries are not symlinks and needn't be resolved;
474         e.g.,
475         `GIT_CEILING_DIRECTORIES=/maybe/symlink::/very/slow/non/symlink`.
477 `GIT_DISCOVERY_ACROSS_FILESYSTEM`::
478         When run in a directory that does not have ".git" repository
479         directory, Git tries to find such a directory in the parent
480         directories to find the top of the working tree, but by default it
481         does not cross filesystem boundaries.  This environment variable
482         can be set to true to tell Git not to stop at filesystem
483         boundaries.  Like `GIT_CEILING_DIRECTORIES`, this will not affect
484         an explicit repository directory set via `GIT_DIR` or on the
485         command line.
487 `GIT_COMMON_DIR`::
488         If this variable is set to a path, non-worktree files that are
489         normally in $GIT_DIR will be taken from this path
490         instead. Worktree-specific files such as HEAD or index are
491         taken from $GIT_DIR. See linkgit:gitrepository-layout[5] and
492         linkgit:git-worktree[1] for
493         details. This variable has lower precedence than other path
494         variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY...
496 `GIT_DEFAULT_HASH_ALGORITHM`::
497         If this variable is set, the default hash algorithm for new
498         repositories will be set to this value. This value is currently
499         ignored when cloning; the setting of the remote repository
500         is used instead. The default is "sha1".
502 Git Commits
503 ~~~~~~~~~~~
504 `GIT_AUTHOR_NAME`::
505         The human-readable name used in the author identity when creating commit or
506         tag objects, or when writing reflogs. Overrides the `user.name` and
507         `author.name` configuration settings.
509 `GIT_AUTHOR_EMAIL`::
510         The email address used in the author identity when creating commit or
511         tag objects, or when writing reflogs. Overrides the `user.email` and
512         `author.email` configuration settings.
514 `GIT_AUTHOR_DATE`::
515         The date used for the author identity when creating commit or tag objects, or
516         when writing reflogs. See linkgit:git-commit[1] for valid formats.
518 `GIT_COMMITTER_NAME`::
519         The human-readable name used in the committer identity when creating commit or
520         tag objects, or when writing reflogs. Overrides the `user.name` and
521         `committer.name` configuration settings.
523 `GIT_COMMITTER_EMAIL`::
524         The email address used in the author identity when creating commit or
525         tag objects, or when writing reflogs. Overrides the `user.email` and
526         `committer.email` configuration settings.
528 `GIT_COMMITTER_DATE`::
529         The date used for the committer identity when creating commit or tag objects, or
530         when writing reflogs. See linkgit:git-commit[1] for valid formats.
532 `EMAIL`::
533         The email address used in the author and committer identities if no other
534         relevant environment variable or configuration setting has been set.
536 Git Diffs
537 ~~~~~~~~~
538 `GIT_DIFF_OPTS`::
539         Only valid setting is "--unified=??" or "-u??" to set the
540         number of context lines shown when a unified diff is created.
541         This takes precedence over any "-U" or "--unified" option
542         value passed on the Git diff command line.
544 `GIT_EXTERNAL_DIFF`::
545         When the environment variable `GIT_EXTERNAL_DIFF` is set, the
546         program named by it is called, instead of the diff invocation
547         described above.  For a path that is added, removed, or modified,
548         `GIT_EXTERNAL_DIFF` is called with 7 parameters:
550         path old-file old-hex old-mode new-file new-hex new-mode
552 where:
554         <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
555                          contents of <old|new>,
556         <old|new>-hex:: are the 40-hexdigit SHA-1 hashes,
557         <old|new>-mode:: are the octal representation of the file modes.
559 The file parameters can point at the user's working file
560 (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
561 when a new file is added), or a temporary file (e.g. `old-file` in the
562 index).  `GIT_EXTERNAL_DIFF` should not worry about unlinking the
563 temporary file --- it is removed when `GIT_EXTERNAL_DIFF` exits.
565 For a path that is unmerged, `GIT_EXTERNAL_DIFF` is called with 1
566 parameter, <path>.
568 For each path `GIT_EXTERNAL_DIFF` is called, two environment variables,
569 `GIT_DIFF_PATH_COUNTER` and `GIT_DIFF_PATH_TOTAL` are set.
571 `GIT_DIFF_PATH_COUNTER`::
572         A 1-based counter incremented by one for every path.
574 `GIT_DIFF_PATH_TOTAL`::
575         The total number of paths.
577 other
578 ~~~~~
579 `GIT_MERGE_VERBOSITY`::
580         A number controlling the amount of output shown by
581         the recursive merge strategy.  Overrides merge.verbosity.
582         See linkgit:git-merge[1]
584 `GIT_PAGER`::
585         This environment variable overrides `$PAGER`. If it is set
586         to an empty string or to the value "cat", Git will not launch
587         a pager.  See also the `core.pager` option in
588         linkgit:git-config[1].
590 `GIT_PROGRESS_DELAY`::
591         A number controlling how many seconds to delay before showing
592         optional progress indicators. Defaults to 2.
594 `GIT_EDITOR`::
595         This environment variable overrides `$EDITOR` and `$VISUAL`.
596         It is used by several Git commands when, on interactive mode,
597         an editor is to be launched. See also linkgit:git-var[1]
598         and the `core.editor` option in linkgit:git-config[1].
600 `GIT_SSH`::
601 `GIT_SSH_COMMAND`::
602         If either of these environment variables is set then 'git fetch'
603         and 'git push' will use the specified command instead of 'ssh'
604         when they need to connect to a remote system.
605         The command-line parameters passed to the configured command are
606         determined by the ssh variant.  See `ssh.variant` option in
607         linkgit:git-config[1] for details.
609 `$GIT_SSH_COMMAND` takes precedence over `$GIT_SSH`, and is interpreted
610 by the shell, which allows additional arguments to be included.
611 `$GIT_SSH` on the other hand must be just the path to a program
612 (which can be a wrapper shell script, if additional arguments are
613 needed).
615 Usually it is easier to configure any desired options through your
616 personal `.ssh/config` file.  Please consult your ssh documentation
617 for further details.
619 `GIT_SSH_VARIANT`::
620         If this environment variable is set, it overrides Git's autodetection
621         whether `GIT_SSH`/`GIT_SSH_COMMAND`/`core.sshCommand` refer to OpenSSH,
622         plink or tortoiseplink. This variable overrides the config setting
623         `ssh.variant` that serves the same purpose.
625 `GIT_ASKPASS`::
626         If this environment variable is set, then Git commands which need to
627         acquire passwords or passphrases (e.g. for HTTP or IMAP authentication)
628         will call this program with a suitable prompt as command-line argument
629         and read the password from its STDOUT. See also the `core.askPass`
630         option in linkgit:git-config[1].
632 `GIT_TERMINAL_PROMPT`::
633         If this environment variable is set to `0`, git will not prompt
634         on the terminal (e.g., when asking for HTTP authentication).
636 `GIT_CONFIG_NOSYSTEM`::
637         Whether to skip reading settings from the system-wide
638         `$(prefix)/etc/gitconfig` file.  This environment variable can
639         be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a
640         predictable environment for a picky script, or you can set it
641         temporarily to avoid using a buggy `/etc/gitconfig` file while
642         waiting for someone with sufficient permissions to fix it.
644 `GIT_FLUSH`::
645         If this environment variable is set to "1", then commands such
646         as 'git blame' (in incremental mode), 'git rev-list', 'git log',
647         'git check-attr' and 'git check-ignore' will
648         force a flush of the output stream after each record have been
649         flushed. If this
650         variable is set to "0", the output of these commands will be done
651         using completely buffered I/O.   If this environment variable is
652         not set, Git will choose buffered or record-oriented flushing
653         based on whether stdout appears to be redirected to a file or not.
655 `GIT_TRACE`::
656         Enables general trace messages, e.g. alias expansion, built-in
657         command execution and external command execution.
659 If this variable is set to "1", "2" or "true" (comparison
660 is case insensitive), trace messages will be printed to
661 stderr.
663 If the variable is set to an integer value greater than 2
664 and lower than 10 (strictly) then Git will interpret this
665 value as an open file descriptor and will try to write the
666 trace messages into this file descriptor.
668 Alternatively, if the variable is set to an absolute path
669 (starting with a '/' character), Git will interpret this
670 as a file path and will try to append the trace messages
671 to it.
673 Unsetting the variable, or setting it to empty, "0" or
674 "false" (case insensitive) disables trace messages.
676 `GIT_TRACE_FSMONITOR`::
677         Enables trace messages for the filesystem monitor extension.
678         See `GIT_TRACE` for available trace output options.
680 `GIT_TRACE_PACK_ACCESS`::
681         Enables trace messages for all accesses to any packs. For each
682         access, the pack file name and an offset in the pack is
683         recorded. This may be helpful for troubleshooting some
684         pack-related performance problems.
685         See `GIT_TRACE` for available trace output options.
687 `GIT_TRACE_PACKET`::
688         Enables trace messages for all packets coming in or out of a
689         given program. This can help with debugging object negotiation
690         or other protocol issues. Tracing is turned off at a packet
691         starting with "PACK" (but see `GIT_TRACE_PACKFILE` below).
692         See `GIT_TRACE` for available trace output options.
694 `GIT_TRACE_PACKFILE`::
695         Enables tracing of packfiles sent or received by a
696         given program. Unlike other trace output, this trace is
697         verbatim: no headers, and no quoting of binary data. You almost
698         certainly want to direct into a file (e.g.,
699         `GIT_TRACE_PACKFILE=/tmp/my.pack`) rather than displaying it on
700         the terminal or mixing it with other trace output.
702 Note that this is currently only implemented for the client side
703 of clones and fetches.
705 `GIT_TRACE_PERFORMANCE`::
706         Enables performance related trace messages, e.g. total execution
707         time of each Git command.
708         See `GIT_TRACE` for available trace output options.
710 `GIT_TRACE_SETUP`::
711         Enables trace messages printing the .git, working tree and current
712         working directory after Git has completed its setup phase.
713         See `GIT_TRACE` for available trace output options.
715 `GIT_TRACE_SHALLOW`::
716         Enables trace messages that can help debugging fetching /
717         cloning of shallow repositories.
718         See `GIT_TRACE` for available trace output options.
720 `GIT_TRACE_CURL`::
721         Enables a curl full trace dump of all incoming and outgoing data,
722         including descriptive information, of the git transport protocol.
723         This is similar to doing curl `--trace-ascii` on the command line.
724         This option overrides setting the `GIT_CURL_VERBOSE` environment
725         variable.
726         See `GIT_TRACE` for available trace output options.
728 `GIT_TRACE_CURL_NO_DATA`::
729         When a curl trace is enabled (see `GIT_TRACE_CURL` above), do not dump
730         data (that is, only dump info lines and headers).
732 `GIT_TRACE2`::
733         Enables more detailed trace messages from the "trace2" library.
734         Output from `GIT_TRACE2` is a simple text-based format for human
735         readability.
737 If this variable is set to "1", "2" or "true" (comparison
738 is case insensitive), trace messages will be printed to
739 stderr.
741 If the variable is set to an integer value greater than 2
742 and lower than 10 (strictly) then Git will interpret this
743 value as an open file descriptor and will try to write the
744 trace messages into this file descriptor.
746 Alternatively, if the variable is set to an absolute path
747 (starting with a '/' character), Git will interpret this
748 as a file path and will try to append the trace messages
749 to it.  If the path already exists and is a directory, the
750 trace messages will be written to files (one per process)
751 in that directory, named according to the last component
752 of the SID and an optional counter (to avoid filename
753 collisions).
755 In addition, if the variable is set to
756 `af_unix:[<socket_type>:]<absolute-pathname>`, Git will try
757 to open the path as a Unix Domain Socket.  The socket type
758 can be either `stream` or `dgram`.
760 Unsetting the variable, or setting it to empty, "0" or
761 "false" (case insensitive) disables trace messages.
763 See link:technical/api-trace2.html[Trace2 documentation]
764 for full details.
767 `GIT_TRACE2_EVENT`::
768         This setting writes a JSON-based format that is suited for machine
769         interpretation.
770         See `GIT_TRACE2` for available trace output options and
771         link:technical/api-trace2.html[Trace2 documentation] for full details.
773 `GIT_TRACE2_PERF`::
774         In addition to the text-based messages available in `GIT_TRACE2`, this
775         setting writes a column-based format for understanding nesting
776         regions.
777         See `GIT_TRACE2` for available trace output options and
778         link:technical/api-trace2.html[Trace2 documentation] for full details.
780 `GIT_REDACT_COOKIES`::
781         This can be set to a comma-separated list of strings. When a curl trace
782         is enabled (see `GIT_TRACE_CURL` above), whenever a "Cookies:" header
783         sent by the client is dumped, values of cookies whose key is in that
784         list (case-sensitive) are redacted.
786 `GIT_LITERAL_PATHSPECS`::
787         Setting this variable to `1` will cause Git to treat all
788         pathspecs literally, rather than as glob patterns. For example,
789         running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search
790         for commits that touch the path `*.c`, not any paths that the
791         glob `*.c` matches. You might want this if you are feeding
792         literal paths to Git (e.g., paths previously given to you by
793         `git ls-tree`, `--raw` diff output, etc).
795 `GIT_GLOB_PATHSPECS`::
796         Setting this variable to `1` will cause Git to treat all
797         pathspecs as glob patterns (aka "glob" magic).
799 `GIT_NOGLOB_PATHSPECS`::
800         Setting this variable to `1` will cause Git to treat all
801         pathspecs as literal (aka "literal" magic).
803 `GIT_ICASE_PATHSPECS`::
804         Setting this variable to `1` will cause Git to treat all
805         pathspecs as case-insensitive.
807 `GIT_REFLOG_ACTION`::
808         When a ref is updated, reflog entries are created to keep
809         track of the reason why the ref was updated (which is
810         typically the name of the high-level command that updated
811         the ref), in addition to the old and new values of the ref.
812         A scripted Porcelain command can use set_reflog_action
813         helper function in `git-sh-setup` to set its name to this
814         variable when it is invoked as the top level command by the
815         end user, to be recorded in the body of the reflog.
817 `GIT_REF_PARANOIA`::
818         If set to `1`, include broken or badly named refs when iterating
819         over lists of refs. In a normal, non-corrupted repository, this
820         does nothing. However, enabling it may help git to detect and
821         abort some operations in the presence of broken refs. Git sets
822         this variable automatically when performing destructive
823         operations like linkgit:git-prune[1]. You should not need to set
824         it yourself unless you want to be paranoid about making sure
825         an operation has touched every ref (e.g., because you are
826         cloning a repository to make a backup).
828 `GIT_ALLOW_PROTOCOL`::
829         If set to a colon-separated list of protocols, behave as if
830         `protocol.allow` is set to `never`, and each of the listed
831         protocols has `protocol.<name>.allow` set to `always`
832         (overriding any existing configuration). In other words, any
833         protocol not mentioned will be disallowed (i.e., this is a
834         whitelist, not a blacklist). See the description of
835         `protocol.allow` in linkgit:git-config[1] for more details.
837 `GIT_PROTOCOL_FROM_USER`::
838         Set to 0 to prevent protocols used by fetch/push/clone which are
839         configured to the `user` state.  This is useful to restrict recursive
840         submodule initialization from an untrusted repository or for programs
841         which feed potentially-untrusted URLS to git commands.  See
842         linkgit:git-config[1] for more details.
844 `GIT_PROTOCOL`::
845         For internal use only.  Used in handshaking the wire protocol.
846         Contains a colon ':' separated list of keys with optional values
847         'key[=value]'.  Presence of unknown keys and values must be
848         ignored.
850 `GIT_OPTIONAL_LOCKS`::
851         If set to `0`, Git will complete any requested operation without
852         performing any optional sub-operations that require taking a lock.
853         For example, this will prevent `git status` from refreshing the
854         index as a side effect. This is useful for processes running in
855         the background which do not want to cause lock contention with
856         other operations on the repository.  Defaults to `1`.
858 `GIT_REDIRECT_STDIN`::
859 `GIT_REDIRECT_STDOUT`::
860 `GIT_REDIRECT_STDERR`::
861         Windows-only: allow redirecting the standard input/output/error
862         handles to paths specified by the environment variables. This is
863         particularly useful in multi-threaded applications where the
864         canonical way to pass standard handles via `CreateProcess()` is
865         not an option because it would require the handles to be marked
866         inheritable (and consequently *every* spawned process would
867         inherit them, possibly blocking regular Git operations). The
868         primary intended use case is to use named pipes for communication
869         (e.g. `\\.\pipe\my-git-stdin-123`).
871 Two special values are supported: `off` will simply close the
872 corresponding standard handle, and if `GIT_REDIRECT_STDERR` is
873 `2>&1`, standard error will be redirected to the same handle as
874 standard output.
876 `GIT_PRINT_SHA1_ELLIPSIS` (deprecated)::
877         If set to `yes`, print an ellipsis following an
878         (abbreviated) SHA-1 value.  This affects indications of
879         detached HEADs (linkgit:git-checkout[1]) and the raw
880         diff output (linkgit:git-diff[1]).  Printing an
881         ellipsis in the cases mentioned is no longer considered
882         adequate and support for it is likely to be removed in the
883         foreseeable future (along with the variable).
885 Discussion[[Discussion]]
886 ------------------------
888 More detail on the following is available from the
889 link:user-manual.html#git-concepts[Git concepts chapter of the
890 user-manual] and linkgit:gitcore-tutorial[7].
892 A Git project normally consists of a working directory with a ".git"
893 subdirectory at the top level.  The .git directory contains, among other
894 things, a compressed object database representing the complete history
895 of the project, an "index" file which links that history to the current
896 contents of the working tree, and named pointers into that history such
897 as tags and branch heads.
899 The object database contains objects of three main types: blobs, which
900 hold file data; trees, which point to blobs and other trees to build up
901 directory hierarchies; and commits, which each reference a single tree
902 and some number of parent commits.
904 The commit, equivalent to what other systems call a "changeset" or
905 "version", represents a step in the project's history, and each parent
906 represents an immediately preceding step.  Commits with more than one
907 parent represent merges of independent lines of development.
909 All objects are named by the SHA-1 hash of their contents, normally
910 written as a string of 40 hex digits.  Such names are globally unique.
911 The entire history leading up to a commit can be vouched for by signing
912 just that commit.  A fourth object type, the tag, is provided for this
913 purpose.
915 When first created, objects are stored in individual files, but for
916 efficiency may later be compressed together into "pack files".
918 Named pointers called refs mark interesting points in history.  A ref
919 may contain the SHA-1 name of an object or the name of another ref.  Refs
920 with names beginning `ref/head/` contain the SHA-1 name of the most
921 recent commit (or "head") of a branch under development.  SHA-1 names of
922 tags of interest are stored under `ref/tags/`.  A special ref named
923 `HEAD` contains the name of the currently checked-out branch.
925 The index file is initialized with a list of all paths and, for each
926 path, a blob object and a set of attributes.  The blob object represents
927 the contents of the file as of the head of the current branch.  The
928 attributes (last modified time, size, etc.) are taken from the
929 corresponding file in the working tree.  Subsequent changes to the
930 working tree can be found by comparing these attributes.  The index may
931 be updated with new content, and new commits may be created from the
932 content stored in the index.
934 The index is also capable of storing multiple entries (called "stages")
935 for a given pathname.  These stages are used to hold the various
936 unmerged version of a file when a merge is in progress.
938 FURTHER DOCUMENTATION
939 ---------------------
941 See the references in the "description" section to get started
942 using Git.  The following is probably more detail than necessary
943 for a first-time user.
945 The link:user-manual.html#git-concepts[Git concepts chapter of the
946 user-manual] and linkgit:gitcore-tutorial[7] both provide
947 introductions to the underlying Git architecture.
949 See linkgit:gitworkflows[7] for an overview of recommended workflows.
951 See also the link:howto-index.html[howto] documents for some useful
952 examples.
954 The internals are documented in the
955 link:technical/api-index.html[Git API documentation].
957 Users migrating from CVS may also want to
958 read linkgit:gitcvs-migration[7].
961 Authors
962 -------
963 Git was started by Linus Torvalds, and is currently maintained by Junio
964 C Hamano. Numerous contributions have come from the Git mailing list
965 <git@vger.kernel.org>.  http://www.openhub.net/p/git/contributors/summary
966 gives you a more complete list of contributors.
968 If you have a clone of git.git itself, the
969 output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you
970 the authors for specific parts of the project.
972 Reporting Bugs
973 --------------
975 Report bugs to the Git mailing list <git@vger.kernel.org> where the
976 development and maintenance is primarily done.  You do not have to be
977 subscribed to the list to send a message there.  See the list archive
978 at https://lore.kernel.org/git for previous bug reports and other
979 discussions.
981 Issues which are security relevant should be disclosed privately to
982 the Git Security mailing list <git-security@googlegroups.com>.
984 SEE ALSO
985 --------
986 linkgit:gittutorial[7], linkgit:gittutorial-2[7],
987 linkgit:giteveryday[7], linkgit:gitcvs-migration[7],
988 linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
989 linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],
990 linkgit:gitworkflows[7]
994 Part of the linkgit:git[1] suite