trace2: document the supported values of GIT_TRACE2* env variables
[git/git.git] / Documentation / git.txt
1 git(1)
2 ======
5 ----
6 git - the stupid content tracker
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>]
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 ``.
40 -------
41 --version::
42 Prints the Git suite version that the 'git' program came from.
44 --help::
45 Prints the synopsis and a list of the most commonly used
46 commands. If the option `--all` or `-a` is given then all
47 available commands are printed. If a Git command is named this
48 option will bring up the manual page for that command.
49 +
50 Other options are available to control how the manual page is
51 displayed. See linkgit:git-help[1] for more information,
52 because `git --help ...` is converted internally into `git
53 help ...`.
55 -C <path>::
56 Run as if git was started in '<path>' instead of the current working
57 directory. When multiple `-C` options are given, each subsequent
58 non-absolute `-C <path>` is interpreted relative to the preceding `-C
59 <path>`.
60 +
61 This option affects options that expect path name like `--git-dir` and
62 `--work-tree` in that their interpretations of the path names would be
63 made relative to the working directory caused by the `-C` option. For
64 example the following invocations are equivalent:
66 git --git-dir=a.git --work-tree=b -C c status
67 git --git-dir=c/a.git --work-tree=c/b status
69 -c <name>=<value>::
70 Pass a configuration parameter to the command. The value
71 given will override values from configuration files.
72 The <name> is expected in the same format as listed by
73 'git config' (subkeys separated by dots).
74 +
75 Note that omitting the `=` in `git -c ...` is allowed and sets
76 `` to the boolean true value (just like `[foo]bar` would in a
77 config file). Including the equals but with an empty value (like `git -c
78 ...`) sets `` to the empty string which `git config
79 --type=bool` will convert to `false`.
81 --exec-path[=<path>]::
82 Path to wherever your core Git programs are installed.
83 This can also be controlled by setting the GIT_EXEC_PATH
84 environment variable. If no path is given, 'git' will print
85 the current setting and then exit.
87 --html-path::
88 Print the path, without trailing slash, where Git's HTML
89 documentation is installed and exit.
91 --man-path::
92 Print the manpath (see `man(1)`) for the man pages for
93 this version of Git and exit.
95 --info-path::
96 Print the path where the Info files documenting this
97 version of Git are installed and exit.
99 -p::
100 --paginate::
101 Pipe all output into 'less' (or if set, $PAGER) if standard
102 output is a terminal. This overrides the `pager.<cmd>`
103 configuration options (see the "Configuration Mechanism" section
104 below).
106 -P::
107 --no-pager::
108 Do not pipe Git output into a pager.
110 --git-dir=<path>::
111 Set the path to the repository. This can also be controlled by
112 setting the `GIT_DIR` environment variable. It can be an absolute
113 path or relative path to current working directory.
115 --work-tree=<path>::
116 Set the path to the working tree. It can be an absolute path
117 or a path relative to the current working directory.
118 This can also be controlled by setting the GIT_WORK_TREE
119 environment variable and the core.worktree configuration
120 variable (see core.worktree in linkgit:git-config[1] for a
121 more detailed discussion).
123 --namespace=<path>::
124 Set the Git namespace. See linkgit:gitnamespaces[7] for more
125 details. Equivalent to setting the `GIT_NAMESPACE` environment
126 variable.
128 --super-prefix=<path>::
129 Currently for internal use only. Set a prefix which gives a path from
130 above a repository down to its root. One use is to give submodules
131 context about the superproject that invoked it.
133 --bare::
134 Treat the repository as a bare repository. If GIT_DIR
135 environment is not set, it is set to the current working
136 directory.
138 --no-replace-objects::
139 Do not use replacement refs to replace Git objects. See
140 linkgit:git-replace[1] for more information.
142 --literal-pathspecs::
143 Treat pathspecs literally (i.e. no globbing, no pathspec magic).
144 This is equivalent to setting the `GIT_LITERAL_PATHSPECS` environment
145 variable to `1`.
147 --glob-pathspecs::
148 Add "glob" magic to all pathspec. This is equivalent to setting
149 the `GIT_GLOB_PATHSPECS` environment variable to `1`. Disabling
150 globbing on individual pathspecs can be done using pathspec
151 magic ":(literal)"
153 --noglob-pathspecs::
154 Add "literal" magic to all pathspec. This is equivalent to setting
155 the `GIT_NOGLOB_PATHSPECS` environment variable to `1`. Enabling
156 globbing on individual pathspecs can be done using pathspec
157 magic ":(glob)"
159 --icase-pathspecs::
160 Add "icase" magic to all pathspec. This is equivalent to setting
161 the `GIT_ICASE_PATHSPECS` environment variable to `1`.
163 --no-optional-locks::
164 Do not perform optional operations that require locks. This is
165 equivalent to setting the `GIT_OPTIONAL_LOCKS` to `0`.
167 --list-cmds=group[,group...]::
168 List commands by group. This is an internal/experimental
169 option and may change or be removed in the future. Supported
170 groups are: builtins, parseopt (builtin commands that use
171 parse-options), main (all commands in libexec directory),
172 others (all other commands in `$PATH` that have git- prefix),
173 list-<category> (see categories in command-list.txt),
174 nohelpers (exclude helper commands), alias and config
175 (retrieve command list from config variable completion.commands)
178 ------------
180 We divide Git into high level ("porcelain") commands and low level
181 ("plumbing") commands.
183 High-level commands (porcelain)
184 -------------------------------
186 We separate the porcelain commands into the main commands and some
187 ancillary user utilities.
189 Main porcelain commands
190 ~~~~~~~~~~~~~~~~~~~~~~~
192 include::cmds-mainporcelain.txt[]
194 Ancillary Commands
195 ~~~~~~~~~~~~~~~~~~
196 Manipulators:
198 include::cmds-ancillarymanipulators.txt[]
200 Interrogators:
202 include::cmds-ancillaryinterrogators.txt[]
205 Interacting with Others
206 ~~~~~~~~~~~~~~~~~~~~~~~
208 These commands are to interact with foreign SCM and with other
209 people via patch over e-mail.
211 include::cmds-foreignscminterface.txt[]
214 Low-level commands (plumbing)
215 -----------------------------
217 Although Git includes its
218 own porcelain layer, its low-level commands are sufficient to support
219 development of alternative porcelains. Developers of such porcelains
220 might start by reading about linkgit:git-update-index[1] and
221 linkgit:git-read-tree[1].
223 The interface (input, output, set of options and the semantics)
224 to these low-level commands are meant to be a lot more stable
225 than Porcelain level commands, because these commands are
226 primarily for scripted use. The interface to Porcelain commands
227 on the other hand are subject to change in order to improve the
228 end user experience.
230 The following description divides
231 the low-level commands into commands that manipulate objects (in
232 the repository, index, and working tree), commands that interrogate and
233 compare objects, and commands that move objects and references between
234 repositories.
237 Manipulation commands
238 ~~~~~~~~~~~~~~~~~~~~~
240 include::cmds-plumbingmanipulators.txt[]
243 Interrogation commands
244 ~~~~~~~~~~~~~~~~~~~~~~
246 include::cmds-plumbinginterrogators.txt[]
248 In general, the interrogate commands do not touch the files in
249 the working tree.
252 Synching repositories
253 ~~~~~~~~~~~~~~~~~~~~~
255 include::cmds-synchingrepositories.txt[]
257 The following are helper commands used by the above; end users
258 typically do not use them directly.
260 include::cmds-synchelpers.txt[]
263 Internal helper commands
264 ~~~~~~~~~~~~~~~~~~~~~~~~
266 These are internal helper commands used by other commands; end
267 users typically do not use them directly.
269 include::cmds-purehelpers.txt[]
272 Configuration Mechanism
273 -----------------------
275 Git uses a simple text format to store customizations that are per
276 repository and are per user. Such a configuration file may look
277 like this:
279 ------------
280 #
281 # A '#' or ';' character indicates a comment.
282 #
284 ; core variables
285 [core]
286 ; Don't trust file modes
287 filemode = false
289 ; user identity
290 [user]
291 name = "Junio C Hamano"
292 email = ""
294 ------------
296 Various commands read from the configuration file and adjust
297 their operation accordingly. See linkgit:git-config[1] for a
298 list and more details about the configuration mechanism.
301 Identifier Terminology
302 ----------------------
303 <object>::
304 Indicates the object name for any type of object.
306 <blob>::
307 Indicates a blob object name.
309 <tree>::
310 Indicates a tree object name.
312 <commit>::
313 Indicates a commit object name.
315 <tree-ish>::
316 Indicates a tree, commit or tag object name. A
317 command that takes a <tree-ish> argument ultimately wants to
318 operate on a <tree> object but automatically dereferences
319 <commit> and <tag> objects that point at a <tree>.
321 <commit-ish>::
322 Indicates a commit or tag object name. A
323 command that takes a <commit-ish> argument ultimately wants to
324 operate on a <commit> object but automatically dereferences
325 <tag> objects that point at a <commit>.
327 <type>::
328 Indicates that an object type is required.
329 Currently one of: `blob`, `tree`, `commit`, or `tag`.
331 <file>::
332 Indicates a filename - almost always relative to the
333 root of the tree structure `GIT_INDEX_FILE` describes.
335 Symbolic Identifiers
336 --------------------
337 Any Git command accepting any <object> can also use the following
338 symbolic notation:
340 HEAD::
341 indicates the head of the current branch.
343 <tag>::
344 a valid tag 'name'
345 (i.e. a `refs/tags/<tag>` reference).
347 <head>::
348 a valid head 'name'
349 (i.e. a `refs/heads/<head>` reference).
351 For a more complete list of ways to spell object names, see
352 "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
355 File/Directory Structure
356 ------------------------
358 Please see the linkgit:gitrepository-layout[5] document.
360 Read linkgit:githooks[5] for more details about each hook.
362 Higher level SCMs may provide and manage additional information in the
363 `$GIT_DIR`.
366 Terminology
367 -----------
368 Please see linkgit:gitglossary[7].
371 Environment Variables
372 ---------------------
373 Various Git commands use the following environment variables:
375 The Git Repository
376 ~~~~~~~~~~~~~~~~~~
377 These environment variables apply to 'all' core Git commands. Nb: it
378 is worth noting that they may be used/overridden by SCMS sitting above
379 Git so take care if using a foreign front-end.
382 This environment allows the specification of an alternate
383 index file. If not specified, the default of `$GIT_DIR/index`
384 is used.
387 This environment variable allows the specification of an index
388 version for new repositories. It won't affect existing index
389 files. By default index file version 2 or 3 is used. See
390 linkgit:git-update-index[1] for more information.
393 If the object storage directory is specified via this
394 environment variable then the sha1 directories are created
395 underneath - otherwise the default `$GIT_DIR/objects`
396 directory is used.
399 Due to the immutable nature of Git objects, old objects can be
400 archived into shared, read-only directories. This variable
401 specifies a ":" separated (on Windows ";" separated) list
402 of Git object directories which can be used to search for Git
403 objects. New objects will not be written to these directories.
404 +
405 Entries that begin with `"` (double-quote) will be interpreted
406 as C-style quoted paths, removing leading and trailing
407 double-quotes and respecting backslash escapes. E.g., the value
408 `"path-with-\"-and-:-in-it":vanilla-path` has two paths:
409 `path-with-"-and-:-in-it` and `vanilla-path`.
411 `GIT_DIR`::
412 If the `GIT_DIR` environment variable is set then it
413 specifies a path to use instead of the default `.git`
414 for the base of the repository.
415 The `--git-dir` command-line option also sets this value.
418 Set the path to the root of the working tree.
419 This can also be controlled by the `--work-tree` command-line
420 option and the core.worktree configuration variable.
423 Set the Git namespace; see linkgit:gitnamespaces[7] for details.
424 The `--namespace` command-line option also sets this value.
427 This should be a colon-separated list of absolute paths. If
428 set, it is a list of directories that Git should not chdir up
429 into while looking for a repository directory (useful for
430 excluding slow-loading network directories). It will not
431 exclude the current working directory or a GIT_DIR set on the
432 command line or in the environment. Normally, Git has to read
433 the entries in this list and resolve any symlink that
434 might be present in order to compare them with the current
435 directory. However, if even this access is slow, you
436 can add an empty entry to the list to tell Git that the
437 subsequent entries are not symlinks and needn't be resolved;
438 e.g.,
439 `GIT_CEILING_DIRECTORIES=/maybe/symlink::/very/slow/non/symlink`.
442 When run in a directory that does not have ".git" repository
443 directory, Git tries to find such a directory in the parent
444 directories to find the top of the working tree, but by default it
445 does not cross filesystem boundaries. This environment variable
446 can be set to true to tell Git not to stop at filesystem
447 boundaries. Like `GIT_CEILING_DIRECTORIES`, this will not affect
448 an explicit repository directory set via `GIT_DIR` or on the
449 command line.
452 If this variable is set to a path, non-worktree files that are
453 normally in $GIT_DIR will be taken from this path
454 instead. Worktree-specific files such as HEAD or index are
455 taken from $GIT_DIR. See linkgit:gitrepository-layout[5] and
456 linkgit:git-worktree[1] for
457 details. This variable has lower precedence than other path
458 variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY...
460 Git Commits
461 ~~~~~~~~~~~
468 'EMAIL'::
469 see linkgit:git-commit-tree[1]
471 Git Diffs
472 ~~~~~~~~~
474 Only valid setting is "--unified=??" or "-u??" to set the
475 number of context lines shown when a unified diff is created.
476 This takes precedence over any "-U" or "--unified" option
477 value passed on the Git diff command line.
480 When the environment variable `GIT_EXTERNAL_DIFF` is set, the
481 program named by it is called, instead of the diff invocation
482 described above. For a path that is added, removed, or modified,
483 `GIT_EXTERNAL_DIFF` is called with 7 parameters:
485 path old-file old-hex old-mode new-file new-hex new-mode
486 +
487 where:
489 <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
490 contents of <old|new>,
491 <old|new>-hex:: are the 40-hexdigit SHA-1 hashes,
492 <old|new>-mode:: are the octal representation of the file modes.
493 +
494 The file parameters can point at the user's working file
495 (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
496 when a new file is added), or a temporary file (e.g. `old-file` in the
497 index). `GIT_EXTERNAL_DIFF` should not worry about unlinking the
498 temporary file --- it is removed when `GIT_EXTERNAL_DIFF` exits.
499 +
500 For a path that is unmerged, `GIT_EXTERNAL_DIFF` is called with 1
501 parameter, <path>.
502 +
503 For each path `GIT_EXTERNAL_DIFF` is called, two environment variables,
507 A 1-based counter incremented by one for every path.
510 The total number of paths.
512 other
513 ~~~~~
515 A number controlling the amount of output shown by
516 the recursive merge strategy. Overrides merge.verbosity.
517 See linkgit:git-merge[1]
519 `GIT_PAGER`::
520 This environment variable overrides `$PAGER`. If it is set
521 to an empty string or to the value "cat", Git will not launch
522 a pager. See also the `core.pager` option in
523 linkgit:git-config[1].
525 `GIT_EDITOR`::
526 This environment variable overrides `$EDITOR` and `$VISUAL`.
527 It is used by several Git commands when, on interactive mode,
528 an editor is to be launched. See also linkgit:git-var[1]
529 and the `core.editor` option in linkgit:git-config[1].
531 `GIT_SSH`::
533 If either of these environment variables is set then 'git fetch'
534 and 'git push' will use the specified command instead of 'ssh'
535 when they need to connect to a remote system.
536 The command-line parameters passed to the configured command are
537 determined by the ssh variant. See `ssh.variant` option in
538 linkgit:git-config[1] for details.
539 +
540 `$GIT_SSH_COMMAND` takes precedence over `$GIT_SSH`, and is interpreted
541 by the shell, which allows additional arguments to be included.
542 `$GIT_SSH` on the other hand must be just the path to a program
543 (which can be a wrapper shell script, if additional arguments are
544 needed).
545 +
546 Usually it is easier to configure any desired options through your
547 personal `.ssh/config` file. Please consult your ssh documentation
548 for further details.
551 If this environment variable is set, it overrides Git's autodetection
552 whether `GIT_SSH`/`GIT_SSH_COMMAND`/`core.sshCommand` refer to OpenSSH,
553 plink or tortoiseplink. This variable overrides the config setting
554 `ssh.variant` that serves the same purpose.
557 If this environment variable is set, then Git commands which need to
558 acquire passwords or passphrases (e.g. for HTTP or IMAP authentication)
559 will call this program with a suitable prompt as command-line argument
560 and read the password from its STDOUT. See also the `core.askPass`
561 option in linkgit:git-config[1].
564 If this environment variable is set to `0`, git will not prompt
565 on the terminal (e.g., when asking for HTTP authentication).
568 Whether to skip reading settings from the system-wide
569 `$(prefix)/etc/gitconfig` file. This environment variable can
570 be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a
571 predictable environment for a picky script, or you can set it
572 temporarily to avoid using a buggy `/etc/gitconfig` file while
573 waiting for someone with sufficient permissions to fix it.
575 `GIT_FLUSH`::
576 If this environment variable is set to "1", then commands such
577 as 'git blame' (in incremental mode), 'git rev-list', 'git log',
578 'git check-attr' and 'git check-ignore' will
579 force a flush of the output stream after each record have been
580 flushed. If this
581 variable is set to "0", the output of these commands will be done
582 using completely buffered I/O. If this environment variable is
583 not set, Git will choose buffered or record-oriented flushing
584 based on whether stdout appears to be redirected to a file or not.
586 `GIT_TRACE`::
587 Enables general trace messages, e.g. alias expansion, built-in
588 command execution and external command execution.
589 +
590 If this variable is set to "1", "2" or "true" (comparison
591 is case insensitive), trace messages will be printed to
592 stderr.
593 +
594 If the variable is set to an integer value greater than 2
595 and lower than 10 (strictly) then Git will interpret this
596 value as an open file descriptor and will try to write the
597 trace messages into this file descriptor.
598 +
599 Alternatively, if the variable is set to an absolute path
600 (starting with a '/' character), Git will interpret this
601 as a file path and will try to append the trace messages
602 to it.
603 +
604 Unsetting the variable, or setting it to empty, "0" or
605 "false" (case insensitive) disables trace messages.
608 Enables trace messages for the filesystem monitor extension.
609 See `GIT_TRACE` for available trace output options.
612 Enables trace messages for all accesses to any packs. For each
613 access, the pack file name and an offset in the pack is
614 recorded. This may be helpful for troubleshooting some
615 pack-related performance problems.
616 See `GIT_TRACE` for available trace output options.
619 Enables trace messages for all packets coming in or out of a
620 given program. This can help with debugging object negotiation
621 or other protocol issues. Tracing is turned off at a packet
622 starting with "PACK" (but see `GIT_TRACE_PACKFILE` below).
623 See `GIT_TRACE` for available trace output options.
626 Enables tracing of packfiles sent or received by a
627 given program. Unlike other trace output, this trace is
628 verbatim: no headers, and no quoting of binary data. You almost
629 certainly want to direct into a file (e.g.,
630 `GIT_TRACE_PACKFILE=/tmp/my.pack`) rather than displaying it on
631 the terminal or mixing it with other trace output.
632 +
633 Note that this is currently only implemented for the client side
634 of clones and fetches.
637 Enables performance related trace messages, e.g. total execution
638 time of each Git command.
639 See `GIT_TRACE` for available trace output options.
642 Enables trace messages printing the .git, working tree and current
643 working directory after Git has completed its setup phase.
644 See `GIT_TRACE` for available trace output options.
647 Enables trace messages that can help debugging fetching /
648 cloning of shallow repositories.
649 See `GIT_TRACE` for available trace output options.
652 Enables a curl full trace dump of all incoming and outgoing data,
653 including descriptive information, of the git transport protocol.
654 This is similar to doing curl `--trace-ascii` on the command line.
655 This option overrides setting the `GIT_CURL_VERBOSE` environment
656 variable.
657 See `GIT_TRACE` for available trace output options.
660 When a curl trace is enabled (see `GIT_TRACE_CURL` above), do not dump
661 data (that is, only dump info lines and headers).
663 `GIT_TRACE2`::
664 Enables more detailed trace messages from the "trace2" library.
665 Output from `GIT_TRACE2` is a simple text-based format for human
666 readability.
667 +
668 If this variable is set to "1", "2" or "true" (comparison
669 is case insensitive), trace messages will be printed to
670 stderr.
671 +
672 If the variable is set to an integer value greater than 2
673 and lower than 10 (strictly) then Git will interpret this
674 value as an open file descriptor and will try to write the
675 trace messages into this file descriptor.
676 +
677 Alternatively, if the variable is set to an absolute path
678 (starting with a '/' character), Git will interpret this
679 as a file path and will try to append the trace messages
680 to it. If the path already exists and is a directory, the
681 trace messages will be written to files (one per process)
682 in that directory, named according to the last component
683 of the SID and an optional counter (to avoid filename
684 collisions).
685 +
686 In addition, if the variable is set to
687 `af_unix:[<socket_type>:]<absolute-pathname>`, Git will try
688 to open the path as a Unix Domain Socket. The socket type
689 can be either `stream` or `dgram`.
690 +
691 Unsetting the variable, or setting it to empty, "0" or
692 "false" (case insensitive) disables trace messages.
693 +
694 See link:technical/api-trace2.html[Trace2 documentation]
695 for full details.
699 This setting writes a JSON-based format that is suited for machine
700 interpretation.
701 See `GIT_TRACE2` for available trace output options and
702 link:technical/api-trace2.html[Trace2 documentation] for full details.
705 In addition to the text-based messages available in `GIT_TRACE2`, this
706 setting writes a column-based format for understanding nesting
707 regions.
708 See `GIT_TRACE2` for available trace output options and
709 link:technical/api-trace2.html[Trace2 documentation] for full details.
712 This can be set to a comma-separated list of strings. When a curl trace
713 is enabled (see `GIT_TRACE_CURL` above), whenever a "Cookies:" header
714 sent by the client is dumped, values of cookies whose key is in that
715 list (case-sensitive) are redacted.
718 Setting this variable to `1` will cause Git to treat all
719 pathspecs literally, rather than as glob patterns. For example,
720 running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search
721 for commits that touch the path `*.c`, not any paths that the
722 glob `*.c` matches. You might want this if you are feeding
723 literal paths to Git (e.g., paths previously given to you by
724 `git ls-tree`, `--raw` diff output, etc).
727 Setting this variable to `1` will cause Git to treat all
728 pathspecs as glob patterns (aka "glob" magic).
731 Setting this variable to `1` will cause Git to treat all
732 pathspecs as literal (aka "literal" magic).
735 Setting this variable to `1` will cause Git to treat all
736 pathspecs as case-insensitive.
739 When a ref is updated, reflog entries are created to keep
740 track of the reason why the ref was updated (which is
741 typically the name of the high-level command that updated
742 the ref), in addition to the old and new values of the ref.
743 A scripted Porcelain command can use set_reflog_action
744 helper function in `git-sh-setup` to set its name to this
745 variable when it is invoked as the top level command by the
746 end user, to be recorded in the body of the reflog.
749 If set to `1`, include broken or badly named refs when iterating
750 over lists of refs. In a normal, non-corrupted repository, this
751 does nothing. However, enabling it may help git to detect and
752 abort some operations in the presence of broken refs. Git sets
753 this variable automatically when performing destructive
754 operations like linkgit:git-prune[1]. You should not need to set
755 it yourself unless you want to be paranoid about making sure
756 an operation has touched every ref (e.g., because you are
757 cloning a repository to make a backup).
760 If set to a colon-separated list of protocols, behave as if
761 `protocol.allow` is set to `never`, and each of the listed
762 protocols has `protocol.<name>.allow` set to `always`
763 (overriding any existing configuration). In other words, any
764 protocol not mentioned will be disallowed (i.e., this is a
765 whitelist, not a blacklist). See the description of
766 `protocol.allow` in linkgit:git-config[1] for more details.
769 Set to 0 to prevent protocols used by fetch/push/clone which are
770 configured to the `user` state. This is useful to restrict recursive
771 submodule initialization from an untrusted repository or for programs
772 which feed potentially-untrusted URLS to git commands. See
773 linkgit:git-config[1] for more details.
776 For internal use only. Used in handshaking the wire protocol.
777 Contains a colon ':' separated list of keys with optional values
778 'key[=value]'. Presence of unknown keys and values must be
779 ignored.
782 If set to `0`, Git will complete any requested operation without
783 performing any optional sub-operations that require taking a lock.
784 For example, this will prevent `git status` from refreshing the
785 index as a side effect. This is useful for processes running in
786 the background which do not want to cause lock contention with
787 other operations on the repository. Defaults to `1`.
792 Windows-only: allow redirecting the standard input/output/error
793 handles to paths specified by the environment variables. This is
794 particularly useful in multi-threaded applications where the
795 canonical way to pass standard handles via `CreateProcess()` is
796 not an option because it would require the handles to be marked
797 inheritable (and consequently *every* spawned process would
798 inherit them, possibly blocking regular Git operations). The
799 primary intended use case is to use named pipes for communication
800 (e.g. `\\.\pipe\my-git-stdin-123`).
801 +
802 Two special values are supported: `off` will simply close the
803 corresponding standard handle, and if `GIT_REDIRECT_STDERR` is
804 `2>&1`, standard error will be redirected to the same handle as
805 standard output.
807 `GIT_PRINT_SHA1_ELLIPSIS` (deprecated)::
808 If set to `yes`, print an ellipsis following an
809 (abbreviated) SHA-1 value. This affects indications of
810 detached HEADs (linkgit:git-checkout[1]) and the raw
811 diff output (linkgit:git-diff[1]). Printing an
812 ellipsis in the cases mentioned is no longer considered
813 adequate and support for it is likely to be removed in the
814 foreseeable future (along with the variable).
816 Discussion[[Discussion]]
817 ------------------------
819 More detail on the following is available from the
820 link:user-manual.html#git-concepts[Git concepts chapter of the
821 user-manual] and linkgit:gitcore-tutorial[7].
823 A Git project normally consists of a working directory with a ".git"
824 subdirectory at the top level. The .git directory contains, among other
825 things, a compressed object database representing the complete history
826 of the project, an "index" file which links that history to the current
827 contents of the working tree, and named pointers into that history such
828 as tags and branch heads.
830 The object database contains objects of three main types: blobs, which
831 hold file data; trees, which point to blobs and other trees to build up
832 directory hierarchies; and commits, which each reference a single tree
833 and some number of parent commits.
835 The commit, equivalent to what other systems call a "changeset" or
836 "version", represents a step in the project's history, and each parent
837 represents an immediately preceding step. Commits with more than one
838 parent represent merges of independent lines of development.
840 All objects are named by the SHA-1 hash of their contents, normally
841 written as a string of 40 hex digits. Such names are globally unique.
842 The entire history leading up to a commit can be vouched for by signing
843 just that commit. A fourth object type, the tag, is provided for this
844 purpose.
846 When first created, objects are stored in individual files, but for
847 efficiency may later be compressed together into "pack files".
849 Named pointers called refs mark interesting points in history. A ref
850 may contain the SHA-1 name of an object or the name of another ref. Refs
851 with names beginning `ref/head/` contain the SHA-1 name of the most
852 recent commit (or "head") of a branch under development. SHA-1 names of
853 tags of interest are stored under `ref/tags/`. A special ref named
854 `HEAD` contains the name of the currently checked-out branch.
856 The index file is initialized with a list of all paths and, for each
857 path, a blob object and a set of attributes. The blob object represents
858 the contents of the file as of the head of the current branch. The
859 attributes (last modified time, size, etc.) are taken from the
860 corresponding file in the working tree. Subsequent changes to the
861 working tree can be found by comparing these attributes. The index may
862 be updated with new content, and new commits may be created from the
863 content stored in the index.
865 The index is also capable of storing multiple entries (called "stages")
866 for a given pathname. These stages are used to hold the various
867 unmerged version of a file when a merge is in progress.
870 ---------------------
872 See the references in the "description" section to get started
873 using Git. The following is probably more detail than necessary
874 for a first-time user.
876 The link:user-manual.html#git-concepts[Git concepts chapter of the
877 user-manual] and linkgit:gitcore-tutorial[7] both provide
878 introductions to the underlying Git architecture.
880 See linkgit:gitworkflows[7] for an overview of recommended workflows.
882 See also the link:howto-index.html[howto] documents for some useful
883 examples.
885 The internals are documented in the
886 link:technical/api-index.html[Git API documentation].
888 Users migrating from CVS may also want to
889 read linkgit:gitcvs-migration[7].
892 Authors
893 -------
894 Git was started by Linus Torvalds, and is currently maintained by Junio
895 C Hamano. Numerous contributions have come from the Git mailing list
896 <>.
897 gives you a more complete list of contributors.
899 If you have a clone of git.git itself, the
900 output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you
901 the authors for specific parts of the project.
903 Reporting Bugs
904 --------------
906 Report bugs to the Git mailing list <> where the
907 development and maintenance is primarily done. You do not have to be
908 subscribed to the list to send a message there. See the list archive
909 at for previous bug reports and other
910 discussions.
912 Issues which are security relevant should be disclosed privately to
913 the Git Security mailing list <>.
916 --------
917 linkgit:gittutorial[7], linkgit:gittutorial-2[7],
918 linkgit:giteveryday[7], linkgit:gitcvs-migration[7],
919 linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
920 linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],
921 linkgit:gitworkflows[7]
923 GIT
924 ---
925 Part of the linkgit:git[1] suite