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