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