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