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