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