6d1f2fd9ae9e993e46d935f835bdfec4e6f686e1
[git/git.git] / Documentation / git.txt
1 git(1)
2 ======
3
4 NAME
5 ----
6 git - the stupid content tracker
7
8
9 SYNOPSIS
10 --------
11 [verse]
12 'git' [--version] [--help] [-C <path>] [-c <name>=<value>]
13 [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
14 [-p|--paginate|-P|--no-pager] [--no-replace-objects] [--bare]
15 [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
16 [--super-prefix=<path>]
17 <command> [<args>]
18
19 DESCRIPTION
20 -----------
21 Git is a fast, scalable, distributed revision control system with an
22 unusually rich command set that provides both high-level operations
23 and full access to internals.
24
25 See linkgit:gittutorial[7] to get started, then see
26 linkgit:giteveryday[7] for a useful minimum set of
27 commands. The link:user-manual.html[Git User's Manual] has a more
28 in-depth introduction.
29
30 After you mastered the basic concepts, you can come back to this
31 page to learn what commands Git offers. You can learn more about
32 individual Git commands with "git help command". linkgit:gitcli[7]
33 manual page gives you an overview of the command-line command syntax.
34
35 A formatted and hyperlinked copy of the latest Git documentation
36 can be viewed at `https://git.github.io/htmldocs/git.html`.
37
38
39 OPTIONS
40 -------
41 --version::
42 Prints the Git suite version that the 'git' program came from.
43
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 ...`.
54
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:
65
66 git --git-dir=a.git --work-tree=b -C c status
67 git --git-dir=c/a.git --work-tree=c/b status
68
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 foo.bar ...` is allowed and sets
76 `foo.bar` 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 foo.bar= ...`) sets `foo.bar` to the empty string which `git config
79 --type=bool` will convert to `false`.
80
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.
86
87 --html-path::
88 Print the path, without trailing slash, where Git's HTML
89 documentation is installed and exit.
90
91 --man-path::
92 Print the manpath (see `man(1)`) for the man pages for
93 this version of Git and exit.
94
95 --info-path::
96 Print the path where the Info files documenting this
97 version of Git are installed and exit.
98
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).
105
106 -P::
107 --no-pager::
108 Do not pipe Git output into a pager.
109
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.
114
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).
122
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.
127
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.
132
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.
137
138 --no-replace-objects::
139 Do not use replacement refs to replace Git objects. See
140 linkgit:git-replace[1] for more information.
141
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`.
146
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)"
152
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)"
158
159 --icase-pathspecs::
160 Add "icase" magic to all pathspec. This is equivalent to setting
161 the `GIT_ICASE_PATHSPECS` environment variable to `1`.
162
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`.
166
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)
176
177 GIT COMMANDS
178 ------------
179
180 We divide Git into high level ("porcelain") commands and low level
181 ("plumbing") commands.
182
183 High-level commands (porcelain)
184 -------------------------------
185
186 We separate the porcelain commands into the main commands and some
187 ancillary user utilities.
188
189 Main porcelain commands
190 ~~~~~~~~~~~~~~~~~~~~~~~
191
192 include::cmds-mainporcelain.txt[]
193
194 Ancillary Commands
195 ~~~~~~~~~~~~~~~~~~
196 Manipulators:
197
198 include::cmds-ancillarymanipulators.txt[]
199
200 Interrogators:
201
202 include::cmds-ancillaryinterrogators.txt[]
203
204
205 Interacting with Others
206 ~~~~~~~~~~~~~~~~~~~~~~~
207
208 These commands are to interact with foreign SCM and with other
209 people via patch over e-mail.
210
211 include::cmds-foreignscminterface.txt[]
212
213
214 Low-level commands (plumbing)
215 -----------------------------
216
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].
222
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.
229
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.
235
236
237 Manipulation commands
238 ~~~~~~~~~~~~~~~~~~~~~
239
240 include::cmds-plumbingmanipulators.txt[]
241
242
243 Interrogation commands
244 ~~~~~~~~~~~~~~~~~~~~~~
245
246 include::cmds-plumbinginterrogators.txt[]
247
248 In general, the interrogate commands do not touch the files in
249 the working tree.
250
251
252 Synching repositories
253 ~~~~~~~~~~~~~~~~~~~~~
254
255 include::cmds-synchingrepositories.txt[]
256
257 The following are helper commands used by the above; end users
258 typically do not use them directly.
259
260 include::cmds-synchelpers.txt[]
261
262
263 Internal helper commands
264 ~~~~~~~~~~~~~~~~~~~~~~~~
265
266 These are internal helper commands used by other commands; end
267 users typically do not use them directly.
268
269 include::cmds-purehelpers.txt[]
270
271
272 Configuration Mechanism
273 -----------------------
274
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:
278
279 ------------
280 #
281 # A '#' or ';' character indicates a comment.
282 #
283
284 ; core variables
285 [core]
286 ; Don't trust file modes
287 filemode = false
288
289 ; user identity
290 [user]
291 name = "Junio C Hamano"
292 email = "gitster@pobox.com"
293
294 ------------
295
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.
299
300
301 Identifier Terminology
302 ----------------------
303 <object>::
304 Indicates the object name for any type of object.
305
306 <blob>::
307 Indicates a blob object name.
308
309 <tree>::
310 Indicates a tree object name.
311
312 <commit>::
313 Indicates a commit object name.
314
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>.
320
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>.
326
327 <type>::
328 Indicates that an object type is required.
329 Currently one of: `blob`, `tree`, `commit`, or `tag`.
330
331 <file>::
332 Indicates a filename - almost always relative to the
333 root of the tree structure `GIT_INDEX_FILE` describes.
334
335 Symbolic Identifiers
336 --------------------
337 Any Git command accepting any <object> can also use the following
338 symbolic notation:
339
340 HEAD::
341 indicates the head of the current branch.
342
343 <tag>::
344 a valid tag 'name'
345 (i.e. a `refs/tags/<tag>` reference).
346
347 <head>::
348 a valid head 'name'
349 (i.e. a `refs/heads/<head>` reference).
350
351 For a more complete list of ways to spell object names, see
352 "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
353
354
355 File/Directory Structure
356 ------------------------
357
358 Please see the linkgit:gitrepository-layout[5] document.
359
360 Read linkgit:githooks[5] for more details about each hook.
361
362 Higher level SCMs may provide and manage additional information in the
363 `$GIT_DIR`.
364
365
366 Terminology
367 -----------
368 Please see linkgit:gitglossary[7].
369
370
371 Environment Variables
372 ---------------------
373 Various Git commands use the following environment variables:
374
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.
380
381 `GIT_INDEX_FILE`::
382 This environment allows the specification of an alternate
383 index file. If not specified, the default of `$GIT_DIR/index`
384 is used.
385
386 `GIT_INDEX_VERSION`::
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.
391
392 `GIT_OBJECT_DIRECTORY`::
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.
397
398 `GIT_ALTERNATE_OBJECT_DIRECTORIES`::
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`.
410
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.
416
417 `GIT_WORK_TREE`::
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.
421
422 `GIT_NAMESPACE`::
423 Set the Git namespace; see linkgit:gitnamespaces[7] for details.
424 The `--namespace` command-line option also sets this value.
425
426 `GIT_CEILING_DIRECTORIES`::
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`.
440
441 `GIT_DISCOVERY_ACROSS_FILESYSTEM`::
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.
450
451 `GIT_COMMON_DIR`::
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...
459
460 Git Commits
461 ~~~~~~~~~~~
462 `GIT_AUTHOR_NAME`::
463 `GIT_AUTHOR_EMAIL`::
464 `GIT_AUTHOR_DATE`::
465 `GIT_COMMITTER_NAME`::
466 `GIT_COMMITTER_EMAIL`::
467 `GIT_COMMITTER_DATE`::
468 'EMAIL'::
469 see linkgit:git-commit-tree[1]
470
471 Git Diffs
472 ~~~~~~~~~
473 `GIT_DIFF_OPTS`::
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.
478
479 `GIT_EXTERNAL_DIFF`::
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:
484
485 path old-file old-hex old-mode new-file new-hex new-mode
486 +
487 where:
488
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,
504 `GIT_DIFF_PATH_COUNTER` and `GIT_DIFF_PATH_TOTAL` are set.
505
506 `GIT_DIFF_PATH_COUNTER`::
507 A 1-based counter incremented by one for every path.
508
509 `GIT_DIFF_PATH_TOTAL`::
510 The total number of paths.
511
512 other
513 ~~~~~
514 `GIT_MERGE_VERBOSITY`::
515 A number controlling the amount of output shown by
516 the recursive merge strategy. Overrides merge.verbosity.
517 See linkgit:git-merge[1]
518
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].
524
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].
530
531 `GIT_SSH`::
532 `GIT_SSH_COMMAND`::
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.
549
550 `GIT_SSH_VARIANT`::
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.
555
556 `GIT_ASKPASS`::
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].
562
563 `GIT_TERMINAL_PROMPT`::
564 If this environment variable is set to `0`, git will not prompt
565 on the terminal (e.g., when asking for HTTP authentication).
566
567 `GIT_CONFIG_NOSYSTEM`::
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.
574
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.
585
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.
606
607 `GIT_TRACE_FSMONITOR`::
608 Enables trace messages for the filesystem monitor extension.
609 See `GIT_TRACE` for available trace output options.
610
611 `GIT_TRACE_PACK_ACCESS`::
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.
617
618 `GIT_TRACE_PACKET`::
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.
624
625 `GIT_TRACE_PACKFILE`::
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.
635
636 `GIT_TRACE_PERFORMANCE`::
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.
640
641 `GIT_TRACE_SETUP`::
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.
645
646 `GIT_TRACE_SHALLOW`::
647 Enables trace messages that can help debugging fetching /
648 cloning of shallow repositories.
649 See `GIT_TRACE` for available trace output options.
650
651 `GIT_TRACE_CURL`::
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.
658
659 `GIT_TRACE_CURL_NO_DATA`::
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).
662
663 `GIT_REDACT_COOKIES`::
664 This can be set to a comma-separated list of strings. When a curl trace
665 is enabled (see `GIT_TRACE_CURL` above), whenever a "Cookies:" header
666 sent by the client is dumped, values of cookies whose key is in that
667 list (case-sensitive) are redacted.
668
669 `GIT_LITERAL_PATHSPECS`::
670 Setting this variable to `1` will cause Git to treat all
671 pathspecs literally, rather than as glob patterns. For example,
672 running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search
673 for commits that touch the path `*.c`, not any paths that the
674 glob `*.c` matches. You might want this if you are feeding
675 literal paths to Git (e.g., paths previously given to you by
676 `git ls-tree`, `--raw` diff output, etc).
677
678 `GIT_GLOB_PATHSPECS`::
679 Setting this variable to `1` will cause Git to treat all
680 pathspecs as glob patterns (aka "glob" magic).
681
682 `GIT_NOGLOB_PATHSPECS`::
683 Setting this variable to `1` will cause Git to treat all
684 pathspecs as literal (aka "literal" magic).
685
686 `GIT_ICASE_PATHSPECS`::
687 Setting this variable to `1` will cause Git to treat all
688 pathspecs as case-insensitive.
689
690 `GIT_REFLOG_ACTION`::
691 When a ref is updated, reflog entries are created to keep
692 track of the reason why the ref was updated (which is
693 typically the name of the high-level command that updated
694 the ref), in addition to the old and new values of the ref.
695 A scripted Porcelain command can use set_reflog_action
696 helper function in `git-sh-setup` to set its name to this
697 variable when it is invoked as the top level command by the
698 end user, to be recorded in the body of the reflog.
699
700 `GIT_REF_PARANOIA`::
701 If set to `1`, include broken or badly named refs when iterating
702 over lists of refs. In a normal, non-corrupted repository, this
703 does nothing. However, enabling it may help git to detect and
704 abort some operations in the presence of broken refs. Git sets
705 this variable automatically when performing destructive
706 operations like linkgit:git-prune[1]. You should not need to set
707 it yourself unless you want to be paranoid about making sure
708 an operation has touched every ref (e.g., because you are
709 cloning a repository to make a backup).
710
711 `GIT_ALLOW_PROTOCOL`::
712 If set to a colon-separated list of protocols, behave as if
713 `protocol.allow` is set to `never`, and each of the listed
714 protocols has `protocol.<name>.allow` set to `always`
715 (overriding any existing configuration). In other words, any
716 protocol not mentioned will be disallowed (i.e., this is a
717 whitelist, not a blacklist). See the description of
718 `protocol.allow` in linkgit:git-config[1] for more details.
719
720 `GIT_PROTOCOL_FROM_USER`::
721 Set to 0 to prevent protocols used by fetch/push/clone which are
722 configured to the `user` state. This is useful to restrict recursive
723 submodule initialization from an untrusted repository or for programs
724 which feed potentially-untrusted URLS to git commands. See
725 linkgit:git-config[1] for more details.
726
727 `GIT_PROTOCOL`::
728 For internal use only. Used in handshaking the wire protocol.
729 Contains a colon ':' separated list of keys with optional values
730 'key[=value]'. Presence of unknown keys and values must be
731 ignored.
732
733 `GIT_OPTIONAL_LOCKS`::
734 If set to `0`, Git will complete any requested operation without
735 performing any optional sub-operations that require taking a lock.
736 For example, this will prevent `git status` from refreshing the
737 index as a side effect. This is useful for processes running in
738 the background which do not want to cause lock contention with
739 other operations on the repository. Defaults to `1`.
740
741 `GIT_REDIRECT_STDIN`::
742 `GIT_REDIRECT_STDOUT`::
743 `GIT_REDIRECT_STDERR`::
744 Windows-only: allow redirecting the standard input/output/error
745 handles to paths specified by the environment variables. This is
746 particularly useful in multi-threaded applications where the
747 canonical way to pass standard handles via `CreateProcess()` is
748 not an option because it would require the handles to be marked
749 inheritable (and consequently *every* spawned process would
750 inherit them, possibly blocking regular Git operations). The
751 primary intended use case is to use named pipes for communication
752 (e.g. `\\.\pipe\my-git-stdin-123`).
753 +
754 Two special values are supported: `off` will simply close the
755 corresponding standard handle, and if `GIT_REDIRECT_STDERR` is
756 `2>&1`, standard error will be redirected to the same handle as
757 standard output.
758
759 `GIT_PRINT_SHA1_ELLIPSIS` (deprecated)::
760 If set to `yes`, print an ellipsis following an
761 (abbreviated) SHA-1 value. This affects indications of
762 detached HEADs (linkgit:git-checkout[1]) and the raw
763 diff output (linkgit:git-diff[1]). Printing an
764 ellipsis in the cases mentioned is no longer considered
765 adequate and support for it is likely to be removed in the
766 foreseeable future (along with the variable).
767
768 Discussion[[Discussion]]
769 ------------------------
770
771 More detail on the following is available from the
772 link:user-manual.html#git-concepts[Git concepts chapter of the
773 user-manual] and linkgit:gitcore-tutorial[7].
774
775 A Git project normally consists of a working directory with a ".git"
776 subdirectory at the top level. The .git directory contains, among other
777 things, a compressed object database representing the complete history
778 of the project, an "index" file which links that history to the current
779 contents of the working tree, and named pointers into that history such
780 as tags and branch heads.
781
782 The object database contains objects of three main types: blobs, which
783 hold file data; trees, which point to blobs and other trees to build up
784 directory hierarchies; and commits, which each reference a single tree
785 and some number of parent commits.
786
787 The commit, equivalent to what other systems call a "changeset" or
788 "version", represents a step in the project's history, and each parent
789 represents an immediately preceding step. Commits with more than one
790 parent represent merges of independent lines of development.
791
792 All objects are named by the SHA-1 hash of their contents, normally
793 written as a string of 40 hex digits. Such names are globally unique.
794 The entire history leading up to a commit can be vouched for by signing
795 just that commit. A fourth object type, the tag, is provided for this
796 purpose.
797
798 When first created, objects are stored in individual files, but for
799 efficiency may later be compressed together into "pack files".
800
801 Named pointers called refs mark interesting points in history. A ref
802 may contain the SHA-1 name of an object or the name of another ref. Refs
803 with names beginning `ref/head/` contain the SHA-1 name of the most
804 recent commit (or "head") of a branch under development. SHA-1 names of
805 tags of interest are stored under `ref/tags/`. A special ref named
806 `HEAD` contains the name of the currently checked-out branch.
807
808 The index file is initialized with a list of all paths and, for each
809 path, a blob object and a set of attributes. The blob object represents
810 the contents of the file as of the head of the current branch. The
811 attributes (last modified time, size, etc.) are taken from the
812 corresponding file in the working tree. Subsequent changes to the
813 working tree can be found by comparing these attributes. The index may
814 be updated with new content, and new commits may be created from the
815 content stored in the index.
816
817 The index is also capable of storing multiple entries (called "stages")
818 for a given pathname. These stages are used to hold the various
819 unmerged version of a file when a merge is in progress.
820
821 FURTHER DOCUMENTATION
822 ---------------------
823
824 See the references in the "description" section to get started
825 using Git. The following is probably more detail than necessary
826 for a first-time user.
827
828 The link:user-manual.html#git-concepts[Git concepts chapter of the
829 user-manual] and linkgit:gitcore-tutorial[7] both provide
830 introductions to the underlying Git architecture.
831
832 See linkgit:gitworkflows[7] for an overview of recommended workflows.
833
834 See also the link:howto-index.html[howto] documents for some useful
835 examples.
836
837 The internals are documented in the
838 link:technical/api-index.html[Git API documentation].
839
840 Users migrating from CVS may also want to
841 read linkgit:gitcvs-migration[7].
842
843
844 Authors
845 -------
846 Git was started by Linus Torvalds, and is currently maintained by Junio
847 C Hamano. Numerous contributions have come from the Git mailing list
848 <git@vger.kernel.org>. http://www.openhub.net/p/git/contributors/summary
849 gives you a more complete list of contributors.
850
851 If you have a clone of git.git itself, the
852 output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you
853 the authors for specific parts of the project.
854
855 Reporting Bugs
856 --------------
857
858 Report bugs to the Git mailing list <git@vger.kernel.org> where the
859 development and maintenance is primarily done. You do not have to be
860 subscribed to the list to send a message there. See the list archive
861 at https://public-inbox.org/git for previous bug reports and other
862 discussions.
863
864 Issues which are security relevant should be disclosed privately to
865 the Git Security mailing list <git-security@googlegroups.com>.
866
867 SEE ALSO
868 --------
869 linkgit:gittutorial[7], linkgit:gittutorial-2[7],
870 linkgit:giteveryday[7], linkgit:gitcvs-migration[7],
871 linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
872 linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],
873 linkgit:gitworkflows[7]
874
875 GIT
876 ---
877 Part of the linkgit:git[1] suite