Merge 1.5.0.7 in
[git/git.git] / Documentation / git.txt
CommitLineData
7984eabe 1git(7)
2cf565c5 2======
2cf565c5
DG
3
4NAME
5----
6git - the stupid content tracker
7
8
9SYNOPSIS
10--------
8b70004b 11[verse]
6acbcb92 12'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [-p|--paginate]
8b70004b 13 [--bare] [--git-dir=GIT_DIR] [--help] COMMAND [ARGS]
2cf565c5
DG
14
15DESCRIPTION
16-----------
23091e95
BF
17Git is a fast, scalable, distributed revision control system with an
18unusually rich command set that provides both high-level operations
19and full access to internals.
20
21See this link:tutorial.html[tutorial] to get started, then see
22link:everyday.html[Everyday Git] for a useful minimum set of commands, and
23"man git-commandname" for documentation of each command. CVS users may
24also want to read link:cvs-migration.html[CVS migration].
c0b4a003
JH
25link:user-manual.html[Git User's Manual] is still work in
26progress, but when finished hopefully it will guide a new user
27in a coherent way to git enlightenment ;-).
cb22bc44 28
4514ad4f 29The COMMAND is either a name of a Git command (see below) or an alias
e0d10e1c 30as defined in the configuration file (see gitlink:git-config[1]).
4514ad4f 31
26cfcfbf
JH
32ifdef::stalenotes[]
33[NOTE]
34============
35You are reading the documentation for the latest version of git.
36Documentation for older releases are available here:
37
43a8e4fe
JH
38* link:v1.5.0.6/git.html[documentation for release 1.5.0.6]
39
40* link:v1.5.0.6/RelNotes-1.5.0.6.txt[release notes for 1.5.0.6]
7976ce1b
JH
41
42* link:v1.5.0.5/RelNotes-1.5.0.5.txt[release notes for 1.5.0.5]
46d49472
JH
43
44* link:v1.5.0.3/RelNotes-1.5.0.3.txt[release notes for 1.5.0.3]
c260d790
JH
45
46* link:v1.5.0.2/RelNotes-1.5.0.2.txt[release notes for 1.5.0.2]
a53b12c3
JH
47
48* link:v1.5.0.1/RelNotes-1.5.0.1.txt[release notes for 1.5.0.1]
49
6132bd5c
JH
50* link:v1.5.0/RelNotes-1.5.0.txt[release notes for 1.5.0]
51
26cfcfbf
JH
52* link:v1.4.4.4/git.html[documentation for release 1.4.4.4]
53
54* link:v1.3.3/git.html[documentation for release 1.3.3]
55
56* link:v1.2.6/git.html[documentation for release 1.2.6]
57
58* link:v1.0.13/git.html[documentation for release 1.0.13]
59
60============
61
62endif::stalenotes[]
63
cb22bc44
AE
64OPTIONS
65-------
66--version::
a87cd02c 67 Prints the git suite version that the 'git' program came from.
cb22bc44
AE
68
69--help::
a87cd02c
FK
70 Prints the synopsis and a list of the most commonly used
71 commands. If a git command is named this option will bring up
72 the man-page for that command. If the option '--all' or '-a' is
73 given then all available commands are printed.
cb22bc44
AE
74
75--exec-path::
a87cd02c 76 Path to wherever your core git programs are installed.
cb22bc44
AE
77 This can also be controlled by setting the GIT_EXEC_PATH
78 environment variable. If no path is given 'git' will print
79 the current setting and then exit.
80
6acbcb92
JS
81-p|--paginate::
82 Pipe all output into 'less' (or if set, $PAGER).
83
84--git-dir=<path>::
85 Set the path to the repository. This can also be controlled by
86 setting the GIT_DIR environment variable.
87
88--bare::
89 Same as --git-dir=`pwd`.
9755afbd 90
23091e95
BF
91FURTHER DOCUMENTATION
92---------------------
9755afbd 93
23091e95
BF
94See the references above to get started using git. The following is
95probably more detail than necessary for a first-time user.
8db9307c 96
23091e95
BF
97The <<Discussion,Discussion>> section below and the
98link:core-tutorial.html[Core tutorial] both provide introductions to the
99underlying git architecture.
e6fc2346 100
23091e95
BF
101See also the link:howto-index.html[howto] documents for some useful
102examples.
9755afbd 103
23091e95
BF
104GIT COMMANDS
105------------
9755afbd 106
23091e95
BF
107We divide git into high level ("porcelain") commands and low level
108("plumbing") commands.
8b15e2fb 109
23091e95
BF
110High-level commands (porcelain)
111-------------------------------
112
113We separate the porcelain commands into the main commands and some
114ancillary user utilities.
115
116Main porcelain commands
117~~~~~~~~~~~~~~~~~~~~~~~
905197de 118
377e8139 119include::cmds-mainporcelain.txt[]
e31bb3bb 120
90933efb 121Ancillary Commands
23091e95 122~~~~~~~~~~~~~~~~~~
2f2de9b4
JH
123Manipulators:
124
377e8139 125include::cmds-ancillarymanipulators.txt[]
204ee6a9 126
90933efb 127Interrogators:
204ee6a9 128
377e8139 129include::cmds-ancillaryinterrogators.txt[]
7fc9d69f 130
89bf2077
JH
131
132Interacting with Others
133~~~~~~~~~~~~~~~~~~~~~~~
134
135These commands are to interact with foreign SCM and with other
136people via patch over e-mail.
137
138include::cmds-foreignscminterface.txt[]
139
140
b1f33d62
RR
141Low-level commands (plumbing)
142-----------------------------
143
144Although git includes its
145own porcelain layer, its low-level commands are sufficient to support
146development of alternative porcelains. Developers of such porcelains
147might start by reading about gitlink:git-update-index[1] and
148gitlink:git-read-tree[1].
149
89bf2077
JH
150The interface (input, output, set of options and the semantics)
151to these low-level commands are meant to be a lot more stable
152than Porcelain level commands, because these commands are
153primarily for scripted use. The interface to Porcelain commands
154on the other hand are subject to change in order to improve the
155end user experience.
156
157The following description divides
158the low-level commands into commands that manipulate objects (in
b1f33d62
RR
159the repository, index, and working tree), commands that interrogate and
160compare objects, and commands that move objects and references between
161repositories.
162
89bf2077 163
b1f33d62
RR
164Manipulation commands
165~~~~~~~~~~~~~~~~~~~~~
b1f33d62 166
377e8139 167include::cmds-plumbingmanipulators.txt[]
b1f33d62
RR
168
169
170Interrogation commands
171~~~~~~~~~~~~~~~~~~~~~~
172
377e8139 173include::cmds-plumbinginterrogators.txt[]
b1f33d62
RR
174
175In general, the interrogate commands do not touch the files in
176the working tree.
177
178
179Synching repositories
180~~~~~~~~~~~~~~~~~~~~~
181
377e8139 182include::cmds-synchingrepositories.txt[]
b1f33d62 183
89bf2077
JH
184The following are helper programs used by the above; end users
185typically do not use them directly.
186
187include::cmds-synchelpers.txt[]
188
189
190Internal helper commands
191~~~~~~~~~~~~~~~~~~~~~~~~
192
193These are internal helper commands used by other commands; end
194users typically do not use them directly.
195
196include::cmds-purehelpers.txt[]
197
b1f33d62 198
5773c9f2
JH
199Configuration Mechanism
200-----------------------
201
2fa090b6 202Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
5773c9f2 203is used to hold per-repository configuration options. It is a
addf88e4 204simple text file modeled after `.ini` format familiar to some
5773c9f2
JH
205people. Here is an example:
206
207------------
208#
2fa090b6 209# A '#' or ';' character indicates a comment.
5773c9f2
JH
210#
211
212; core variables
213[core]
214 ; Don't trust file modes
215 filemode = false
216
217; user identity
218[user]
219 name = "Junio C Hamano"
220 email = "junkio@twinsun.com"
221
222------------
223
224Various commands read from the configuration file and adjust
225their operation accordingly.
226
227
6c84e2e0 228Identifier Terminology
2cf565c5
DG
229----------------------
230<object>::
2fa090b6 231 Indicates the object name for any type of object.
2cf565c5
DG
232
233<blob>::
2fa090b6 234 Indicates a blob object name.
2cf565c5
DG
235
236<tree>::
2fa090b6 237 Indicates a tree object name.
2cf565c5
DG
238
239<commit>::
2fa090b6 240 Indicates a commit object name.
2cf565c5
DG
241
242<tree-ish>::
2fa090b6 243 Indicates a tree, commit or tag object name. A
6c84e2e0
DG
244 command that takes a <tree-ish> argument ultimately wants to
245 operate on a <tree> object but automatically dereferences
246 <commit> and <tag> objects that point at a <tree>.
2cf565c5 247
043d7605
TT
248<commit-ish>::
249 Indicates a commit or tag object name. A
250 command that takes a <commit-ish> argument ultimately wants to
251 operate on a <commit> object but automatically dereferences
252 <tag> objects that point at a <commit>.
253
2cf565c5
DG
254<type>::
255 Indicates that an object type is required.
2fa090b6 256 Currently one of: `blob`, `tree`, `commit`, or `tag`.
2cf565c5
DG
257
258<file>::
2fa090b6
JH
259 Indicates a filename - almost always relative to the
260 root of the tree structure `GIT_INDEX_FILE` describes.
2cf565c5 261
c1bdacf9
DG
262Symbolic Identifiers
263--------------------
90933efb 264Any git command accepting any <object> can also use the following
6c84e2e0 265symbolic notation:
c1bdacf9
DG
266
267HEAD::
2fa090b6
JH
268 indicates the head of the current branch (i.e. the
269 contents of `$GIT_DIR/HEAD`).
270
c1bdacf9 271<tag>::
2fa090b6
JH
272 a valid tag 'name'
273 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
274
c1bdacf9 275<head>::
2fa090b6
JH
276 a valid head 'name'
277 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
278
d47107d8
JH
279For a more complete list of ways to spell object names, see
280"SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1].
281
c1bdacf9
DG
282
283File/Directory Structure
284------------------------
c1bdacf9 285
a1d4aa74 286Please see link:repository-layout.html[repository layout] document.
c1bdacf9 287
6250ad1e
JL
288Read link:hooks.html[hooks] for more details about each hook.
289
c1bdacf9 290Higher level SCMs may provide and manage additional information in the
2fa090b6 291`$GIT_DIR`.
c1bdacf9 292
a1d4aa74 293
2cf565c5
DG
294Terminology
295-----------
1bff6490 296Please see link:glossary.html[glossary] document.
2cf565c5
DG
297
298
299Environment Variables
300---------------------
301Various git commands use the following environment variables:
302
c1bdacf9
DG
303The git Repository
304~~~~~~~~~~~~~~~~~~
305These environment variables apply to 'all' core git commands. Nb: it
306is worth noting that they may be used/overridden by SCMS sitting above
2fa090b6 307git so take care if using Cogito etc.
c1bdacf9
DG
308
309'GIT_INDEX_FILE'::
310 This environment allows the specification of an alternate
5f3aa197
LS
311 index file. If not specified, the default of `$GIT_DIR/index`
312 is used.
c1bdacf9
DG
313
314'GIT_OBJECT_DIRECTORY'::
315 If the object storage directory is specified via this
316 environment variable then the sha1 directories are created
317 underneath - otherwise the default `$GIT_DIR/objects`
318 directory is used.
319
320'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
321 Due to the immutable nature of git objects, old objects can be
322 archived into shared, read-only directories. This variable
90933efb 323 specifies a ":" separated list of git object directories which
c1bdacf9
DG
324 can be used to search for git objects. New objects will not be
325 written to these directories.
326
327'GIT_DIR'::
2fa090b6
JH
328 If the 'GIT_DIR' environment variable is set then it
329 specifies a path to use instead of the default `.git`
330 for the base of the repository.
c1bdacf9
DG
331
332git Commits
333~~~~~~~~~~~
334'GIT_AUTHOR_NAME'::
335'GIT_AUTHOR_EMAIL'::
336'GIT_AUTHOR_DATE'::
337'GIT_COMMITTER_NAME'::
338'GIT_COMMITTER_EMAIL'::
a7154e91 339 see gitlink:git-commit-tree[1]
c1bdacf9
DG
340
341git Diffs
342~~~~~~~~~
d81ed1b5 343'GIT_DIFF_OPTS'::
fde97d8a
SE
344 Only valid setting is "--unified=??" or "-u??" to set the
345 number of context lines shown when a unified diff is created.
346 This takes precedence over any "-U" or "--unified" option
347 value passed on the git diff command line.
348
d81ed1b5 349'GIT_EXTERNAL_DIFF'::
fde97d8a
SE
350 When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
351 program named by it is called, instead of the diff invocation
352 described above. For a path that is added, removed, or modified,
353 'GIT_EXTERNAL_DIFF' is called with 7 parameters:
354
355 path old-file old-hex old-mode new-file new-hex new-mode
356+
357where:
358
359 <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
360 contents of <old|new>,
361 <old|new>-hex:: are the 40-hexdigit SHA1 hashes,
362 <old|new>-mode:: are the octal representation of the file modes.
363
364+
365The file parameters can point at the user's working file
366(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
367when a new file is added), or a temporary file (e.g. `old-file` in the
368index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the
369temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
370+
371For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
372parameter, <path>.
2cf565c5 373
575ba9d6
ML
374other
375~~~~~
c27d205a
ML
376'GIT_PAGER'::
377 This environment variable overrides `$PAGER`.
378
575ba9d6 379'GIT_TRACE'::
2886bdb1
CC
380 If this variable is set to "1", "2" or "true" (comparison
381 is case insensitive), git will print `trace:` messages on
575ba9d6
ML
382 stderr telling about alias expansion, built-in command
383 execution and external command execution.
2886bdb1
CC
384 If this variable is set to an integer value greater than 1
385 and lower than 10 (strictly) then git will interpret this
386 value as an open file descriptor and will try to write the
387 trace messages into this file descriptor.
388 Alternatively, if this variable is set to an absolute path
389 (starting with a '/' character), git will interpret this
390 as a file path and will try to write the trace messages
391 into it.
575ba9d6 392
8db9307c
JH
393Discussion[[Discussion]]
394------------------------
556b6600 395include::core-intro.txt[]
6c84e2e0 396
cb22bc44
AE
397Authors
398-------
9755afbd
JH
399* git's founding father is Linus Torvalds <torvalds@osdl.org>.
400* The current git nurse is Junio C Hamano <junkio@cox.net>.
401* The git potty was written by Andres Ericsson <ae@op5.se>.
402* General upbringing is handled by the git-list <git@vger.kernel.org>.
2cf565c5
DG
403
404Documentation
405--------------
9755afbd
JH
406The documentation for git suite was started by David Greaves
407<david@dgreaves.com>, and later enhanced greatly by the
408contributors on the git-list <git@vger.kernel.org>.
2cf565c5
DG
409
410GIT
411---
a7154e91 412Part of the gitlink:git[7] suite
2cf565c5 413