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