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