Merge branch 'ls/no-double-utf8-author-name' of ../git-gui into ls/git-gui-no-double...
[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|--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 --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 --no-pager::
107 Do not pipe Git output into a pager.
108
109 --git-dir=<path>::
110 Set the path to the repository. This can also be controlled by
111 setting the `GIT_DIR` environment variable. It can be an absolute
112 path or relative path to current working directory.
113
114 --work-tree=<path>::
115 Set the path to the working tree. It can be an absolute path
116 or a path relative to the current working directory.
117 This can also be controlled by setting the GIT_WORK_TREE
118 environment variable and the core.worktree configuration
119 variable (see core.worktree in linkgit:git-config[1] for a
120 more detailed discussion).
121
122 --namespace=<path>::
123 Set the Git namespace. See linkgit:gitnamespaces[7] for more
124 details. Equivalent to setting the `GIT_NAMESPACE` environment
125 variable.
126
127 --super-prefix=<path>::
128 Currently for internal use only. Set a prefix which gives a path from
129 above a repository down to its root. One use is to give submodules
130 context about the superproject that invoked it.
131
132 --bare::
133 Treat the repository as a bare repository. If GIT_DIR
134 environment is not set, it is set to the current working
135 directory.
136
137 --no-replace-objects::
138 Do not use replacement refs to replace Git objects. See
139 linkgit:git-replace[1] for more information.
140
141 --literal-pathspecs::
142 Treat pathspecs literally (i.e. no globbing, no pathspec magic).
143 This is equivalent to setting the `GIT_LITERAL_PATHSPECS` environment
144 variable to `1`.
145
146 --glob-pathspecs::
147 Add "glob" magic to all pathspec. This is equivalent to setting
148 the `GIT_GLOB_PATHSPECS` environment variable to `1`. Disabling
149 globbing on individual pathspecs can be done using pathspec
150 magic ":(literal)"
151
152 --noglob-pathspecs::
153 Add "literal" magic to all pathspec. This is equivalent to setting
154 the `GIT_NOGLOB_PATHSPECS` environment variable to `1`. Enabling
155 globbing on individual pathspecs can be done using pathspec
156 magic ":(glob)"
157
158 --icase-pathspecs::
159 Add "icase" magic to all pathspec. This is equivalent to setting
160 the `GIT_ICASE_PATHSPECS` environment variable to `1`.
161
162 --no-optional-locks::
163 Do not perform optional operations that require locks. This is
164 equivalent to setting the `GIT_OPTIONAL_LOCKS` to `0`.
165
166 GIT COMMANDS
167 ------------
168
169 We divide Git into high level ("porcelain") commands and low level
170 ("plumbing") commands.
171
172 High-level commands (porcelain)
173 -------------------------------
174
175 We separate the porcelain commands into the main commands and some
176 ancillary user utilities.
177
178 Main porcelain commands
179 ~~~~~~~~~~~~~~~~~~~~~~~
180
181 include::cmds-mainporcelain.txt[]
182
183 Ancillary Commands
184 ~~~~~~~~~~~~~~~~~~
185 Manipulators:
186
187 include::cmds-ancillarymanipulators.txt[]
188
189 Interrogators:
190
191 include::cmds-ancillaryinterrogators.txt[]
192
193
194 Interacting with Others
195 ~~~~~~~~~~~~~~~~~~~~~~~
196
197 These commands are to interact with foreign SCM and with other
198 people via patch over e-mail.
199
200 include::cmds-foreignscminterface.txt[]
201
202
203 Low-level commands (plumbing)
204 -----------------------------
205
206 Although Git includes its
207 own porcelain layer, its low-level commands are sufficient to support
208 development of alternative porcelains. Developers of such porcelains
209 might start by reading about linkgit:git-update-index[1] and
210 linkgit:git-read-tree[1].
211
212 The interface (input, output, set of options and the semantics)
213 to these low-level commands are meant to be a lot more stable
214 than Porcelain level commands, because these commands are
215 primarily for scripted use. The interface to Porcelain commands
216 on the other hand are subject to change in order to improve the
217 end user experience.
218
219 The following description divides
220 the low-level commands into commands that manipulate objects (in
221 the repository, index, and working tree), commands that interrogate and
222 compare objects, and commands that move objects and references between
223 repositories.
224
225
226 Manipulation commands
227 ~~~~~~~~~~~~~~~~~~~~~
228
229 include::cmds-plumbingmanipulators.txt[]
230
231
232 Interrogation commands
233 ~~~~~~~~~~~~~~~~~~~~~~
234
235 include::cmds-plumbinginterrogators.txt[]
236
237 In general, the interrogate commands do not touch the files in
238 the working tree.
239
240
241 Synching repositories
242 ~~~~~~~~~~~~~~~~~~~~~
243
244 include::cmds-synchingrepositories.txt[]
245
246 The following are helper commands used by the above; end users
247 typically do not use them directly.
248
249 include::cmds-synchelpers.txt[]
250
251
252 Internal helper commands
253 ~~~~~~~~~~~~~~~~~~~~~~~~
254
255 These are internal helper commands used by other commands; end
256 users typically do not use them directly.
257
258 include::cmds-purehelpers.txt[]
259
260
261 Configuration Mechanism
262 -----------------------
263
264 Git uses a simple text format to store customizations that are per
265 repository and are per user. Such a configuration file may look
266 like this:
267
268 ------------
269 #
270 # A '#' or ';' character indicates a comment.
271 #
272
273 ; core variables
274 [core]
275 ; Don't trust file modes
276 filemode = false
277
278 ; user identity
279 [user]
280 name = "Junio C Hamano"
281 email = "gitster@pobox.com"
282
283 ------------
284
285 Various commands read from the configuration file and adjust
286 their operation accordingly. See linkgit:git-config[1] for a
287 list and more details about the configuration mechanism.
288
289
290 Identifier Terminology
291 ----------------------
292 <object>::
293 Indicates the object name for any type of object.
294
295 <blob>::
296 Indicates a blob object name.
297
298 <tree>::
299 Indicates a tree object name.
300
301 <commit>::
302 Indicates a commit object name.
303
304 <tree-ish>::
305 Indicates a tree, commit or tag object name. A
306 command that takes a <tree-ish> argument ultimately wants to
307 operate on a <tree> object but automatically dereferences
308 <commit> and <tag> objects that point at a <tree>.
309
310 <commit-ish>::
311 Indicates a commit or tag object name. A
312 command that takes a <commit-ish> argument ultimately wants to
313 operate on a <commit> object but automatically dereferences
314 <tag> objects that point at a <commit>.
315
316 <type>::
317 Indicates that an object type is required.
318 Currently one of: `blob`, `tree`, `commit`, or `tag`.
319
320 <file>::
321 Indicates a filename - almost always relative to the
322 root of the tree structure `GIT_INDEX_FILE` describes.
323
324 Symbolic Identifiers
325 --------------------
326 Any Git command accepting any <object> can also use the following
327 symbolic notation:
328
329 HEAD::
330 indicates the head of the current branch.
331
332 <tag>::
333 a valid tag 'name'
334 (i.e. a `refs/tags/<tag>` reference).
335
336 <head>::
337 a valid head 'name'
338 (i.e. a `refs/heads/<head>` reference).
339
340 For a more complete list of ways to spell object names, see
341 "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
342
343
344 File/Directory Structure
345 ------------------------
346
347 Please see the linkgit:gitrepository-layout[5] document.
348
349 Read linkgit:githooks[5] for more details about each hook.
350
351 Higher level SCMs may provide and manage additional information in the
352 `$GIT_DIR`.
353
354
355 Terminology
356 -----------
357 Please see linkgit:gitglossary[7].
358
359
360 Environment Variables
361 ---------------------
362 Various Git commands use the following environment variables:
363
364 The Git Repository
365 ~~~~~~~~~~~~~~~~~~
366 These environment variables apply to 'all' core Git commands. Nb: it
367 is worth noting that they may be used/overridden by SCMS sitting above
368 Git so take care if using a foreign front-end.
369
370 `GIT_INDEX_FILE`::
371 This environment allows the specification of an alternate
372 index file. If not specified, the default of `$GIT_DIR/index`
373 is used.
374
375 `GIT_INDEX_VERSION`::
376 This environment variable allows the specification of an index
377 version for new repositories. It won't affect existing index
378 files. By default index file version 2 or 3 is used. See
379 linkgit:git-update-index[1] for more information.
380
381 `GIT_OBJECT_DIRECTORY`::
382 If the object storage directory is specified via this
383 environment variable then the sha1 directories are created
384 underneath - otherwise the default `$GIT_DIR/objects`
385 directory is used.
386
387 `GIT_ALTERNATE_OBJECT_DIRECTORIES`::
388 Due to the immutable nature of Git objects, old objects can be
389 archived into shared, read-only directories. This variable
390 specifies a ":" separated (on Windows ";" separated) list
391 of Git object directories which can be used to search for Git
392 objects. New objects will not be written to these directories.
393 +
394 Entries that begin with `"` (double-quote) will be interpreted
395 as C-style quoted paths, removing leading and trailing
396 double-quotes and respecting backslash escapes. E.g., the value
397 `"path-with-\"-and-:-in-it":vanilla-path` has two paths:
398 `path-with-"-and-:-in-it` and `vanilla-path`.
399
400 `GIT_DIR`::
401 If the `GIT_DIR` environment variable is set then it
402 specifies a path to use instead of the default `.git`
403 for the base of the repository.
404 The `--git-dir` command-line option also sets this value.
405
406 `GIT_WORK_TREE`::
407 Set the path to the root of the working tree.
408 This can also be controlled by the `--work-tree` command-line
409 option and the core.worktree configuration variable.
410
411 `GIT_NAMESPACE`::
412 Set the Git namespace; see linkgit:gitnamespaces[7] for details.
413 The `--namespace` command-line option also sets this value.
414
415 `GIT_CEILING_DIRECTORIES`::
416 This should be a colon-separated list of absolute paths. If
417 set, it is a list of directories that Git should not chdir up
418 into while looking for a repository directory (useful for
419 excluding slow-loading network directories). It will not
420 exclude the current working directory or a GIT_DIR set on the
421 command line or in the environment. Normally, Git has to read
422 the entries in this list and resolve any symlink that
423 might be present in order to compare them with the current
424 directory. However, if even this access is slow, you
425 can add an empty entry to the list to tell Git that the
426 subsequent entries are not symlinks and needn't be resolved;
427 e.g.,
428 `GIT_CEILING_DIRECTORIES=/maybe/symlink::/very/slow/non/symlink`.
429
430 `GIT_DISCOVERY_ACROSS_FILESYSTEM`::
431 When run in a directory that does not have ".git" repository
432 directory, Git tries to find such a directory in the parent
433 directories to find the top of the working tree, but by default it
434 does not cross filesystem boundaries. This environment variable
435 can be set to true to tell Git not to stop at filesystem
436 boundaries. Like `GIT_CEILING_DIRECTORIES`, this will not affect
437 an explicit repository directory set via `GIT_DIR` or on the
438 command line.
439
440 `GIT_COMMON_DIR`::
441 If this variable is set to a path, non-worktree files that are
442 normally in $GIT_DIR will be taken from this path
443 instead. Worktree-specific files such as HEAD or index are
444 taken from $GIT_DIR. See linkgit:gitrepository-layout[5] and
445 linkgit:git-worktree[1] for
446 details. This variable has lower precedence than other path
447 variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY...
448
449 Git Commits
450 ~~~~~~~~~~~
451 `GIT_AUTHOR_NAME`::
452 `GIT_AUTHOR_EMAIL`::
453 `GIT_AUTHOR_DATE`::
454 `GIT_COMMITTER_NAME`::
455 `GIT_COMMITTER_EMAIL`::
456 `GIT_COMMITTER_DATE`::
457 'EMAIL'::
458 see linkgit:git-commit-tree[1]
459
460 Git Diffs
461 ~~~~~~~~~
462 `GIT_DIFF_OPTS`::
463 Only valid setting is "--unified=??" or "-u??" to set the
464 number of context lines shown when a unified diff is created.
465 This takes precedence over any "-U" or "--unified" option
466 value passed on the Git diff command line.
467
468 `GIT_EXTERNAL_DIFF`::
469 When the environment variable `GIT_EXTERNAL_DIFF` is set, the
470 program named by it is called, instead of the diff invocation
471 described above. For a path that is added, removed, or modified,
472 `GIT_EXTERNAL_DIFF` is called with 7 parameters:
473
474 path old-file old-hex old-mode new-file new-hex new-mode
475 +
476 where:
477
478 <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
479 contents of <old|new>,
480 <old|new>-hex:: are the 40-hexdigit SHA-1 hashes,
481 <old|new>-mode:: are the octal representation of the file modes.
482 +
483 The file parameters can point at the user's working file
484 (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
485 when a new file is added), or a temporary file (e.g. `old-file` in the
486 index). `GIT_EXTERNAL_DIFF` should not worry about unlinking the
487 temporary file --- it is removed when `GIT_EXTERNAL_DIFF` exits.
488 +
489 For a path that is unmerged, `GIT_EXTERNAL_DIFF` is called with 1
490 parameter, <path>.
491 +
492 For each path `GIT_EXTERNAL_DIFF` is called, two environment variables,
493 `GIT_DIFF_PATH_COUNTER` and `GIT_DIFF_PATH_TOTAL` are set.
494
495 `GIT_DIFF_PATH_COUNTER`::
496 A 1-based counter incremented by one for every path.
497
498 `GIT_DIFF_PATH_TOTAL`::
499 The total number of paths.
500
501 other
502 ~~~~~
503 `GIT_MERGE_VERBOSITY`::
504 A number controlling the amount of output shown by
505 the recursive merge strategy. Overrides merge.verbosity.
506 See linkgit:git-merge[1]
507
508 `GIT_PAGER`::
509 This environment variable overrides `$PAGER`. If it is set
510 to an empty string or to the value "cat", Git will not launch
511 a pager. See also the `core.pager` option in
512 linkgit:git-config[1].
513
514 `GIT_EDITOR`::
515 This environment variable overrides `$EDITOR` and `$VISUAL`.
516 It is used by several Git commands when, on interactive mode,
517 an editor is to be launched. See also linkgit:git-var[1]
518 and the `core.editor` option in linkgit:git-config[1].
519
520 `GIT_SSH`::
521 `GIT_SSH_COMMAND`::
522 If either of these environment variables is set then 'git fetch'
523 and 'git push' will use the specified command instead of 'ssh'
524 when they need to connect to a remote system.
525 The command will be given exactly two or four arguments: the
526 'username@host' (or just 'host') from the URL and the shell
527 command to execute on that remote system, optionally preceded by
528 `-p` (literally) and the 'port' from the URL when it specifies
529 something other than the default SSH port.
530 +
531 `$GIT_SSH_COMMAND` takes precedence over `$GIT_SSH`, and is interpreted
532 by the shell, which allows additional arguments to be included.
533 `$GIT_SSH` on the other hand must be just the path to a program
534 (which can be a wrapper shell script, if additional arguments are
535 needed).
536 +
537 Usually it is easier to configure any desired options through your
538 personal `.ssh/config` file. Please consult your ssh documentation
539 for further details.
540
541 `GIT_SSH_VARIANT`::
542 If this environment variable is set, it overrides Git's autodetection
543 whether `GIT_SSH`/`GIT_SSH_COMMAND`/`core.sshCommand` refer to OpenSSH,
544 plink or tortoiseplink. This variable overrides the config setting
545 `ssh.variant` that serves the same purpose.
546
547 `GIT_ASKPASS`::
548 If this environment variable is set, then Git commands which need to
549 acquire passwords or passphrases (e.g. for HTTP or IMAP authentication)
550 will call this program with a suitable prompt as command-line argument
551 and read the password from its STDOUT. See also the `core.askPass`
552 option in linkgit:git-config[1].
553
554 `GIT_TERMINAL_PROMPT`::
555 If this environment variable is set to `0`, git will not prompt
556 on the terminal (e.g., when asking for HTTP authentication).
557
558 `GIT_CONFIG_NOSYSTEM`::
559 Whether to skip reading settings from the system-wide
560 `$(prefix)/etc/gitconfig` file. This environment variable can
561 be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a
562 predictable environment for a picky script, or you can set it
563 temporarily to avoid using a buggy `/etc/gitconfig` file while
564 waiting for someone with sufficient permissions to fix it.
565
566 `GIT_FLUSH`::
567 If this environment variable is set to "1", then commands such
568 as 'git blame' (in incremental mode), 'git rev-list', 'git log',
569 'git check-attr' and 'git check-ignore' will
570 force a flush of the output stream after each record have been
571 flushed. If this
572 variable is set to "0", the output of these commands will be done
573 using completely buffered I/O. If this environment variable is
574 not set, Git will choose buffered or record-oriented flushing
575 based on whether stdout appears to be redirected to a file or not.
576
577 `GIT_TRACE`::
578 Enables general trace messages, e.g. alias expansion, built-in
579 command execution and external command execution.
580 +
581 If this variable is set to "1", "2" or "true" (comparison
582 is case insensitive), trace messages will be printed to
583 stderr.
584 +
585 If the variable is set to an integer value greater than 2
586 and lower than 10 (strictly) then Git will interpret this
587 value as an open file descriptor and will try to write the
588 trace messages into this file descriptor.
589 +
590 Alternatively, if the variable is set to an absolute path
591 (starting with a '/' character), Git will interpret this
592 as a file path and will try to write the trace messages
593 into it.
594 +
595 Unsetting the variable, or setting it to empty, "0" or
596 "false" (case insensitive) disables trace messages.
597
598 `GIT_TRACE_FSMONITOR`::
599 Enables trace messages for the filesystem monitor extension.
600 See `GIT_TRACE` for available trace output options.
601
602 `GIT_TRACE_PACK_ACCESS`::
603 Enables trace messages for all accesses to any packs. For each
604 access, the pack file name and an offset in the pack is
605 recorded. This may be helpful for troubleshooting some
606 pack-related performance problems.
607 See `GIT_TRACE` for available trace output options.
608
609 `GIT_TRACE_PACKET`::
610 Enables trace messages for all packets coming in or out of a
611 given program. This can help with debugging object negotiation
612 or other protocol issues. Tracing is turned off at a packet
613 starting with "PACK" (but see `GIT_TRACE_PACKFILE` below).
614 See `GIT_TRACE` for available trace output options.
615
616 `GIT_TRACE_PACKFILE`::
617 Enables tracing of packfiles sent or received by a
618 given program. Unlike other trace output, this trace is
619 verbatim: no headers, and no quoting of binary data. You almost
620 certainly want to direct into a file (e.g.,
621 `GIT_TRACE_PACKFILE=/tmp/my.pack`) rather than displaying it on
622 the terminal or mixing it with other trace output.
623 +
624 Note that this is currently only implemented for the client side
625 of clones and fetches.
626
627 `GIT_TRACE_PERFORMANCE`::
628 Enables performance related trace messages, e.g. total execution
629 time of each Git command.
630 See `GIT_TRACE` for available trace output options.
631
632 `GIT_TRACE_SETUP`::
633 Enables trace messages printing the .git, working tree and current
634 working directory after Git has completed its setup phase.
635 See `GIT_TRACE` for available trace output options.
636
637 `GIT_TRACE_SHALLOW`::
638 Enables trace messages that can help debugging fetching /
639 cloning of shallow repositories.
640 See `GIT_TRACE` for available trace output options.
641
642 `GIT_TRACE_CURL`::
643 Enables a curl full trace dump of all incoming and outgoing data,
644 including descriptive information, of the git transport protocol.
645 This is similar to doing curl `--trace-ascii` on the command line.
646 This option overrides setting the `GIT_CURL_VERBOSE` environment
647 variable.
648 See `GIT_TRACE` for available trace output options.
649
650 `GIT_LITERAL_PATHSPECS`::
651 Setting this variable to `1` will cause Git to treat all
652 pathspecs literally, rather than as glob patterns. For example,
653 running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search
654 for commits that touch the path `*.c`, not any paths that the
655 glob `*.c` matches. You might want this if you are feeding
656 literal paths to Git (e.g., paths previously given to you by
657 `git ls-tree`, `--raw` diff output, etc).
658
659 `GIT_GLOB_PATHSPECS`::
660 Setting this variable to `1` will cause Git to treat all
661 pathspecs as glob patterns (aka "glob" magic).
662
663 `GIT_NOGLOB_PATHSPECS`::
664 Setting this variable to `1` will cause Git to treat all
665 pathspecs as literal (aka "literal" magic).
666
667 `GIT_ICASE_PATHSPECS`::
668 Setting this variable to `1` will cause Git to treat all
669 pathspecs as case-insensitive.
670
671 `GIT_REFLOG_ACTION`::
672 When a ref is updated, reflog entries are created to keep
673 track of the reason why the ref was updated (which is
674 typically the name of the high-level command that updated
675 the ref), in addition to the old and new values of the ref.
676 A scripted Porcelain command can use set_reflog_action
677 helper function in `git-sh-setup` to set its name to this
678 variable when it is invoked as the top level command by the
679 end user, to be recorded in the body of the reflog.
680
681 `GIT_REF_PARANOIA`::
682 If set to `1`, include broken or badly named refs when iterating
683 over lists of refs. In a normal, non-corrupted repository, this
684 does nothing. However, enabling it may help git to detect and
685 abort some operations in the presence of broken refs. Git sets
686 this variable automatically when performing destructive
687 operations like linkgit:git-prune[1]. You should not need to set
688 it yourself unless you want to be paranoid about making sure
689 an operation has touched every ref (e.g., because you are
690 cloning a repository to make a backup).
691
692 `GIT_ALLOW_PROTOCOL`::
693 If set to a colon-separated list of protocols, behave as if
694 `protocol.allow` is set to `never`, and each of the listed
695 protocols has `protocol.<name>.allow` set to `always`
696 (overriding any existing configuration). In other words, any
697 protocol not mentioned will be disallowed (i.e., this is a
698 whitelist, not a blacklist). See the description of
699 `protocol.allow` in linkgit:git-config[1] for more details.
700
701 `GIT_PROTOCOL_FROM_USER`::
702 Set to 0 to prevent protocols used by fetch/push/clone which are
703 configured to the `user` state. This is useful to restrict recursive
704 submodule initialization from an untrusted repository or for programs
705 which feed potentially-untrusted URLS to git commands. See
706 linkgit:git-config[1] for more details.
707
708 `GIT_OPTIONAL_LOCKS`::
709 If set to `0`, Git will complete any requested operation without
710 performing any optional sub-operations that require taking a lock.
711 For example, this will prevent `git status` from refreshing the
712 index as a side effect. This is useful for processes running in
713 the background which do not want to cause lock contention with
714 other operations on the repository. Defaults to `1`.
715
716 `GIT_REDIRECT_STDIN`::
717 `GIT_REDIRECT_STDOUT`::
718 `GIT_REDIRECT_STDERR`::
719 Windows-only: allow redirecting the standard input/output/error
720 handles to paths specified by the environment variables. This is
721 particularly useful in multi-threaded applications where the
722 canonical way to pass standard handles via `CreateProcess()` is
723 not an option because it would require the handles to be marked
724 inheritable (and consequently *every* spawned process would
725 inherit them, possibly blocking regular Git operations). The
726 primary intended use case is to use named pipes for communication
727 (e.g. `\\.\pipe\my-git-stdin-123`).
728 +
729 Two special values are supported: `off` will simply close the
730 corresponding standard handle, and if `GIT_REDIRECT_STDERR` is
731 `2>&1`, standard error will be redirected to the same handle as
732 standard output.
733
734 Discussion[[Discussion]]
735 ------------------------
736
737 More detail on the following is available from the
738 link:user-manual.html#git-concepts[Git concepts chapter of the
739 user-manual] and linkgit:gitcore-tutorial[7].
740
741 A Git project normally consists of a working directory with a ".git"
742 subdirectory at the top level. The .git directory contains, among other
743 things, a compressed object database representing the complete history
744 of the project, an "index" file which links that history to the current
745 contents of the working tree, and named pointers into that history such
746 as tags and branch heads.
747
748 The object database contains objects of three main types: blobs, which
749 hold file data; trees, which point to blobs and other trees to build up
750 directory hierarchies; and commits, which each reference a single tree
751 and some number of parent commits.
752
753 The commit, equivalent to what other systems call a "changeset" or
754 "version", represents a step in the project's history, and each parent
755 represents an immediately preceding step. Commits with more than one
756 parent represent merges of independent lines of development.
757
758 All objects are named by the SHA-1 hash of their contents, normally
759 written as a string of 40 hex digits. Such names are globally unique.
760 The entire history leading up to a commit can be vouched for by signing
761 just that commit. A fourth object type, the tag, is provided for this
762 purpose.
763
764 When first created, objects are stored in individual files, but for
765 efficiency may later be compressed together into "pack files".
766
767 Named pointers called refs mark interesting points in history. A ref
768 may contain the SHA-1 name of an object or the name of another ref. Refs
769 with names beginning `ref/head/` contain the SHA-1 name of the most
770 recent commit (or "head") of a branch under development. SHA-1 names of
771 tags of interest are stored under `ref/tags/`. A special ref named
772 `HEAD` contains the name of the currently checked-out branch.
773
774 The index file is initialized with a list of all paths and, for each
775 path, a blob object and a set of attributes. The blob object represents
776 the contents of the file as of the head of the current branch. The
777 attributes (last modified time, size, etc.) are taken from the
778 corresponding file in the working tree. Subsequent changes to the
779 working tree can be found by comparing these attributes. The index may
780 be updated with new content, and new commits may be created from the
781 content stored in the index.
782
783 The index is also capable of storing multiple entries (called "stages")
784 for a given pathname. These stages are used to hold the various
785 unmerged version of a file when a merge is in progress.
786
787 FURTHER DOCUMENTATION
788 ---------------------
789
790 See the references in the "description" section to get started
791 using Git. The following is probably more detail than necessary
792 for a first-time user.
793
794 The link:user-manual.html#git-concepts[Git concepts chapter of the
795 user-manual] and linkgit:gitcore-tutorial[7] both provide
796 introductions to the underlying Git architecture.
797
798 See linkgit:gitworkflows[7] for an overview of recommended workflows.
799
800 See also the link:howto-index.html[howto] documents for some useful
801 examples.
802
803 The internals are documented in the
804 link:technical/api-index.html[Git API documentation].
805
806 Users migrating from CVS may also want to
807 read linkgit:gitcvs-migration[7].
808
809
810 Authors
811 -------
812 Git was started by Linus Torvalds, and is currently maintained by Junio
813 C Hamano. Numerous contributions have come from the Git mailing list
814 <git@vger.kernel.org>. http://www.openhub.net/p/git/contributors/summary
815 gives you a more complete list of contributors.
816
817 If you have a clone of git.git itself, the
818 output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you
819 the authors for specific parts of the project.
820
821 Reporting Bugs
822 --------------
823
824 Report bugs to the Git mailing list <git@vger.kernel.org> where the
825 development and maintenance is primarily done. You do not have to be
826 subscribed to the list to send a message there.
827
828 SEE ALSO
829 --------
830 linkgit:gittutorial[7], linkgit:gittutorial-2[7],
831 linkgit:giteveryday[7], linkgit:gitcvs-migration[7],
832 linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
833 linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],
834 linkgit:gitworkflows[7]
835
836 GIT
837 ---
838 Part of the linkgit:git[1] suite