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