Merge branch 'ls/git-gui-no-double-utf8-author-name'
[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-line parameters passed to the configured command are
526 determined by the ssh variant. See `ssh.variant` option in
527 linkgit:git-config[1] for details.
528
529 +
530 `$GIT_SSH_COMMAND` takes precedence over `$GIT_SSH`, and is interpreted
531 by the shell, which allows additional arguments to be included.
532 `$GIT_SSH` on the other hand must be just the path to a program
533 (which can be a wrapper shell script, if additional arguments are
534 needed).
535 +
536 Usually it is easier to configure any desired options through your
537 personal `.ssh/config` file. Please consult your ssh documentation
538 for further details.
539
540 `GIT_SSH_VARIANT`::
541 If this environment variable is set, it overrides Git's autodetection
542 whether `GIT_SSH`/`GIT_SSH_COMMAND`/`core.sshCommand` refer to OpenSSH,
543 plink or tortoiseplink. This variable overrides the config setting
544 `ssh.variant` that serves the same purpose.
545
546 `GIT_ASKPASS`::
547 If this environment variable is set, then Git commands which need to
548 acquire passwords or passphrases (e.g. for HTTP or IMAP authentication)
549 will call this program with a suitable prompt as command-line argument
550 and read the password from its STDOUT. See also the `core.askPass`
551 option in linkgit:git-config[1].
552
553 `GIT_TERMINAL_PROMPT`::
554 If this environment variable is set to `0`, git will not prompt
555 on the terminal (e.g., when asking for HTTP authentication).
556
557 `GIT_CONFIG_NOSYSTEM`::
558 Whether to skip reading settings from the system-wide
559 `$(prefix)/etc/gitconfig` file. This environment variable can
560 be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a
561 predictable environment for a picky script, or you can set it
562 temporarily to avoid using a buggy `/etc/gitconfig` file while
563 waiting for someone with sufficient permissions to fix it.
564
565 `GIT_FLUSH`::
566 If this environment variable is set to "1", then commands such
567 as 'git blame' (in incremental mode), 'git rev-list', 'git log',
568 'git check-attr' and 'git check-ignore' will
569 force a flush of the output stream after each record have been
570 flushed. If this
571 variable is set to "0", the output of these commands will be done
572 using completely buffered I/O. If this environment variable is
573 not set, Git will choose buffered or record-oriented flushing
574 based on whether stdout appears to be redirected to a file or not.
575
576 `GIT_TRACE`::
577 Enables general trace messages, e.g. alias expansion, built-in
578 command execution and external command execution.
579 +
580 If this variable is set to "1", "2" or "true" (comparison
581 is case insensitive), trace messages will be printed to
582 stderr.
583 +
584 If the variable is set to an integer value greater than 2
585 and lower than 10 (strictly) then Git will interpret this
586 value as an open file descriptor and will try to write the
587 trace messages into this file descriptor.
588 +
589 Alternatively, if the variable is set to an absolute path
590 (starting with a '/' character), Git will interpret this
591 as a file path and will try to write the trace messages
592 into it.
593 +
594 Unsetting the variable, or setting it to empty, "0" or
595 "false" (case insensitive) disables trace messages.
596
597 `GIT_TRACE_FSMONITOR`::
598 Enables trace messages for the filesystem monitor extension.
599 See `GIT_TRACE` for available trace output options.
600
601 `GIT_TRACE_PACK_ACCESS`::
602 Enables trace messages for all accesses to any packs. For each
603 access, the pack file name and an offset in the pack is
604 recorded. This may be helpful for troubleshooting some
605 pack-related performance problems.
606 See `GIT_TRACE` for available trace output options.
607
608 `GIT_TRACE_PACKET`::
609 Enables trace messages for all packets coming in or out of a
610 given program. This can help with debugging object negotiation
611 or other protocol issues. Tracing is turned off at a packet
612 starting with "PACK" (but see `GIT_TRACE_PACKFILE` below).
613 See `GIT_TRACE` for available trace output options.
614
615 `GIT_TRACE_PACKFILE`::
616 Enables tracing of packfiles sent or received by a
617 given program. Unlike other trace output, this trace is
618 verbatim: no headers, and no quoting of binary data. You almost
619 certainly want to direct into a file (e.g.,
620 `GIT_TRACE_PACKFILE=/tmp/my.pack`) rather than displaying it on
621 the terminal or mixing it with other trace output.
622 +
623 Note that this is currently only implemented for the client side
624 of clones and fetches.
625
626 `GIT_TRACE_PERFORMANCE`::
627 Enables performance related trace messages, e.g. total execution
628 time of each Git command.
629 See `GIT_TRACE` for available trace output options.
630
631 `GIT_TRACE_SETUP`::
632 Enables trace messages printing the .git, working tree and current
633 working directory after Git has completed its setup phase.
634 See `GIT_TRACE` for available trace output options.
635
636 `GIT_TRACE_SHALLOW`::
637 Enables trace messages that can help debugging fetching /
638 cloning of shallow repositories.
639 See `GIT_TRACE` for available trace output options.
640
641 `GIT_TRACE_CURL`::
642 Enables a curl full trace dump of all incoming and outgoing data,
643 including descriptive information, of the git transport protocol.
644 This is similar to doing curl `--trace-ascii` on the command line.
645 This option overrides setting the `GIT_CURL_VERBOSE` environment
646 variable.
647 See `GIT_TRACE` for available trace output options.
648
649 `GIT_LITERAL_PATHSPECS`::
650 Setting this variable to `1` will cause Git to treat all
651 pathspecs literally, rather than as glob patterns. For example,
652 running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search
653 for commits that touch the path `*.c`, not any paths that the
654 glob `*.c` matches. You might want this if you are feeding
655 literal paths to Git (e.g., paths previously given to you by
656 `git ls-tree`, `--raw` diff output, etc).
657
658 `GIT_GLOB_PATHSPECS`::
659 Setting this variable to `1` will cause Git to treat all
660 pathspecs as glob patterns (aka "glob" magic).
661
662 `GIT_NOGLOB_PATHSPECS`::
663 Setting this variable to `1` will cause Git to treat all
664 pathspecs as literal (aka "literal" magic).
665
666 `GIT_ICASE_PATHSPECS`::
667 Setting this variable to `1` will cause Git to treat all
668 pathspecs as case-insensitive.
669
670 `GIT_REFLOG_ACTION`::
671 When a ref is updated, reflog entries are created to keep
672 track of the reason why the ref was updated (which is
673 typically the name of the high-level command that updated
674 the ref), in addition to the old and new values of the ref.
675 A scripted Porcelain command can use set_reflog_action
676 helper function in `git-sh-setup` to set its name to this
677 variable when it is invoked as the top level command by the
678 end user, to be recorded in the body of the reflog.
679
680 `GIT_REF_PARANOIA`::
681 If set to `1`, include broken or badly named refs when iterating
682 over lists of refs. In a normal, non-corrupted repository, this
683 does nothing. However, enabling it may help git to detect and
684 abort some operations in the presence of broken refs. Git sets
685 this variable automatically when performing destructive
686 operations like linkgit:git-prune[1]. You should not need to set
687 it yourself unless you want to be paranoid about making sure
688 an operation has touched every ref (e.g., because you are
689 cloning a repository to make a backup).
690
691 `GIT_ALLOW_PROTOCOL`::
692 If set to a colon-separated list of protocols, behave as if
693 `protocol.allow` is set to `never`, and each of the listed
694 protocols has `protocol.<name>.allow` set to `always`
695 (overriding any existing configuration). In other words, any
696 protocol not mentioned will be disallowed (i.e., this is a
697 whitelist, not a blacklist). See the description of
698 `protocol.allow` in linkgit:git-config[1] for more details.
699
700 `GIT_PROTOCOL_FROM_USER`::
701 Set to 0 to prevent protocols used by fetch/push/clone which are
702 configured to the `user` state. This is useful to restrict recursive
703 submodule initialization from an untrusted repository or for programs
704 which feed potentially-untrusted URLS to git commands. See
705 linkgit:git-config[1] for more details.
706
707 `GIT_PROTOCOL`::
708 For internal use only. Used in handshaking the wire protocol.
709 Contains a colon ':' separated list of keys with optional values
710 'key[=value]'. Presence of unknown keys and values must be
711 ignored.
712
713 `GIT_OPTIONAL_LOCKS`::
714 If set to `0`, Git will complete any requested operation without
715 performing any optional sub-operations that require taking a lock.
716 For example, this will prevent `git status` from refreshing the
717 index as a side effect. This is useful for processes running in
718 the background which do not want to cause lock contention with
719 other operations on the repository. Defaults to `1`.
720
721 `GIT_REDIRECT_STDIN`::
722 `GIT_REDIRECT_STDOUT`::
723 `GIT_REDIRECT_STDERR`::
724 Windows-only: allow redirecting the standard input/output/error
725 handles to paths specified by the environment variables. This is
726 particularly useful in multi-threaded applications where the
727 canonical way to pass standard handles via `CreateProcess()` is
728 not an option because it would require the handles to be marked
729 inheritable (and consequently *every* spawned process would
730 inherit them, possibly blocking regular Git operations). The
731 primary intended use case is to use named pipes for communication
732 (e.g. `\\.\pipe\my-git-stdin-123`).
733 +
734 Two special values are supported: `off` will simply close the
735 corresponding standard handle, and if `GIT_REDIRECT_STDERR` is
736 `2>&1`, standard error will be redirected to the same handle as
737 standard output.
738
739 Discussion[[Discussion]]
740 ------------------------
741
742 More detail on the following is available from the
743 link:user-manual.html#git-concepts[Git concepts chapter of the
744 user-manual] and linkgit:gitcore-tutorial[7].
745
746 A Git project normally consists of a working directory with a ".git"
747 subdirectory at the top level. The .git directory contains, among other
748 things, a compressed object database representing the complete history
749 of the project, an "index" file which links that history to the current
750 contents of the working tree, and named pointers into that history such
751 as tags and branch heads.
752
753 The object database contains objects of three main types: blobs, which
754 hold file data; trees, which point to blobs and other trees to build up
755 directory hierarchies; and commits, which each reference a single tree
756 and some number of parent commits.
757
758 The commit, equivalent to what other systems call a "changeset" or
759 "version", represents a step in the project's history, and each parent
760 represents an immediately preceding step. Commits with more than one
761 parent represent merges of independent lines of development.
762
763 All objects are named by the SHA-1 hash of their contents, normally
764 written as a string of 40 hex digits. Such names are globally unique.
765 The entire history leading up to a commit can be vouched for by signing
766 just that commit. A fourth object type, the tag, is provided for this
767 purpose.
768
769 When first created, objects are stored in individual files, but for
770 efficiency may later be compressed together into "pack files".
771
772 Named pointers called refs mark interesting points in history. A ref
773 may contain the SHA-1 name of an object or the name of another ref. Refs
774 with names beginning `ref/head/` contain the SHA-1 name of the most
775 recent commit (or "head") of a branch under development. SHA-1 names of
776 tags of interest are stored under `ref/tags/`. A special ref named
777 `HEAD` contains the name of the currently checked-out branch.
778
779 The index file is initialized with a list of all paths and, for each
780 path, a blob object and a set of attributes. The blob object represents
781 the contents of the file as of the head of the current branch. The
782 attributes (last modified time, size, etc.) are taken from the
783 corresponding file in the working tree. Subsequent changes to the
784 working tree can be found by comparing these attributes. The index may
785 be updated with new content, and new commits may be created from the
786 content stored in the index.
787
788 The index is also capable of storing multiple entries (called "stages")
789 for a given pathname. These stages are used to hold the various
790 unmerged version of a file when a merge is in progress.
791
792 FURTHER DOCUMENTATION
793 ---------------------
794
795 See the references in the "description" section to get started
796 using Git. The following is probably more detail than necessary
797 for a first-time user.
798
799 The link:user-manual.html#git-concepts[Git concepts chapter of the
800 user-manual] and linkgit:gitcore-tutorial[7] both provide
801 introductions to the underlying Git architecture.
802
803 See linkgit:gitworkflows[7] for an overview of recommended workflows.
804
805 See also the link:howto-index.html[howto] documents for some useful
806 examples.
807
808 The internals are documented in the
809 link:technical/api-index.html[Git API documentation].
810
811 Users migrating from CVS may also want to
812 read linkgit:gitcvs-migration[7].
813
814
815 Authors
816 -------
817 Git was started by Linus Torvalds, and is currently maintained by Junio
818 C Hamano. Numerous contributions have come from the Git mailing list
819 <git@vger.kernel.org>. http://www.openhub.net/p/git/contributors/summary
820 gives you a more complete list of contributors.
821
822 If you have a clone of git.git itself, the
823 output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you
824 the authors for specific parts of the project.
825
826 Reporting Bugs
827 --------------
828
829 Report bugs to the Git mailing list <git@vger.kernel.org> where the
830 development and maintenance is primarily done. You do not have to be
831 subscribed to the list to send a message there.
832
833 SEE ALSO
834 --------
835 linkgit:gittutorial[7], linkgit:gittutorial-2[7],
836 linkgit:giteveryday[7], linkgit:gitcvs-migration[7],
837 linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
838 linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],
839 linkgit:gitworkflows[7]
840
841 GIT
842 ---
843 Part of the linkgit:git[1] suite