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