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