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