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