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