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