blob: 9d8f236fe84cd02550b8cf08e835b2926e6c45f0 [file] [log] [blame]
Christian Couder9e1f0a82008-06-06 09:07:32 +02001git(1)
David Greaves2cf565c2005-05-10 22:32:30 +01002======
David Greaves2cf565c2005-05-10 22:32:30 +01003
4NAME
5----
6git - the stupid content tracker
7
8
9SYNOPSIS
10--------
Jonas Fonseca8b700042006-08-25 03:05:48 +020011[verse]
Markus Heidelberg89a56bf2009-04-05 04:15:16 +020012'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--html-path]
Matthieu Moy463a8492007-08-19 19:24:36 +020013 [-p|--paginate|--no-pager]
Matthias Lederhofer892c41b2007-06-06 09:10:42 +020014 [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE]
15 [--help] COMMAND [ARGS]
David Greaves2cf565c2005-05-10 22:32:30 +010016
17DESCRIPTION
18-----------
J. Bruce Fields23091e92006-04-02 17:54:34 -040019Git is a fast, scalable, distributed revision control system with an
20unusually rich command set that provides both high-level operations
21and full access to internals.
22
Jonathan Nieder6998e4d2008-06-30 17:01:21 -050023See linkgit:gittutorial[7] to get started, then see
J. Bruce Fields23091e92006-04-02 17:54:34 -040024link:everyday.html[Everyday Git] for a useful minimum set of commands, and
25"man git-commandname" for documentation of each command. CVS users may
Jonathan Nieder6998e4d2008-06-30 17:01:21 -050026also want to read linkgit:gitcvs-migration[7]. See
27the link:user-manual.html[Git User's Manual] for a more in-depth
J. Bruce Fieldsa1dc34f2007-05-07 01:01:42 -040028introduction.
David Greaves2cf565c2005-05-10 22:32:30 +010029
Petr Baudis4514ad42006-06-07 20:43:50 +020030The COMMAND is either a name of a Git command (see below) or an alias
Dan McGee5162e692007-12-29 00:20:38 -060031as defined in the configuration file (see linkgit:git-config[1]).
Petr Baudis4514ad42006-06-07 20:43:50 +020032
Jari Aalto34b604a2007-04-30 14:21:38 +030033Formatted and hyperlinked version of the latest git
34documentation can be viewed at
35`http://www.kernel.org/pub/software/scm/git/docs/`.
36
Junio C Hamano26cfcfb2007-02-13 15:15:05 -080037ifdef::stalenotes[]
38[NOTE]
39============
Junio C Hamano26cfcfb2007-02-13 15:15:05 -080040
Junio C Hamano2ff3f612007-05-18 21:43:13 -070041You are reading the documentation for the latest (possibly
42unreleased) version of git, that is available from 'master'
43branch of the `git.git` repository.
44Documentation for older releases are available here:
Junio C Hamano43a8e4f2007-03-28 15:40:17 -070045
Junio C Hamanof01f1092009-05-06 17:13:27 -070046* link:v1.6.3/git.html[documentation for release 1.6.3]
Junio C Hamanoa95148d2009-03-03 23:02:16 -080047
48* release notes for
Junio C Hamanof01f1092009-05-06 17:13:27 -070049 link:RelNotes-1.6.2.5.txt[1.6.2.5],
50 link:RelNotes-1.6.2.4.txt[1.6.2.4],
Junio C Hamanoc965c022009-04-12 17:05:55 -070051 link:RelNotes-1.6.2.3.txt[1.6.2.3],
Nanako Shiraishi54a47492009-04-10 09:34:40 +090052 link:RelNotes-1.6.2.2.txt[1.6.2.2],
Junio C Hamanode769782009-03-15 13:10:10 -070053 link:RelNotes-1.6.2.1.txt[1.6.2.1],
Junio C Hamanoa95148d2009-03-03 23:02:16 -080054 link:RelNotes-1.6.2.txt[1.6.2].
55
Junio C Hamano621f1b42009-02-07 11:06:34 -080056* link:v1.6.1.3/git.html[documentation for release 1.6.1.3]
Junio C Hamano8104ebf2008-12-24 19:41:08 -080057
58* release notes for
Junio C Hamano621f1b42009-02-07 11:06:34 -080059 link:RelNotes-1.6.1.3.txt[1.6.1.3],
60 link:RelNotes-1.6.1.2.txt[1.6.1.2],
Junio C Hamanoc42b1ad2009-01-25 16:30:13 -080061 link:RelNotes-1.6.1.1.txt[1.6.1.1],
Junio C Hamano8104ebf2008-12-24 19:41:08 -080062 link:RelNotes-1.6.1.txt[1.6.1].
63
Junio C Hamanoefe05b02008-12-19 19:32:29 -080064* link:v1.6.0.6/git.html[documentation for release 1.6.0.6]
Junio C Hamanoea02eef2008-08-17 11:42:10 -070065
66* release notes for
Junio C Hamanoefe05b02008-12-19 19:32:29 -080067 link:RelNotes-1.6.0.6.txt[1.6.0.6],
Junio C Hamanof371d3e2008-12-07 17:34:14 -080068 link:RelNotes-1.6.0.5.txt[1.6.0.5],
Junio C Hamano171d7662008-11-12 15:04:54 -080069 link:RelNotes-1.6.0.4.txt[1.6.0.4],
70 link:RelNotes-1.6.0.3.txt[1.6.0.3],
Junio C Hamano97a7a822008-09-12 16:18:47 -070071 link:RelNotes-1.6.0.2.txt[1.6.0.2],
72 link:RelNotes-1.6.0.1.txt[1.6.0.1],
Junio C Hamanoea02eef2008-08-17 11:42:10 -070073 link:RelNotes-1.6.0.txt[1.6.0].
74
Junio C Hamanoefe05b02008-12-19 19:32:29 -080075* link:v1.5.6.6/git.html[documentation for release 1.5.6.6]
Junio C Hamanoe449f102008-06-18 13:09:43 -070076
77* release notes for
Junio C Hamanoefe05b02008-12-19 19:32:29 -080078 link:RelNotes-1.5.6.6.txt[1.5.6.6],
Junio C Hamano781c18342008-08-06 12:04:06 -070079 link:RelNotes-1.5.6.5.txt[1.5.6.5],
Junio C Hamano09651dd2008-07-19 15:52:12 -070080 link:RelNotes-1.5.6.4.txt[1.5.6.4],
81 link:RelNotes-1.5.6.3.txt[1.5.6.3],
82 link:RelNotes-1.5.6.2.txt[1.5.6.2],
83 link:RelNotes-1.5.6.1.txt[1.5.6.1],
Junio C Hamanoe6361062008-06-25 17:09:40 -070084 link:RelNotes-1.5.6.txt[1.5.6].
Junio C Hamanoe449f102008-06-18 13:09:43 -070085
Junio C Hamanoefe05b02008-12-19 19:32:29 -080086* link:v1.5.5.6/git.html[documentation for release 1.5.5.6]
Junio C Hamano1d2375d2008-04-07 21:57:43 -070087
88* release notes for
Junio C Hamanoefe05b02008-12-19 19:32:29 -080089 link:RelNotes-1.5.5.6.txt[1.5.5.6],
90 link:RelNotes-1.5.5.5.txt[1.5.5.5],
Junio C Hamano7064ca52008-06-07 11:45:48 -070091 link:RelNotes-1.5.5.4.txt[1.5.5.4],
Junio C Hamano28bc3022008-05-27 22:20:53 -070092 link:RelNotes-1.5.5.3.txt[1.5.5.3],
Junio C Hamano2d3922d2008-05-25 21:14:09 -070093 link:RelNotes-1.5.5.2.txt[1.5.5.2],
Junio C Hamano66aaa2f2008-04-20 11:36:53 -070094 link:RelNotes-1.5.5.1.txt[1.5.5.1],
Junio C Hamano1d2375d2008-04-07 21:57:43 -070095 link:RelNotes-1.5.5.txt[1.5.5].
96
Junio C Hamanoefe05b02008-12-19 19:32:29 -080097* link:v1.5.4.7/git.html[documentation for release 1.5.4.7]
Junio C Hamano6ce8e442008-02-01 20:40:30 -080098
99* release notes for
Junio C Hamanoefe05b02008-12-19 19:32:29 -0800100 link:RelNotes-1.5.4.7.txt[1.5.4.7],
101 link:RelNotes-1.5.4.6.txt[1.5.4.6],
Junio C Hamano803d5152008-03-27 20:43:51 -0700102 link:RelNotes-1.5.4.5.txt[1.5.4.5],
Junio C Hamanoad416ed2008-03-08 20:07:49 -0800103 link:RelNotes-1.5.4.4.txt[1.5.4.4],
Junio C Hamano923d44a2008-02-23 11:49:34 -0800104 link:RelNotes-1.5.4.3.txt[1.5.4.3],
Junio C Hamanocf5c51e2008-02-17 01:18:54 -0800105 link:RelNotes-1.5.4.2.txt[1.5.4.2],
Junio C Hamanoecb879f2008-02-11 19:21:23 -0800106 link:RelNotes-1.5.4.1.txt[1.5.4.1],
Junio C Hamano6ce8e442008-02-01 20:40:30 -0800107 link:RelNotes-1.5.4.txt[1.5.4].
108
Junio C Hamanoe708af62008-01-07 23:39:02 -0800109* link:v1.5.3.8/git.html[documentation for release 1.5.3.8]
Junio C Hamano5587cac2007-09-02 15:16:44 -0700110
111* release notes for
Junio C Hamanoe708af62008-01-07 23:39:02 -0800112 link:RelNotes-1.5.3.8.txt[1.5.3.8],
Junio C Hamanob52e9852007-12-01 12:48:19 -0800113 link:RelNotes-1.5.3.7.txt[1.5.3.7],
Junio C Hamano4a44b9e2007-11-18 15:15:47 -0800114 link:RelNotes-1.5.3.6.txt[1.5.3.6],
Junio C Hamanoafc05f92007-10-31 14:13:25 -0700115 link:RelNotes-1.5.3.5.txt[1.5.3.5],
Junio C Hamano58ba4f62007-10-04 01:35:01 -0700116 link:RelNotes-1.5.3.4.txt[1.5.3.4],
Junio C Hamano326df262007-09-30 17:32:25 -0700117 link:RelNotes-1.5.3.3.txt[1.5.3.3],
Junio C Hamano077d6f72007-09-19 03:21:35 -0700118 link:RelNotes-1.5.3.2.txt[1.5.3.2],
Junio C Hamano8d863c92007-10-23 12:10:55 -0700119 link:RelNotes-1.5.3.1.txt[1.5.3.1],
120 link:RelNotes-1.5.3.txt[1.5.3].
Junio C Hamanob6e4db62007-05-18 17:28:24 -0700121
Junio C Hamanoe6361062008-06-25 17:09:40 -0700122* link:v1.5.2.5/git.html[documentation for release 1.5.2.5]
123
Junio C Hamanoaba170c2007-05-20 00:30:39 -0700124* release notes for
Junio C Hamanoda899de2007-08-15 16:59:27 -0700125 link:RelNotes-1.5.2.5.txt[1.5.2.5],
Junio C Hamanobaafd6e2007-07-12 14:17:26 -0700126 link:RelNotes-1.5.2.4.txt[1.5.2.4],
Junio C Hamano444649e2007-07-02 01:14:00 -0700127 link:RelNotes-1.5.2.3.txt[1.5.2.3],
Junio C Hamano3e48af32007-06-16 09:10:18 -0700128 link:RelNotes-1.5.2.2.txt[1.5.2.2],
129 link:RelNotes-1.5.2.1.txt[1.5.2.1],
Junio C Hamanoaba170c2007-05-20 00:30:39 -0700130 link:RelNotes-1.5.2.txt[1.5.2].
131
132* link:v1.5.1.6/git.html[documentation for release 1.5.1.6]
133
134* release notes for
135 link:RelNotes-1.5.1.6.txt[1.5.1.6],
136 link:RelNotes-1.5.1.5.txt[1.5.1.5],
Junio C Hamano2ff3f612007-05-18 21:43:13 -0700137 link:RelNotes-1.5.1.4.txt[1.5.1.4],
138 link:RelNotes-1.5.1.3.txt[1.5.1.3],
139 link:RelNotes-1.5.1.2.txt[1.5.1.2],
140 link:RelNotes-1.5.1.1.txt[1.5.1.1],
141 link:RelNotes-1.5.1.txt[1.5.1].
Junio C Hamano467592e2007-05-08 23:47:35 -0700142
Junio C Hamano2ff3f612007-05-18 21:43:13 -0700143* link:v1.5.0.7/git.html[documentation for release 1.5.0.7]
Junio C Hamano467592e2007-05-08 23:47:35 -0700144
Junio C Hamanoaba170c2007-05-20 00:30:39 -0700145* release notes for
146 link:RelNotes-1.5.0.7.txt[1.5.0.7],
Junio C Hamano2ff3f612007-05-18 21:43:13 -0700147 link:RelNotes-1.5.0.6.txt[1.5.0.6],
148 link:RelNotes-1.5.0.5.txt[1.5.0.5],
149 link:RelNotes-1.5.0.3.txt[1.5.0.3],
150 link:RelNotes-1.5.0.2.txt[1.5.0.2],
151 link:RelNotes-1.5.0.1.txt[1.5.0.1],
152 link:RelNotes-1.5.0.txt[1.5.0].
Junio C Hamanofdd3e7d2007-04-21 23:51:27 -0700153
Junio C Hamano2ff3f612007-05-18 21:43:13 -0700154* documentation for release link:v1.4.4.4/git.html[1.4.4.4],
155 link:v1.3.3/git.html[1.3.3],
156 link:v1.2.6/git.html[1.2.6],
157 link:v1.0.13/git.html[1.0.13].
Junio C Hamano26cfcfb2007-02-13 15:15:05 -0800158
159============
160
161endif::stalenotes[]
162
Andreas Ericssoncb22bc42005-11-16 00:31:25 +0100163OPTIONS
164-------
165--version::
Fredrik Kuivinena87cd022006-03-09 17:24:19 +0100166 Prints the git suite version that the 'git' program came from.
David Greaves2cf565c2005-05-10 22:32:30 +0100167
Andreas Ericssoncb22bc42005-11-16 00:31:25 +0100168--help::
Fredrik Kuivinena87cd022006-03-09 17:24:19 +0100169 Prints the synopsis and a list of the most commonly used
Christian Couder0f6f1952007-12-04 06:44:29 +0100170 commands. If the option '--all' or '-a' is given then all
171 available commands are printed. If a git command is named this
172 option will bring up the manual page for that command.
Christian Couder45533d22007-12-04 06:44:29 +0100173+
174Other options are available to control how the manual page is
Dan McGee5162e692007-12-29 00:20:38 -0600175displayed. See linkgit:git-help[1] for more information,
Jonathan Niederdb5d6662008-07-03 01:06:23 -0500176because `git --help ...` is converted internally into `git
177help ...`.
Andreas Ericssoncb22bc42005-11-16 00:31:25 +0100178
179--exec-path::
Fredrik Kuivinena87cd022006-03-09 17:24:19 +0100180 Path to wherever your core git programs are installed.
Andreas Ericssoncb22bc42005-11-16 00:31:25 +0100181 This can also be controlled by setting the GIT_EXEC_PATH
Jonathan Nieder56992f72008-07-03 00:08:12 -0500182 environment variable. If no path is given, 'git' will print
Andreas Ericssoncb22bc42005-11-16 00:31:25 +0100183 the current setting and then exit.
184
Markus Heidelberg89a56bf2009-04-05 04:15:16 +0200185--html-path::
186 Print the path to wherever your git HTML documentation is installed
187 and exit.
188
Stephan Beyer32402402008-06-08 03:36:09 +0200189-p::
190--paginate::
Johannes Schindelin6acbcb92006-07-25 20:24:22 +0200191 Pipe all output into 'less' (or if set, $PAGER).
192
Matthieu Moy463a8492007-08-19 19:24:36 +0200193--no-pager::
194 Do not pipe git output into a pager.
195
Johannes Schindelin6acbcb92006-07-25 20:24:22 +0200196--git-dir=<path>::
197 Set the path to the repository. This can also be controlled by
Liu Yubao302cc112008-04-29 04:09:20 +0800198 setting the GIT_DIR environment variable. It can be an absolute
199 path or relative path to current working directory.
Johannes Schindelin6acbcb92006-07-25 20:24:22 +0200200
Matthias Lederhofer892c41b2007-06-06 09:10:42 +0200201--work-tree=<path>::
202 Set the path to the working tree. The value will not be
203 used in combination with repositories found automatically in
204 a .git directory (i.e. $GIT_DIR is not set).
205 This can also be controlled by setting the GIT_WORK_TREE
206 environment variable and the core.worktree configuration
Liu Yubao302cc112008-04-29 04:09:20 +0800207 variable. It can be an absolute path or relative path to
208 the directory specified by --git-dir or GIT_DIR.
209 Note: If --git-dir or GIT_DIR are specified but none of
210 --work-tree, GIT_WORK_TREE and core.worktree is specified,
211 the current working directory is regarded as the top directory
212 of your working tree.
Matthias Lederhofer892c41b2007-06-06 09:10:42 +0200213
Johannes Schindelin6acbcb92006-07-25 20:24:22 +0200214--bare::
Junio C Hamano9277d602007-08-27 22:41:23 -0700215 Treat the repository as a bare repository. If GIT_DIR
216 environment is not set, it is set to the current working
217 directory.
218
Junio C Hamano0d6a8732005-08-23 21:18:49 -0700219
J. Bruce Fields23091e92006-04-02 17:54:34 -0400220FURTHER DOCUMENTATION
221---------------------
Junio C Hamano9755afb2005-12-13 02:38:24 -0800222
J. Bruce Fields23091e92006-04-02 17:54:34 -0400223See the references above to get started using git. The following is
224probably more detail than necessary for a first-time user.
Junio C Hamano9755afb2005-12-13 02:38:24 -0800225
J. Bruce Fields40dac512007-09-03 00:01:19 -0400226The link:user-manual.html#git-concepts[git concepts chapter of the
Jonathan Nieder6998e4d2008-06-30 17:01:21 -0500227user-manual] and linkgit:gitcore-tutorial[7] both provide
J. Bruce Fields40dac512007-09-03 00:01:19 -0400228introductions to the underlying git architecture.
Junio C Hamano9755afb2005-12-13 02:38:24 -0800229
J. Bruce Fields23091e92006-04-02 17:54:34 -0400230See also the link:howto-index.html[howto] documents for some useful
231examples.
Junio C Hamano9755afb2005-12-13 02:38:24 -0800232
Jonathan Nieder6998e4d2008-06-30 17:01:21 -0500233The internals are documented in the
234link:technical/api-index.html[GIT API documentation].
Junio C Hamano530e7412007-11-24 23:48:04 -0800235
J. Bruce Fields23091e92006-04-02 17:54:34 -0400236GIT COMMANDS
237------------
Junio C Hamano8db93072005-08-30 13:51:01 -0700238
J. Bruce Fields23091e92006-04-02 17:54:34 -0400239We divide git into high level ("porcelain") commands and low level
240("plumbing") commands.
Junio C Hamanoe6fc2342005-08-25 00:28:18 -0700241
J. Bruce Fields23091e92006-04-02 17:54:34 -0400242High-level commands (porcelain)
243-------------------------------
244
245We separate the porcelain commands into the main commands and some
246ancillary user utilities.
247
248Main porcelain commands
249~~~~~~~~~~~~~~~~~~~~~~~
Junio C Hamano905197d2005-08-26 21:33:46 -0700250
Junio C Hamano377e8132007-01-18 15:03:13 -0800251include::cmds-mainporcelain.txt[]
Junio C Hamanoe31bb3b2005-08-15 15:48:47 -0700252
Yasushi SHOJI90933ef2005-08-16 00:23:06 +0900253Ancillary Commands
J. Bruce Fields23091e92006-04-02 17:54:34 -0400254~~~~~~~~~~~~~~~~~~
David Greaves204ee6a2005-05-10 22:32:37 +0100255Manipulators:
256
Junio C Hamano377e8132007-01-18 15:03:13 -0800257include::cmds-ancillarymanipulators.txt[]
Junio C Hamano7fc9d692005-08-23 01:49:47 -0700258
Junio C Hamanof85a4192005-08-29 17:21:06 -0700259Interrogators:
Junio C Hamano7fc9d692005-08-23 01:49:47 -0700260
Junio C Hamano377e8132007-01-18 15:03:13 -0800261include::cmds-ancillaryinterrogators.txt[]
Junio C Hamano35ef3a42005-09-07 23:04:52 -0700262
Junio C Hamano89bf2072007-01-18 22:32:38 -0800263
264Interacting with Others
265~~~~~~~~~~~~~~~~~~~~~~~
266
267These commands are to interact with foreign SCM and with other
268people via patch over e-mail.
269
270include::cmds-foreignscminterface.txt[]
271
272
Robin Rosenbergb1f33d62006-10-29 21:09:48 +0100273Low-level commands (plumbing)
274-----------------------------
275
276Although git includes its
277own porcelain layer, its low-level commands are sufficient to support
278development of alternative porcelains. Developers of such porcelains
Dan McGee5162e692007-12-29 00:20:38 -0600279might start by reading about linkgit:git-update-index[1] and
280linkgit:git-read-tree[1].
Robin Rosenbergb1f33d62006-10-29 21:09:48 +0100281
Junio C Hamano89bf2072007-01-18 22:32:38 -0800282The interface (input, output, set of options and the semantics)
283to these low-level commands are meant to be a lot more stable
284than Porcelain level commands, because these commands are
285primarily for scripted use. The interface to Porcelain commands
286on the other hand are subject to change in order to improve the
287end user experience.
288
289The following description divides
290the low-level commands into commands that manipulate objects (in
Robin Rosenbergb1f33d62006-10-29 21:09:48 +0100291the repository, index, and working tree), commands that interrogate and
292compare objects, and commands that move objects and references between
293repositories.
294
Junio C Hamano89bf2072007-01-18 22:32:38 -0800295
Robin Rosenbergb1f33d62006-10-29 21:09:48 +0100296Manipulation commands
297~~~~~~~~~~~~~~~~~~~~~
Robin Rosenbergb1f33d62006-10-29 21:09:48 +0100298
Junio C Hamano377e8132007-01-18 15:03:13 -0800299include::cmds-plumbingmanipulators.txt[]
Robin Rosenbergb1f33d62006-10-29 21:09:48 +0100300
301
302Interrogation commands
303~~~~~~~~~~~~~~~~~~~~~~
304
Junio C Hamano377e8132007-01-18 15:03:13 -0800305include::cmds-plumbinginterrogators.txt[]
Robin Rosenbergb1f33d62006-10-29 21:09:48 +0100306
307In general, the interrogate commands do not touch the files in
308the working tree.
309
310
311Synching repositories
312~~~~~~~~~~~~~~~~~~~~~
313
Junio C Hamano377e8132007-01-18 15:03:13 -0800314include::cmds-synchingrepositories.txt[]
Robin Rosenbergb1f33d62006-10-29 21:09:48 +0100315
Junio C Hamano89bf2072007-01-18 22:32:38 -0800316The following are helper programs used by the above; end users
317typically do not use them directly.
318
319include::cmds-synchelpers.txt[]
320
321
322Internal helper commands
323~~~~~~~~~~~~~~~~~~~~~~~~
324
325These are internal helper commands used by other commands; end
326users typically do not use them directly.
327
328include::cmds-purehelpers.txt[]
329
Robin Rosenbergb1f33d62006-10-29 21:09:48 +0100330
Junio C Hamano5773c9f2005-10-29 14:32:56 -0700331Configuration Mechanism
332-----------------------
333
Junio C Hamano2fa090b2005-12-07 16:05:21 -0800334Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
Junio C Hamano5773c9f2005-10-29 14:32:56 -0700335is used to hold per-repository configuration options. It is a
Pavel Roskinaddf88e2006-07-09 03:44:30 -0400336simple text file modeled after `.ini` format familiar to some
Junio C Hamano5773c9f2005-10-29 14:32:56 -0700337people. Here is an example:
338
339------------
340#
Junio C Hamano2fa090b2005-12-07 16:05:21 -0800341# A '#' or ';' character indicates a comment.
Junio C Hamano5773c9f2005-10-29 14:32:56 -0700342#
343
344; core variables
345[core]
346 ; Don't trust file modes
347 filemode = false
348
349; user identity
350[user]
351 name = "Junio C Hamano"
352 email = "junkio@twinsun.com"
353
354------------
355
356Various commands read from the configuration file and adjust
357their operation accordingly.
358
359
David Greaves6c84e2e2005-05-22 18:44:16 +0100360Identifier Terminology
David Greaves2cf565c2005-05-10 22:32:30 +0100361----------------------
362<object>::
Junio C Hamano2fa090b2005-12-07 16:05:21 -0800363 Indicates the object name for any type of object.
David Greaves2cf565c2005-05-10 22:32:30 +0100364
365<blob>::
Junio C Hamano2fa090b2005-12-07 16:05:21 -0800366 Indicates a blob object name.
David Greaves2cf565c2005-05-10 22:32:30 +0100367
368<tree>::
Junio C Hamano2fa090b2005-12-07 16:05:21 -0800369 Indicates a tree object name.
David Greaves2cf565c2005-05-10 22:32:30 +0100370
371<commit>::
Junio C Hamano2fa090b2005-12-07 16:05:21 -0800372 Indicates a commit object name.
David Greaves2cf565c2005-05-10 22:32:30 +0100373
374<tree-ish>::
Junio C Hamano2fa090b2005-12-07 16:05:21 -0800375 Indicates a tree, commit or tag object name. A
David Greaves6c84e2e2005-05-22 18:44:16 +0100376 command that takes a <tree-ish> argument ultimately wants to
377 operate on a <tree> object but automatically dereferences
378 <commit> and <tag> objects that point at a <tree>.
David Greaves2cf565c2005-05-10 22:32:30 +0100379
Theodore Ts'o043d7602007-03-05 14:46:05 -0500380<commit-ish>::
381 Indicates a commit or tag object name. A
382 command that takes a <commit-ish> argument ultimately wants to
383 operate on a <commit> object but automatically dereferences
384 <tag> objects that point at a <commit>.
385
David Greaves2cf565c2005-05-10 22:32:30 +0100386<type>::
387 Indicates that an object type is required.
Junio C Hamano2fa090b2005-12-07 16:05:21 -0800388 Currently one of: `blob`, `tree`, `commit`, or `tag`.
David Greaves2cf565c2005-05-10 22:32:30 +0100389
390<file>::
Junio C Hamano2fa090b2005-12-07 16:05:21 -0800391 Indicates a filename - almost always relative to the
392 root of the tree structure `GIT_INDEX_FILE` describes.
David Greaves2cf565c2005-05-10 22:32:30 +0100393
David Greavesc1bdacf2005-05-10 22:32:38 +0100394Symbolic Identifiers
395--------------------
Yasushi SHOJI90933ef2005-08-16 00:23:06 +0900396Any git command accepting any <object> can also use the following
David Greaves6c84e2e2005-05-22 18:44:16 +0100397symbolic notation:
David Greavesc1bdacf2005-05-10 22:32:38 +0100398
399HEAD::
Junio C Hamano2fa090b2005-12-07 16:05:21 -0800400 indicates the head of the current branch (i.e. the
401 contents of `$GIT_DIR/HEAD`).
402
David Greavesc1bdacf2005-05-10 22:32:38 +0100403<tag>::
Junio C Hamano2fa090b2005-12-07 16:05:21 -0800404 a valid tag 'name'
405 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
406
David Greavesc1bdacf2005-05-10 22:32:38 +0100407<head>::
Junio C Hamano2fa090b2005-12-07 16:05:21 -0800408 a valid head 'name'
409 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
410
Junio C Hamanod47107d2006-10-25 11:33:08 -0700411For a more complete list of ways to spell object names, see
Dan McGee5162e692007-12-29 00:20:38 -0600412"SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1].
Junio C Hamanod47107d2006-10-25 11:33:08 -0700413
David Greavesc1bdacf2005-05-10 22:32:38 +0100414
415File/Directory Structure
416------------------------
David Greavesc1bdacf2005-05-10 22:32:38 +0100417
Jonathan Nieder6998e4d2008-06-30 17:01:21 -0500418Please see the linkgit:gitrepository-layout[5] document.
David Greavesc1bdacf2005-05-10 22:32:38 +0100419
Jonathan Nieder6998e4d2008-06-30 17:01:21 -0500420Read linkgit:githooks[5] for more details about each hook.
Jon Loeliger6250ad12006-03-24 21:21:07 -0600421
David Greavesc1bdacf2005-05-10 22:32:38 +0100422Higher level SCMs may provide and manage additional information in the
Junio C Hamano2fa090b2005-12-07 16:05:21 -0800423`$GIT_DIR`.
David Greavesc1bdacf2005-05-10 22:32:38 +0100424
Junio C Hamanoa1d4aa72005-09-01 16:56:13 -0700425
David Greaves2cf565c2005-05-10 22:32:30 +0100426Terminology
427-----------
Jonathan Nieder6998e4d2008-06-30 17:01:21 -0500428Please see linkgit:gitglossary[7].
David Greaves2cf565c2005-05-10 22:32:30 +0100429
430
431Environment Variables
432---------------------
433Various git commands use the following environment variables:
434
David Greavesc1bdacf2005-05-10 22:32:38 +0100435The git Repository
436~~~~~~~~~~~~~~~~~~
437These environment variables apply to 'all' core git commands. Nb: it
438is worth noting that they may be used/overridden by SCMS sitting above
Junio C Hamano2fa090b2005-12-07 16:05:21 -0800439git so take care if using Cogito etc.
David Greaves2cf565c2005-05-10 22:32:30 +0100440
David Greavesc1bdacf2005-05-10 22:32:38 +0100441'GIT_INDEX_FILE'::
442 This environment allows the specification of an alternate
Lukas_Sandström5f3aa192005-11-11 02:12:27 +0100443 index file. If not specified, the default of `$GIT_DIR/index`
444 is used.
David Greavesc1bdacf2005-05-10 22:32:38 +0100445
446'GIT_OBJECT_DIRECTORY'::
447 If the object storage directory is specified via this
448 environment variable then the sha1 directories are created
449 underneath - otherwise the default `$GIT_DIR/objects`
450 directory is used.
451
452'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
453 Due to the immutable nature of git objects, old objects can be
454 archived into shared, read-only directories. This variable
Johannes Sixt80ba0742007-12-03 21:55:57 +0100455 specifies a ":" separated (on Windows ";" separated) list
456 of git object directories which can be used to search for git
457 objects. New objects will not be written to these directories.
David Greavesc1bdacf2005-05-10 22:32:38 +0100458
459'GIT_DIR'::
Junio C Hamano2fa090b2005-12-07 16:05:21 -0800460 If the 'GIT_DIR' environment variable is set then it
461 specifies a path to use instead of the default `.git`
462 for the base of the repository.
David Greavesc1bdacf2005-05-10 22:32:38 +0100463
Matthias Lederhofer892c41b2007-06-06 09:10:42 +0200464'GIT_WORK_TREE'::
465 Set the path to the working tree. The value will not be
466 used in combination with repositories found automatically in
467 a .git directory (i.e. $GIT_DIR is not set).
468 This can also be controlled by the '--work-tree' command line
469 option and the core.worktree configuration variable.
470
David Reiss0454dd92008-05-19 23:49:26 -0700471'GIT_CEILING_DIRECTORIES'::
472 This should be a colon-separated list of absolute paths.
473 If set, it is a list of directories that git should not chdir
474 up into while looking for a repository directory.
475 It will not exclude the current working directory or
476 a GIT_DIR set on the command line or in the environment.
477 (Useful for excluding slow-loading network directories.)
478
David Greavesc1bdacf2005-05-10 22:32:38 +0100479git Commits
480~~~~~~~~~~~
481'GIT_AUTHOR_NAME'::
482'GIT_AUTHOR_EMAIL'::
483'GIT_AUTHOR_DATE'::
484'GIT_COMMITTER_NAME'::
485'GIT_COMMITTER_EMAIL'::
Josh Triplett4e58bf92007-04-28 18:40:12 -0700486'GIT_COMMITTER_DATE'::
Josh Triplett28a94f82007-04-28 18:40:28 -0700487'EMAIL'::
Dan McGee5162e692007-12-29 00:20:38 -0600488 see linkgit:git-commit-tree[1]
David Greavesc1bdacf2005-05-10 22:32:38 +0100489
490git Diffs
491~~~~~~~~~
Junio C Hamanod81ed1b2005-05-10 20:54:57 -0700492'GIT_DIFF_OPTS'::
Seanfde97d82006-11-27 14:37:43 -0500493 Only valid setting is "--unified=??" or "-u??" to set the
494 number of context lines shown when a unified diff is created.
495 This takes precedence over any "-U" or "--unified" option
496 value passed on the git diff command line.
497
Junio C Hamanod81ed1b2005-05-10 20:54:57 -0700498'GIT_EXTERNAL_DIFF'::
Seanfde97d82006-11-27 14:37:43 -0500499 When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
500 program named by it is called, instead of the diff invocation
501 described above. For a path that is added, removed, or modified,
502 'GIT_EXTERNAL_DIFF' is called with 7 parameters:
503
504 path old-file old-hex old-mode new-file new-hex new-mode
505+
506where:
507
508 <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
509 contents of <old|new>,
510 <old|new>-hex:: are the 40-hexdigit SHA1 hashes,
511 <old|new>-mode:: are the octal representation of the file modes.
512
513+
514The file parameters can point at the user's working file
515(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
516when a new file is added), or a temporary file (e.g. `old-file` in the
517index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the
518temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
519+
520For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
521parameter, <path>.
David Greaves2cf565c2005-05-10 22:32:30 +0100522
Matthias Lederhofer575ba9d2006-06-25 15:56:18 +0200523other
524~~~~~
Jakub Narebskidbddb712007-07-13 01:54:06 +0200525'GIT_MERGE_VERBOSITY'::
526 A number controlling the amount of output shown by
527 the recursive merge strategy. Overrides merge.verbosity.
Dan McGee5162e692007-12-29 00:20:38 -0600528 See linkgit:git-merge[1]
Jakub Narebskidbddb712007-07-13 01:54:06 +0200529
Matthias Lederhoferc27d2052006-07-31 15:27:00 +0200530'GIT_PAGER'::
Steven Grimma7738c72007-07-19 03:43:51 -0700531 This environment variable overrides `$PAGER`. If it is set
532 to an empty string or to the value "cat", git will not launch
Jonathan Niederab54cd62008-08-24 00:28:32 -0500533 a pager. See also the `core.pager` option in
534 linkgit:git-config[1].
Matthias Lederhoferc27d2052006-07-31 15:27:00 +0200535
Shawn O. Pearced5538b42007-08-04 02:06:52 -0400536'GIT_SSH'::
Jonathan Niederba020ef2008-07-03 00:41:41 -0500537 If this environment variable is set then 'git-fetch'
538 and 'git-push' will use this command instead
Jonathan Nieder2fd02c92008-07-03 00:55:07 -0500539 of 'ssh' when they need to connect to a remote system.
Jonathan Nieder483bc4f2008-06-30 13:56:34 -0500540 The '$GIT_SSH' command will be given exactly two arguments:
Shawn O. Pearced5538b42007-08-04 02:06:52 -0400541 the 'username@host' (or just 'host') from the URL and the
542 shell command to execute on that remote system.
543+
544To pass options to the program that you want to list in GIT_SSH
545you will need to wrap the program and options into a shell script,
546then set GIT_SSH to refer to the shell script.
547+
548Usually it is easier to configure any desired options through your
549personal `.ssh/config` file. Please consult your ssh documentation
550for further details.
551
Theodore Ts'o06f59e92007-06-29 13:40:46 -0400552'GIT_FLUSH'::
553 If this environment variable is set to "1", then commands such
Jonathan Niederba020ef2008-07-03 00:41:41 -0500554 as 'git-blame' (in incremental mode), 'git-rev-list', 'git-log',
555 and 'git-whatchanged' will force a flush of the output stream
Theodore Ts'o06f59e92007-06-29 13:40:46 -0400556 after each commit-oriented record have been flushed. If this
557 variable is set to "0", the output of these commands will be done
558 using completely buffered I/O. If this environment variable is
559 not set, git will choose buffered or record-oriented flushing
560 based on whether stdout appears to be redirected to a file or not.
561
Matthias Lederhofer575ba9d2006-06-25 15:56:18 +0200562'GIT_TRACE'::
Christian Couder2886bdb2006-09-03 17:32:24 +0200563 If this variable is set to "1", "2" or "true" (comparison
564 is case insensitive), git will print `trace:` messages on
Matthias Lederhofer575ba9d2006-06-25 15:56:18 +0200565 stderr telling about alias expansion, built-in command
566 execution and external command execution.
Christian Couder2886bdb2006-09-03 17:32:24 +0200567 If this variable is set to an integer value greater than 1
568 and lower than 10 (strictly) then git will interpret this
569 value as an open file descriptor and will try to write the
570 trace messages into this file descriptor.
571 Alternatively, if this variable is set to an absolute path
572 (starting with a '/' character), git will interpret this
573 as a file path and will try to write the trace messages
574 into it.
Matthias Lederhofer575ba9d2006-06-25 15:56:18 +0200575
Junio C Hamano8db93072005-08-30 13:51:01 -0700576Discussion[[Discussion]]
577------------------------
J. Bruce Fields40dac512007-09-03 00:01:19 -0400578
579More detail on the following is available from the
580link:user-manual.html#git-concepts[git concepts chapter of the
Jonathan Nieder6998e4d2008-06-30 17:01:21 -0500581user-manual] and linkgit:gitcore-tutorial[7].
J. Bruce Fields40dac512007-09-03 00:01:19 -0400582
583A git project normally consists of a working directory with a ".git"
584subdirectory at the top level. The .git directory contains, among other
585things, a compressed object database representing the complete history
586of the project, an "index" file which links that history to the current
587contents of the working tree, and named pointers into that history such
588as tags and branch heads.
589
590The object database contains objects of three main types: blobs, which
591hold file data; trees, which point to blobs and other trees to build up
Ralf Wildenhues02ff6252007-12-18 07:07:36 +0100592directory hierarchies; and commits, which each reference a single tree
J. Bruce Fields40dac512007-09-03 00:01:19 -0400593and some number of parent commits.
594
595The commit, equivalent to what other systems call a "changeset" or
596"version", represents a step in the project's history, and each parent
597represents an immediately preceding step. Commits with more than one
598parent represent merges of independent lines of development.
599
600All objects are named by the SHA1 hash of their contents, normally
601written as a string of 40 hex digits. Such names are globally unique.
602The entire history leading up to a commit can be vouched for by signing
603just that commit. A fourth object type, the tag, is provided for this
604purpose.
605
606When first created, objects are stored in individual files, but for
607efficiency may later be compressed together into "pack files".
608
609Named pointers called refs mark interesting points in history. A ref
610may contain the SHA1 name of an object or the name of another ref. Refs
611with names beginning `ref/head/` contain the SHA1 name of the most
Ralf Wildenhues02ff6252007-12-18 07:07:36 +0100612recent commit (or "head") of a branch under development. SHA1 names of
J. Bruce Fields40dac512007-09-03 00:01:19 -0400613tags of interest are stored under `ref/tags/`. A special ref named
614`HEAD` contains the name of the currently checked-out branch.
615
616The index file is initialized with a list of all paths and, for each
617path, a blob object and a set of attributes. The blob object represents
618the contents of the file as of the head of the current branch. The
619attributes (last modified time, size, etc.) are taken from the
620corresponding file in the working tree. Subsequent changes to the
621working tree can be found by comparing these attributes. The index may
622be updated with new content, and new commits may be created from the
623content stored in the index.
624
625The index is also capable of storing multiple entries (called "stages")
626for a given pathname. These stages are used to hold the various
627unmerged version of a file when a merge is in progress.
David Greaves6c84e2e2005-05-22 18:44:16 +0100628
Andreas Ericssoncb22bc42005-11-16 00:31:25 +0100629Authors
630-------
Junio C Hamano9755afb2005-12-13 02:38:24 -0800631* git's founding father is Linus Torvalds <torvalds@osdl.org>.
Junio C Hamano947ad2e2007-09-01 04:09:51 -0700632* The current git nurse is Junio C Hamano <gitster@pobox.com>.
Junio C Hamano0240e212007-12-04 00:47:04 -0800633* The git potty was written by Andreas Ericsson <ae@op5.se>.
Junio C Hamano9755afb2005-12-13 02:38:24 -0800634* General upbringing is handled by the git-list <git@vger.kernel.org>.
David Greaves2cf565c2005-05-10 22:32:30 +0100635
636Documentation
637--------------
Junio C Hamano9755afb2005-12-13 02:38:24 -0800638The documentation for git suite was started by David Greaves
639<david@dgreaves.com>, and later enhanced greatly by the
640contributors on the git-list <git@vger.kernel.org>.
David Greaves2cf565c2005-05-10 22:32:30 +0100641
Christian Couder497c8332008-05-29 19:21:46 +0200642SEE ALSO
643--------
644linkgit:gittutorial[7], linkgit:gittutorial-2[7],
Jon Jensen5cbef012008-08-02 15:41:48 -0600645link:everyday.html[Everyday Git], linkgit:gitcvs-migration[7],
Christian Couder497c8332008-05-29 19:21:46 +0200646linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
Brian Gernhardtdc493082008-07-02 10:13:35 -0400647linkgit:gitcli[7], link:user-manual.html[The Git User's Manual]
Christian Couder497c8332008-05-29 19:21:46 +0200648
David Greaves2cf565c2005-05-10 22:32:30 +0100649GIT
650---
Christian Couder9e1f0a82008-06-06 09:07:32 +0200651Part of the linkgit:git[1] suite