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