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