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