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