remote-bzr: add support for bzr repos
[git/mingw/j6t.git] / Documentation / git.txt
blob8438c076c3385246e5d381ce8323d50b6d72211a
1 git(1)
2 ======
4 NAME
5 ----
6 git - the stupid content tracker
9 SYNOPSIS
10 --------
11 [verse]
12 'git' [--version] [--help] [-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     <command> [<args>]
18 DESCRIPTION
19 -----------
20 Git is a fast, scalable, distributed revision control system with an
21 unusually rich command set that provides both high-level operations
22 and full access to internals.
24 See linkgit:gittutorial[7] to get started, then see
25 link:everyday.html[Everyday Git] for a useful minimum set of
26 commands.  The link:user-manual.html[Git User's Manual] has a more
27 in-depth introduction.
29 After you mastered the basic concepts, you can come back to this
30 page to learn what commands Git offers.  You can learn more about
31 individual Git commands with "git help command".  linkgit:gitcli[7]
32 manual page gives you an overview of the command line command syntax.
34 Formatted and hyperlinked version of the latest Git documentation
35 can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`.
37 ifdef::stalenotes[]
38 [NOTE]
39 ============
41 You are reading the documentation for the latest (possibly
42 unreleased) version of Git, that is available from 'master'
43 branch of the `git.git` repository.
44 Documentation for older releases are available here:
46 * link:v1.8.2.2/git.html[documentation for release 1.8.2.2]
48 * release notes for
49   link:RelNotes/1.8.2.2.txt[1.8.2.2].
50   link:RelNotes/1.8.2.1.txt[1.8.2.1].
51   link:RelNotes/1.8.2.txt[1.8.2].
53 * link:v1.8.1.6/git.html[documentation for release 1.8.1.6]
55 * release notes for
56   link:RelNotes/1.8.1.6.txt[1.8.1.6],
57   link:RelNotes/1.8.1.5.txt[1.8.1.5],
58   link:RelNotes/1.8.1.4.txt[1.8.1.4],
59   link:RelNotes/1.8.1.3.txt[1.8.1.3],
60   link:RelNotes/1.8.1.2.txt[1.8.1.2],
61   link:RelNotes/1.8.1.1.txt[1.8.1.1],
62   link:RelNotes/1.8.1.txt[1.8.1].
64 * link:v1.8.0.3/git.html[documentation for release 1.8.0.3]
66 * release notes for
67   link:RelNotes/1.8.0.3.txt[1.8.0.3],
68   link:RelNotes/1.8.0.2.txt[1.8.0.2],
69   link:RelNotes/1.8.0.1.txt[1.8.0.1],
70   link:RelNotes/1.8.0.txt[1.8.0].
72 * link:v1.7.12.4/git.html[documentation for release 1.7.12.4]
74 * release notes for
75   link:RelNotes/1.7.12.4.txt[1.7.12.4],
76   link:RelNotes/1.7.12.3.txt[1.7.12.3],
77   link:RelNotes/1.7.12.2.txt[1.7.12.2],
78   link:RelNotes/1.7.12.1.txt[1.7.12.1],
79   link:RelNotes/1.7.12.txt[1.7.12].
81 * link:v1.7.11.7/git.html[documentation for release 1.7.11.7]
83 * release notes for
84   link:RelNotes/1.7.11.7.txt[1.7.11.7],
85   link:RelNotes/1.7.11.6.txt[1.7.11.6],
86   link:RelNotes/1.7.11.5.txt[1.7.11.5],
87   link:RelNotes/1.7.11.4.txt[1.7.11.4],
88   link:RelNotes/1.7.11.3.txt[1.7.11.3],
89   link:RelNotes/1.7.11.2.txt[1.7.11.2],
90   link:RelNotes/1.7.11.1.txt[1.7.11.1],
91   link:RelNotes/1.7.11.txt[1.7.11].
93 * link:v1.7.10.5/git.html[documentation for release 1.7.10.5]
95 * release notes for
96   link:RelNotes/1.7.10.5.txt[1.7.10.5],
97   link:RelNotes/1.7.10.4.txt[1.7.10.4],
98   link:RelNotes/1.7.10.3.txt[1.7.10.3],
99   link:RelNotes/1.7.10.2.txt[1.7.10.2],
100   link:RelNotes/1.7.10.1.txt[1.7.10.1],
101   link:RelNotes/1.7.10.txt[1.7.10].
103 * link:v1.7.9.7/git.html[documentation for release 1.7.9.7]
105 * release notes for
106   link:RelNotes/1.7.9.7.txt[1.7.9.7],
107   link:RelNotes/1.7.9.6.txt[1.7.9.6],
108   link:RelNotes/1.7.9.5.txt[1.7.9.5],
109   link:RelNotes/1.7.9.4.txt[1.7.9.4],
110   link:RelNotes/1.7.9.3.txt[1.7.9.3],
111   link:RelNotes/1.7.9.2.txt[1.7.9.2],
112   link:RelNotes/1.7.9.1.txt[1.7.9.1],
113   link:RelNotes/1.7.9.txt[1.7.9].
115 * link:v1.7.8.6/git.html[documentation for release 1.7.8.6]
117 * release notes for
118   link:RelNotes/1.7.8.6.txt[1.7.8.6],
119   link:RelNotes/1.7.8.5.txt[1.7.8.5],
120   link:RelNotes/1.7.8.4.txt[1.7.8.4],
121   link:RelNotes/1.7.8.3.txt[1.7.8.3],
122   link:RelNotes/1.7.8.2.txt[1.7.8.2],
123   link:RelNotes/1.7.8.1.txt[1.7.8.1],
124   link:RelNotes/1.7.8.txt[1.7.8].
126 * link:v1.7.7.7/git.html[documentation for release 1.7.7.7]
128 * release notes for
129   link:RelNotes/1.7.7.7.txt[1.7.7.7],
130   link:RelNotes/1.7.7.6.txt[1.7.7.6],
131   link:RelNotes/1.7.7.5.txt[1.7.7.5],
132   link:RelNotes/1.7.7.4.txt[1.7.7.4],
133   link:RelNotes/1.7.7.3.txt[1.7.7.3],
134   link:RelNotes/1.7.7.2.txt[1.7.7.2],
135   link:RelNotes/1.7.7.1.txt[1.7.7.1],
136   link:RelNotes/1.7.7.txt[1.7.7].
138 * link:v1.7.6.6/git.html[documentation for release 1.7.6.6]
140 * release notes for
141   link:RelNotes/1.7.6.6.txt[1.7.6.6],
142   link:RelNotes/1.7.6.5.txt[1.7.6.5],
143   link:RelNotes/1.7.6.4.txt[1.7.6.4],
144   link:RelNotes/1.7.6.3.txt[1.7.6.3],
145   link:RelNotes/1.7.6.2.txt[1.7.6.2],
146   link:RelNotes/1.7.6.1.txt[1.7.6.1],
147   link:RelNotes/1.7.6.txt[1.7.6].
149 * link:v1.7.5.4/git.html[documentation for release 1.7.5.4]
151 * release notes for
152   link:RelNotes/1.7.5.4.txt[1.7.5.4],
153   link:RelNotes/1.7.5.3.txt[1.7.5.3],
154   link:RelNotes/1.7.5.2.txt[1.7.5.2],
155   link:RelNotes/1.7.5.1.txt[1.7.5.1],
156   link:RelNotes/1.7.5.txt[1.7.5].
158 * link:v1.7.4.5/git.html[documentation for release 1.7.4.5]
160 * release notes for
161   link:RelNotes/1.7.4.5.txt[1.7.4.5],
162   link:RelNotes/1.7.4.4.txt[1.7.4.4],
163   link:RelNotes/1.7.4.3.txt[1.7.4.3],
164   link:RelNotes/1.7.4.2.txt[1.7.4.2],
165   link:RelNotes/1.7.4.1.txt[1.7.4.1],
166   link:RelNotes/1.7.4.txt[1.7.4].
168 * link:v1.7.3.5/git.html[documentation for release 1.7.3.5]
170 * release notes for
171   link:RelNotes/1.7.3.5.txt[1.7.3.5],
172   link:RelNotes/1.7.3.4.txt[1.7.3.4],
173   link:RelNotes/1.7.3.3.txt[1.7.3.3],
174   link:RelNotes/1.7.3.2.txt[1.7.3.2],
175   link:RelNotes/1.7.3.1.txt[1.7.3.1],
176   link:RelNotes/1.7.3.txt[1.7.3].
178 * link:v1.7.2.5/git.html[documentation for release 1.7.2.5]
180 * release notes for
181   link:RelNotes/1.7.2.5.txt[1.7.2.5],
182   link:RelNotes/1.7.2.4.txt[1.7.2.4],
183   link:RelNotes/1.7.2.3.txt[1.7.2.3],
184   link:RelNotes/1.7.2.2.txt[1.7.2.2],
185   link:RelNotes/1.7.2.1.txt[1.7.2.1],
186   link:RelNotes/1.7.2.txt[1.7.2].
188 * link:v1.7.1.4/git.html[documentation for release 1.7.1.4]
190 * release notes for
191   link:RelNotes/1.7.1.4.txt[1.7.1.4],
192   link:RelNotes/1.7.1.3.txt[1.7.1.3],
193   link:RelNotes/1.7.1.2.txt[1.7.1.2],
194   link:RelNotes/1.7.1.1.txt[1.7.1.1],
195   link:RelNotes/1.7.1.txt[1.7.1].
197 * link:v1.7.0.9/git.html[documentation for release 1.7.0.9]
199 * release notes for
200   link:RelNotes/1.7.0.9.txt[1.7.0.9],
201   link:RelNotes/1.7.0.8.txt[1.7.0.8],
202   link:RelNotes/1.7.0.7.txt[1.7.0.7],
203   link:RelNotes/1.7.0.6.txt[1.7.0.6],
204   link:RelNotes/1.7.0.5.txt[1.7.0.5],
205   link:RelNotes/1.7.0.4.txt[1.7.0.4],
206   link:RelNotes/1.7.0.3.txt[1.7.0.3],
207   link:RelNotes/1.7.0.2.txt[1.7.0.2],
208   link:RelNotes/1.7.0.1.txt[1.7.0.1],
209   link:RelNotes/1.7.0.txt[1.7.0].
211 * link:v1.6.6.3/git.html[documentation for release 1.6.6.3]
213 * release notes for
214   link:RelNotes/1.6.6.3.txt[1.6.6.3],
215   link:RelNotes/1.6.6.2.txt[1.6.6.2],
216   link:RelNotes/1.6.6.1.txt[1.6.6.1],
217   link:RelNotes/1.6.6.txt[1.6.6].
219 * link:v1.6.5.9/git.html[documentation for release 1.6.5.9]
221 * release notes for
222   link:RelNotes/1.6.5.9.txt[1.6.5.9],
223   link:RelNotes/1.6.5.8.txt[1.6.5.8],
224   link:RelNotes/1.6.5.7.txt[1.6.5.7],
225   link:RelNotes/1.6.5.6.txt[1.6.5.6],
226   link:RelNotes/1.6.5.5.txt[1.6.5.5],
227   link:RelNotes/1.6.5.4.txt[1.6.5.4],
228   link:RelNotes/1.6.5.3.txt[1.6.5.3],
229   link:RelNotes/1.6.5.2.txt[1.6.5.2],
230   link:RelNotes/1.6.5.1.txt[1.6.5.1],
231   link:RelNotes/1.6.5.txt[1.6.5].
233 * link:v1.6.4.5/git.html[documentation for release 1.6.4.5]
235 * release notes for
236   link:RelNotes/1.6.4.5.txt[1.6.4.5],
237   link:RelNotes/1.6.4.4.txt[1.6.4.4],
238   link:RelNotes/1.6.4.3.txt[1.6.4.3],
239   link:RelNotes/1.6.4.2.txt[1.6.4.2],
240   link:RelNotes/1.6.4.1.txt[1.6.4.1],
241   link:RelNotes/1.6.4.txt[1.6.4].
243 * link:v1.6.3.4/git.html[documentation for release 1.6.3.4]
245 * release notes for
246   link:RelNotes/1.6.3.4.txt[1.6.3.4],
247   link:RelNotes/1.6.3.3.txt[1.6.3.3],
248   link:RelNotes/1.6.3.2.txt[1.6.3.2],
249   link:RelNotes/1.6.3.1.txt[1.6.3.1],
250   link:RelNotes/1.6.3.txt[1.6.3].
252 * release notes for
253   link:RelNotes/1.6.2.5.txt[1.6.2.5],
254   link:RelNotes/1.6.2.4.txt[1.6.2.4],
255   link:RelNotes/1.6.2.3.txt[1.6.2.3],
256   link:RelNotes/1.6.2.2.txt[1.6.2.2],
257   link:RelNotes/1.6.2.1.txt[1.6.2.1],
258   link:RelNotes/1.6.2.txt[1.6.2].
260 * link:v1.6.1.3/git.html[documentation for release 1.6.1.3]
262 * release notes for
263   link:RelNotes/1.6.1.3.txt[1.6.1.3],
264   link:RelNotes/1.6.1.2.txt[1.6.1.2],
265   link:RelNotes/1.6.1.1.txt[1.6.1.1],
266   link:RelNotes/1.6.1.txt[1.6.1].
268 * link:v1.6.0.6/git.html[documentation for release 1.6.0.6]
270 * release notes for
271   link:RelNotes/1.6.0.6.txt[1.6.0.6],
272   link:RelNotes/1.6.0.5.txt[1.6.0.5],
273   link:RelNotes/1.6.0.4.txt[1.6.0.4],
274   link:RelNotes/1.6.0.3.txt[1.6.0.3],
275   link:RelNotes/1.6.0.2.txt[1.6.0.2],
276   link:RelNotes/1.6.0.1.txt[1.6.0.1],
277   link:RelNotes/1.6.0.txt[1.6.0].
279 * link:v1.5.6.6/git.html[documentation for release 1.5.6.6]
281 * release notes for
282   link:RelNotes/1.5.6.6.txt[1.5.6.6],
283   link:RelNotes/1.5.6.5.txt[1.5.6.5],
284   link:RelNotes/1.5.6.4.txt[1.5.6.4],
285   link:RelNotes/1.5.6.3.txt[1.5.6.3],
286   link:RelNotes/1.5.6.2.txt[1.5.6.2],
287   link:RelNotes/1.5.6.1.txt[1.5.6.1],
288   link:RelNotes/1.5.6.txt[1.5.6].
290 * link:v1.5.5.6/git.html[documentation for release 1.5.5.6]
292 * release notes for
293   link:RelNotes/1.5.5.6.txt[1.5.5.6],
294   link:RelNotes/1.5.5.5.txt[1.5.5.5],
295   link:RelNotes/1.5.5.4.txt[1.5.5.4],
296   link:RelNotes/1.5.5.3.txt[1.5.5.3],
297   link:RelNotes/1.5.5.2.txt[1.5.5.2],
298   link:RelNotes/1.5.5.1.txt[1.5.5.1],
299   link:RelNotes/1.5.5.txt[1.5.5].
301 * link:v1.5.4.7/git.html[documentation for release 1.5.4.7]
303 * release notes for
304   link:RelNotes/1.5.4.7.txt[1.5.4.7],
305   link:RelNotes/1.5.4.6.txt[1.5.4.6],
306   link:RelNotes/1.5.4.5.txt[1.5.4.5],
307   link:RelNotes/1.5.4.4.txt[1.5.4.4],
308   link:RelNotes/1.5.4.3.txt[1.5.4.3],
309   link:RelNotes/1.5.4.2.txt[1.5.4.2],
310   link:RelNotes/1.5.4.1.txt[1.5.4.1],
311   link:RelNotes/1.5.4.txt[1.5.4].
313 * link:v1.5.3.8/git.html[documentation for release 1.5.3.8]
315 * release notes for
316   link:RelNotes/1.5.3.8.txt[1.5.3.8],
317   link:RelNotes/1.5.3.7.txt[1.5.3.7],
318   link:RelNotes/1.5.3.6.txt[1.5.3.6],
319   link:RelNotes/1.5.3.5.txt[1.5.3.5],
320   link:RelNotes/1.5.3.4.txt[1.5.3.4],
321   link:RelNotes/1.5.3.3.txt[1.5.3.3],
322   link:RelNotes/1.5.3.2.txt[1.5.3.2],
323   link:RelNotes/1.5.3.1.txt[1.5.3.1],
324   link:RelNotes/1.5.3.txt[1.5.3].
326 * link:v1.5.2.5/git.html[documentation for release 1.5.2.5]
328 * release notes for
329   link:RelNotes/1.5.2.5.txt[1.5.2.5],
330   link:RelNotes/1.5.2.4.txt[1.5.2.4],
331   link:RelNotes/1.5.2.3.txt[1.5.2.3],
332   link:RelNotes/1.5.2.2.txt[1.5.2.2],
333   link:RelNotes/1.5.2.1.txt[1.5.2.1],
334   link:RelNotes/1.5.2.txt[1.5.2].
336 * link:v1.5.1.6/git.html[documentation for release 1.5.1.6]
338 * release notes for
339   link:RelNotes/1.5.1.6.txt[1.5.1.6],
340   link:RelNotes/1.5.1.5.txt[1.5.1.5],
341   link:RelNotes/1.5.1.4.txt[1.5.1.4],
342   link:RelNotes/1.5.1.3.txt[1.5.1.3],
343   link:RelNotes/1.5.1.2.txt[1.5.1.2],
344   link:RelNotes/1.5.1.1.txt[1.5.1.1],
345   link:RelNotes/1.5.1.txt[1.5.1].
347 * link:v1.5.0.7/git.html[documentation for release 1.5.0.7]
349 * release notes for
350   link:RelNotes/1.5.0.7.txt[1.5.0.7],
351   link:RelNotes/1.5.0.6.txt[1.5.0.6],
352   link:RelNotes/1.5.0.5.txt[1.5.0.5],
353   link:RelNotes/1.5.0.3.txt[1.5.0.3],
354   link:RelNotes/1.5.0.2.txt[1.5.0.2],
355   link:RelNotes/1.5.0.1.txt[1.5.0.1],
356   link:RelNotes/1.5.0.txt[1.5.0].
358 * documentation for release link:v1.4.4.4/git.html[1.4.4.4],
359   link:v1.3.3/git.html[1.3.3],
360   link:v1.2.6/git.html[1.2.6],
361   link:v1.0.13/git.html[1.0.13].
363 ============
365 endif::stalenotes[]
367 OPTIONS
368 -------
369 --version::
370         Prints the Git suite version that the 'git' program came from.
372 --help::
373         Prints the synopsis and a list of the most commonly used
374         commands. If the option '--all' or '-a' is given then all
375         available commands are printed. If a Git command is named this
376         option will bring up the manual page for that command.
378 Other options are available to control how the manual page is
379 displayed. See linkgit:git-help[1] for more information,
380 because `git --help ...` is converted internally into `git
381 help ...`.
383 -c <name>=<value>::
384         Pass a configuration parameter to the command. The value
385         given will override values from configuration files.
386         The <name> is expected in the same format as listed by
387         'git config' (subkeys separated by dots).
389 --exec-path[=<path>]::
390         Path to wherever your core Git programs are installed.
391         This can also be controlled by setting the GIT_EXEC_PATH
392         environment variable. If no path is given, 'git' will print
393         the current setting and then exit.
395 --html-path::
396         Print the path, without trailing slash, where Git's HTML
397         documentation is installed and exit.
399 --man-path::
400         Print the manpath (see `man(1)`) for the man pages for
401         this version of Git and exit.
403 --info-path::
404         Print the path where the Info files documenting this
405         version of Git are installed and exit.
407 -p::
408 --paginate::
409         Pipe all output into 'less' (or if set, $PAGER) if standard
410         output is a terminal.  This overrides the `pager.<cmd>`
411         configuration options (see the "Configuration Mechanism" section
412         below).
414 --no-pager::
415         Do not pipe Git output into a pager.
417 --git-dir=<path>::
418         Set the path to the repository. This can also be controlled by
419         setting the GIT_DIR environment variable. It can be an absolute
420         path or relative path to current working directory.
422 --work-tree=<path>::
423         Set the path to the working tree. It can be an absolute path
424         or a path relative to the current working directory.
425         This can also be controlled by setting the GIT_WORK_TREE
426         environment variable and the core.worktree configuration
427         variable (see core.worktree in linkgit:git-config[1] for a
428         more detailed discussion).
430 --namespace=<path>::
431         Set the Git namespace.  See linkgit:gitnamespaces[7] for more
432         details.  Equivalent to setting the `GIT_NAMESPACE` environment
433         variable.
435 --bare::
436         Treat the repository as a bare repository.  If GIT_DIR
437         environment is not set, it is set to the current working
438         directory.
440 --no-replace-objects::
441         Do not use replacement refs to replace Git objects. See
442         linkgit:git-replace[1] for more information.
444 --literal-pathspecs::
445         Treat pathspecs literally, rather than as glob patterns. This is
446         equivalent to setting the `GIT_LITERAL_PATHSPECS` environment
447         variable to `1`.
450 GIT COMMANDS
451 ------------
453 We divide Git into high level ("porcelain") commands and low level
454 ("plumbing") commands.
456 High-level commands (porcelain)
457 -------------------------------
459 We separate the porcelain commands into the main commands and some
460 ancillary user utilities.
462 Main porcelain commands
463 ~~~~~~~~~~~~~~~~~~~~~~~
465 include::cmds-mainporcelain.txt[]
467 Ancillary Commands
468 ~~~~~~~~~~~~~~~~~~
469 Manipulators:
471 include::cmds-ancillarymanipulators.txt[]
473 Interrogators:
475 include::cmds-ancillaryinterrogators.txt[]
478 Interacting with Others
479 ~~~~~~~~~~~~~~~~~~~~~~~
481 These commands are to interact with foreign SCM and with other
482 people via patch over e-mail.
484 include::cmds-foreignscminterface.txt[]
487 Low-level commands (plumbing)
488 -----------------------------
490 Although Git includes its
491 own porcelain layer, its low-level commands are sufficient to support
492 development of alternative porcelains.  Developers of such porcelains
493 might start by reading about linkgit:git-update-index[1] and
494 linkgit:git-read-tree[1].
496 The interface (input, output, set of options and the semantics)
497 to these low-level commands are meant to be a lot more stable
498 than Porcelain level commands, because these commands are
499 primarily for scripted use.  The interface to Porcelain commands
500 on the other hand are subject to change in order to improve the
501 end user experience.
503 The following description divides
504 the low-level commands into commands that manipulate objects (in
505 the repository, index, and working tree), commands that interrogate and
506 compare objects, and commands that move objects and references between
507 repositories.
510 Manipulation commands
511 ~~~~~~~~~~~~~~~~~~~~~
513 include::cmds-plumbingmanipulators.txt[]
516 Interrogation commands
517 ~~~~~~~~~~~~~~~~~~~~~~
519 include::cmds-plumbinginterrogators.txt[]
521 In general, the interrogate commands do not touch the files in
522 the working tree.
525 Synching repositories
526 ~~~~~~~~~~~~~~~~~~~~~
528 include::cmds-synchingrepositories.txt[]
530 The following are helper commands used by the above; end users
531 typically do not use them directly.
533 include::cmds-synchelpers.txt[]
536 Internal helper commands
537 ~~~~~~~~~~~~~~~~~~~~~~~~
539 These are internal helper commands used by other commands; end
540 users typically do not use them directly.
542 include::cmds-purehelpers.txt[]
545 Configuration Mechanism
546 -----------------------
548 Git uses a simple text format to store customizations that are per
549 repository and are per user.  Such a configuration file may look
550 like this:
552 ------------
554 # A '#' or ';' character indicates a comment.
557 ; core variables
558 [core]
559         ; Don't trust file modes
560         filemode = false
562 ; user identity
563 [user]
564         name = "Junio C Hamano"
565         email = "gitster@pobox.com"
567 ------------
569 Various commands read from the configuration file and adjust
570 their operation accordingly.  See linkgit:git-config[1] for a
571 list and more details about the configuration mechanism.
574 Identifier Terminology
575 ----------------------
576 <object>::
577         Indicates the object name for any type of object.
579 <blob>::
580         Indicates a blob object name.
582 <tree>::
583         Indicates a tree object name.
585 <commit>::
586         Indicates a commit object name.
588 <tree-ish>::
589         Indicates a tree, commit or tag object name.  A
590         command that takes a <tree-ish> argument ultimately wants to
591         operate on a <tree> object but automatically dereferences
592         <commit> and <tag> objects that point at a <tree>.
594 <commit-ish>::
595         Indicates a commit or tag object name.  A
596         command that takes a <commit-ish> argument ultimately wants to
597         operate on a <commit> object but automatically dereferences
598         <tag> objects that point at a <commit>.
600 <type>::
601         Indicates that an object type is required.
602         Currently one of: `blob`, `tree`, `commit`, or `tag`.
604 <file>::
605         Indicates a filename - almost always relative to the
606         root of the tree structure `GIT_INDEX_FILE` describes.
608 Symbolic Identifiers
609 --------------------
610 Any Git command accepting any <object> can also use the following
611 symbolic notation:
613 HEAD::
614         indicates the head of the current branch.
616 <tag>::
617         a valid tag 'name'
618         (i.e. a `refs/tags/<tag>` reference).
620 <head>::
621         a valid head 'name'
622         (i.e. a `refs/heads/<head>` reference).
624 For a more complete list of ways to spell object names, see
625 "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
628 File/Directory Structure
629 ------------------------
631 Please see the linkgit:gitrepository-layout[5] document.
633 Read linkgit:githooks[5] for more details about each hook.
635 Higher level SCMs may provide and manage additional information in the
636 `$GIT_DIR`.
639 Terminology
640 -----------
641 Please see linkgit:gitglossary[7].
644 Environment Variables
645 ---------------------
646 Various Git commands use the following environment variables:
648 The Git Repository
649 ~~~~~~~~~~~~~~~~~~
650 These environment variables apply to 'all' core Git commands. Nb: it
651 is worth noting that they may be used/overridden by SCMS sitting above
652 Git so take care if using Cogito etc.
654 'GIT_INDEX_FILE'::
655         This environment allows the specification of an alternate
656         index file. If not specified, the default of `$GIT_DIR/index`
657         is used.
659 'GIT_OBJECT_DIRECTORY'::
660         If the object storage directory is specified via this
661         environment variable then the sha1 directories are created
662         underneath - otherwise the default `$GIT_DIR/objects`
663         directory is used.
665 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
666         Due to the immutable nature of Git objects, old objects can be
667         archived into shared, read-only directories. This variable
668         specifies a ":" separated (on Windows ";" separated) list
669         of Git object directories which can be used to search for Git
670         objects. New objects will not be written to these directories.
672 'GIT_DIR'::
673         If the 'GIT_DIR' environment variable is set then it
674         specifies a path to use instead of the default `.git`
675         for the base of the repository.
676         The '--git-dir' command-line option also sets this value.
678 'GIT_WORK_TREE'::
679         Set the path to the working tree.  The value will not be
680         used in combination with repositories found automatically in
681         a .git directory (i.e. $GIT_DIR is not set).
682         This can also be controlled by the '--work-tree' command line
683         option and the core.worktree configuration variable.
685 'GIT_NAMESPACE'::
686         Set the Git namespace; see linkgit:gitnamespaces[7] for details.
687         The '--namespace' command-line option also sets this value.
689 'GIT_CEILING_DIRECTORIES'::
690         This should be a colon-separated list of absolute paths.  If
691         set, it is a list of directories that Git should not chdir up
692         into while looking for a repository directory (useful for
693         excluding slow-loading network directories).  It will not
694         exclude the current working directory or a GIT_DIR set on the
695         command line or in the environment.  Normally, Git has to read
696         the entries in this list and resolve any symlink that
697         might be present in order to compare them with the current
698         directory.  However, if even this access is slow, you
699         can add an empty entry to the list to tell Git that the
700         subsequent entries are not symlinks and needn't be resolved;
701         e.g.,
702         'GIT_CEILING_DIRECTORIES=/maybe/symlink::/very/slow/non/symlink'.
704 'GIT_DISCOVERY_ACROSS_FILESYSTEM'::
705         When run in a directory that does not have ".git" repository
706         directory, Git tries to find such a directory in the parent
707         directories to find the top of the working tree, but by default it
708         does not cross filesystem boundaries.  This environment variable
709         can be set to true to tell Git not to stop at filesystem
710         boundaries.  Like 'GIT_CEILING_DIRECTORIES', this will not affect
711         an explicit repository directory set via 'GIT_DIR' or on the
712         command line.
714 Git Commits
715 ~~~~~~~~~~~
716 'GIT_AUTHOR_NAME'::
717 'GIT_AUTHOR_EMAIL'::
718 'GIT_AUTHOR_DATE'::
719 'GIT_COMMITTER_NAME'::
720 'GIT_COMMITTER_EMAIL'::
721 'GIT_COMMITTER_DATE'::
722 'EMAIL'::
723         see linkgit:git-commit-tree[1]
725 Git Diffs
726 ~~~~~~~~~
727 'GIT_DIFF_OPTS'::
728         Only valid setting is "--unified=??" or "-u??" to set the
729         number of context lines shown when a unified diff is created.
730         This takes precedence over any "-U" or "--unified" option
731         value passed on the Git diff command line.
733 'GIT_EXTERNAL_DIFF'::
734         When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
735         program named by it is called, instead of the diff invocation
736         described above.  For a path that is added, removed, or modified,
737         'GIT_EXTERNAL_DIFF' is called with 7 parameters:
739         path old-file old-hex old-mode new-file new-hex new-mode
741 where:
743         <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
744                          contents of <old|new>,
745         <old|new>-hex:: are the 40-hexdigit SHA-1 hashes,
746         <old|new>-mode:: are the octal representation of the file modes.
748 The file parameters can point at the user's working file
749 (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
750 when a new file is added), or a temporary file (e.g. `old-file` in the
751 index).  'GIT_EXTERNAL_DIFF' should not worry about unlinking the
752 temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
754 For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
755 parameter, <path>.
757 other
758 ~~~~~
759 'GIT_MERGE_VERBOSITY'::
760         A number controlling the amount of output shown by
761         the recursive merge strategy.  Overrides merge.verbosity.
762         See linkgit:git-merge[1]
764 'GIT_PAGER'::
765         This environment variable overrides `$PAGER`. If it is set
766         to an empty string or to the value "cat", Git will not launch
767         a pager.  See also the `core.pager` option in
768         linkgit:git-config[1].
770 'GIT_EDITOR'::
771         This environment variable overrides `$EDITOR` and `$VISUAL`.
772         It is used by several Git commands when, on interactive mode,
773         an editor is to be launched. See also linkgit:git-var[1]
774         and the `core.editor` option in linkgit:git-config[1].
776 'GIT_SSH'::
777         If this environment variable is set then 'git fetch'
778         and 'git push' will use this command instead
779         of 'ssh' when they need to connect to a remote system.
780         The '$GIT_SSH' command will be given exactly two or
781         four arguments: the 'username@host' (or just 'host')
782         from the URL and the shell command to execute on that
783         remote system, optionally preceded by '-p' (literally) and
784         the 'port' from the URL when it specifies something other
785         than the default SSH port.
787 To pass options to the program that you want to list in GIT_SSH
788 you will need to wrap the program and options into a shell script,
789 then set GIT_SSH to refer to the shell script.
791 Usually it is easier to configure any desired options through your
792 personal `.ssh/config` file.  Please consult your ssh documentation
793 for further details.
795 'GIT_ASKPASS'::
796         If this environment variable is set, then Git commands which need to
797         acquire passwords or passphrases (e.g. for HTTP or IMAP authentication)
798         will call this program with a suitable prompt as command line argument
799         and read the password from its STDOUT. See also the 'core.askpass'
800         option in linkgit:git-config[1].
802 'GIT_CONFIG_NOSYSTEM'::
803         Whether to skip reading settings from the system-wide
804         `$(prefix)/etc/gitconfig` file.  This environment variable can
805         be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a
806         predictable environment for a picky script, or you can set it
807         temporarily to avoid using a buggy `/etc/gitconfig` file while
808         waiting for someone with sufficient permissions to fix it.
810 'GIT_FLUSH'::
811         If this environment variable is set to "1", then commands such
812         as 'git blame' (in incremental mode), 'git rev-list', 'git log',
813         and 'git whatchanged' will force a flush of the output stream
814         after each commit-oriented record have been flushed.   If this
815         variable is set to "0", the output of these commands will be done
816         using completely buffered I/O.   If this environment variable is
817         not set, Git will choose buffered or record-oriented flushing
818         based on whether stdout appears to be redirected to a file or not.
820 'GIT_TRACE'::
821         If this variable is set to "1", "2" or "true" (comparison
822         is case insensitive), Git will print `trace:` messages on
823         stderr telling about alias expansion, built-in command
824         execution and external command execution.
825         If this variable is set to an integer value greater than 1
826         and lower than 10 (strictly) then Git will interpret this
827         value as an open file descriptor and will try to write the
828         trace messages into this file descriptor.
829         Alternatively, if this variable is set to an absolute path
830         (starting with a '/' character), Git will interpret this
831         as a file path and will try to write the trace messages
832         into it.
834 GIT_LITERAL_PATHSPECS::
835         Setting this variable to `1` will cause Git to treat all
836         pathspecs literally, rather than as glob patterns. For example,
837         running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search
838         for commits that touch the path `*.c`, not any paths that the
839         glob `*.c` matches. You might want this if you are feeding
840         literal paths to Git (e.g., paths previously given to you by
841         `git ls-tree`, `--raw` diff output, etc).
844 Discussion[[Discussion]]
845 ------------------------
847 More detail on the following is available from the
848 link:user-manual.html#git-concepts[Git concepts chapter of the
849 user-manual] and linkgit:gitcore-tutorial[7].
851 A Git project normally consists of a working directory with a ".git"
852 subdirectory at the top level.  The .git directory contains, among other
853 things, a compressed object database representing the complete history
854 of the project, an "index" file which links that history to the current
855 contents of the working tree, and named pointers into that history such
856 as tags and branch heads.
858 The object database contains objects of three main types: blobs, which
859 hold file data; trees, which point to blobs and other trees to build up
860 directory hierarchies; and commits, which each reference a single tree
861 and some number of parent commits.
863 The commit, equivalent to what other systems call a "changeset" or
864 "version", represents a step in the project's history, and each parent
865 represents an immediately preceding step.  Commits with more than one
866 parent represent merges of independent lines of development.
868 All objects are named by the SHA-1 hash of their contents, normally
869 written as a string of 40 hex digits.  Such names are globally unique.
870 The entire history leading up to a commit can be vouched for by signing
871 just that commit.  A fourth object type, the tag, is provided for this
872 purpose.
874 When first created, objects are stored in individual files, but for
875 efficiency may later be compressed together into "pack files".
877 Named pointers called refs mark interesting points in history.  A ref
878 may contain the SHA-1 name of an object or the name of another ref.  Refs
879 with names beginning `ref/head/` contain the SHA-1 name of the most
880 recent commit (or "head") of a branch under development.  SHA-1 names of
881 tags of interest are stored under `ref/tags/`.  A special ref named
882 `HEAD` contains the name of the currently checked-out branch.
884 The index file is initialized with a list of all paths and, for each
885 path, a blob object and a set of attributes.  The blob object represents
886 the contents of the file as of the head of the current branch.  The
887 attributes (last modified time, size, etc.) are taken from the
888 corresponding file in the working tree.  Subsequent changes to the
889 working tree can be found by comparing these attributes.  The index may
890 be updated with new content, and new commits may be created from the
891 content stored in the index.
893 The index is also capable of storing multiple entries (called "stages")
894 for a given pathname.  These stages are used to hold the various
895 unmerged version of a file when a merge is in progress.
897 FURTHER DOCUMENTATION
898 ---------------------
900 See the references in the "description" section to get started
901 using Git.  The following is probably more detail than necessary
902 for a first-time user.
904 The link:user-manual.html#git-concepts[Git concepts chapter of the
905 user-manual] and linkgit:gitcore-tutorial[7] both provide
906 introductions to the underlying Git architecture.
908 See linkgit:gitworkflows[7] for an overview of recommended workflows.
910 See also the link:howto-index.html[howto] documents for some useful
911 examples.
913 The internals are documented in the
914 link:technical/api-index.html[Git API documentation].
916 Users migrating from CVS may also want to
917 read linkgit:gitcvs-migration[7].
920 Authors
921 -------
922 Git was started by Linus Torvalds, and is currently maintained by Junio
923 C Hamano. Numerous contributions have come from the Git mailing list
924 <git@vger.kernel.org>.  http://www.ohloh.net/p/git/contributors/summary
925 gives you a more complete list of contributors.
927 If you have a clone of git.git itself, the
928 output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you
929 the authors for specific parts of the project.
931 Reporting Bugs
932 --------------
934 Report bugs to the Git mailing list <git@vger.kernel.org> where the
935 development and maintenance is primarily done.  You do not have to be
936 subscribed to the list to send a message there.
938 SEE ALSO
939 --------
940 linkgit:gittutorial[7], linkgit:gittutorial-2[7],
941 link:everyday.html[Everyday Git], linkgit:gitcvs-migration[7],
942 linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
943 linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],
944 linkgit:gitworkflows[7]
948 Part of the linkgit:git[1] suite