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