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