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