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