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