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