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]] [-p|--paginate] 13 [--bare] [--git-dir=GIT_DIR] [--help] COMMAND [ARGS] 14 15DESCRIPTION 16----------- 17Git is a fast, scalable, distributed revision control system with an 18unusually rich command set that provides both high-level operations 19and full access to internals. 20 21See this link:tutorial.html[tutorial] to get started, then see 22link:everyday.html[Everyday Git] for a useful minimum set of commands, and 23"man git-commandname" for documentation of each command. CVS users may 24also want to read link:cvs-migration.html[CVS migration]. 25 26The COMMAND is either a name of a Git command (see below) or an alias 27as defined in the configuration file (see gitlink:git-repo-config[1]). 28 29OPTIONS 30------- 31--version:: 32 Prints the git suite version that the 'git' program came from. 33 34--help:: 35 Prints the synopsis and a list of the most commonly used 36 commands. If a git command is named this option will bring up 37 the man-page for that command. If the option '--all' or '-a' is 38 given then all available commands are printed. 39 40--exec-path:: 41 Path to wherever your core git programs are installed. 42 This can also be controlled by setting the GIT_EXEC_PATH 43 environment variable. If no path is given 'git' will print 44 the current setting and then exit. 45 46-p|--paginate:: 47 Pipe all output into 'less' (or if set, $PAGER). 48 49--git-dir=<path>:: 50 Set the path to the repository. This can also be controlled by 51 setting the GIT_DIR environment variable. 52 53--bare:: 54 Same as --git-dir=`pwd`. 55 56FURTHER DOCUMENTATION 57--------------------- 58 59See the references above to get started using git. The following is 60probably more detail than necessary for a first-time user. 61 62The <<Discussion,Discussion>> section below and the 63link:core-tutorial.html[Core tutorial] both provide introductions to the 64underlying git architecture. 65 66See also the link:howto-index.html[howto] documents for some useful 67examples. 68 69GIT COMMANDS 70------------ 71 72We divide git into high level ("porcelain") commands and low level 73("plumbing") commands. 74 75High-level commands (porcelain) 76------------------------------- 77 78We separate the porcelain commands into the main commands and some 79ancillary user utilities. 80 81Main porcelain commands 82~~~~~~~~~~~~~~~~~~~~~~~ 83 84gitlink:git-add[1]:: 85 Add paths to the index. 86 87gitlink:git-am[1]:: 88 Apply patches from a mailbox, but cooler. 89 90gitlink:git-applymbox[1]:: 91 Apply patches from a mailbox, original version by Linus. 92 93gitlink:git-archive[1]:: 94 Creates an archive of files from a named tree. 95 96gitlink:git-bisect[1]:: 97 Find the change that introduced a bug by binary search. 98 99gitlink:git-branch[1]:: 100 Create and Show branches. 101 102gitlink:git-checkout[1]:: 103 Checkout and switch to a branch. 104 105gitlink:git-cherry-pick[1]:: 106 Cherry-pick the effect of an existing commit. 107 108gitlink:git-clean[1]:: 109 Remove untracked files from the working tree. 110 111gitlink:git-clone[1]:: 112 Clones a repository into a new directory. 113 114gitlink:git-commit[1]:: 115 Record changes to the repository. 116 117gitlink:git-diff[1]:: 118 Show changes between commits, commit and working tree, etc. 119 120gitlink:git-fetch[1]:: 121 Download from a remote repository via various protocols. 122 123gitlink:git-format-patch[1]:: 124 Prepare patches for e-mail submission. 125 126gitlink:git-grep[1]:: 127 Print lines matching a pattern. 128 129gitlink:gitk[1]:: 130 The git repository browser. 131 132gitlink:git-log[1]:: 133 Shows commit logs. 134 135gitlink:git-ls-remote[1]:: 136 Shows references in a remote or local repository. 137 138gitlink:git-merge[1]:: 139 Grand unified merge driver. 140 141gitlink:git-mv[1]:: 142 Move or rename a file, a directory, or a symlink. 143 144gitlink:git-pack-refs[1]:: 145 Pack heads and tags for efficient repository access. 146 147gitlink:git-pull[1]:: 148 Fetch from and merge with a remote repository or a local branch. 149 150gitlink:git-push[1]:: 151 Update remote refs along with associated objects. 152 153gitlink:git-rebase[1]:: 154 Rebase local commits to the updated upstream head. 155 156gitlink:git-repack[1]:: 157 Pack unpacked objects in a repository. 158 159gitlink:git-rerere[1]:: 160 Reuse recorded resolution of conflicted merges. 161 162gitlink:git-reset[1]:: 163 Reset current HEAD to the specified state. 164 165gitlink:git-resolve[1]:: 166 Merge two commits. 167 168gitlink:git-revert[1]:: 169 Revert an existing commit. 170 171gitlink:git-rm[1]:: 172 Remove files from the working tree and from the index. 173 174gitlink:git-shortlog[1]:: 175 Summarizes 'git log' output. 176 177gitlink:git-show[1]:: 178 Show one commit log and its diff. 179 180gitlink:git-show-branch[1]:: 181 Show branches and their commits. 182 183gitlink:git-status[1]:: 184 Shows the working tree status. 185 186gitlink:git-verify-tag[1]:: 187 Check the GPG signature of tag. 188 189gitlink:git-whatchanged[1]:: 190 Shows commit logs and differences they introduce. 191 192 193Ancillary Commands 194~~~~~~~~~~~~~~~~~~ 195Manipulators: 196 197gitlink:git-applypatch[1]:: 198 Apply one patch extracted from an e-mail. 199 200gitlink:git-archimport[1]:: 201 Import an arch repository into git. 202 203gitlink:git-convert-objects[1]:: 204 Converts old-style git repository. 205 206gitlink:git-cvsimport[1]:: 207 Salvage your data out of another SCM people love to hate. 208 209gitlink:git-cvsexportcommit[1]:: 210 Export a single commit to a CVS checkout. 211 212gitlink:git-cvsserver[1]:: 213 A CVS server emulator for git. 214 215gitlink:git-lost-found[1]:: 216 Recover lost refs that luckily have not yet been pruned. 217 218gitlink:git-merge-one-file[1]:: 219 The standard helper program to use with `git-merge-index`. 220 221gitlink:git-prune[1]:: 222 Prunes all unreachable objects from the object database. 223 224gitlink:git-quiltimport[1]:: 225 Applies a quilt patchset onto the current branch. 226 227gitlink:git-reflog[1]:: 228 Manage reflog information. 229 230gitlink:git-relink[1]:: 231 Hardlink common objects in local repositories. 232 233gitlink:git-svn[1]:: 234 Bidirectional operation between a single Subversion branch and git. 235 236gitlink:git-svnimport[1]:: 237 Import a SVN repository into git. 238 239gitlink:git-sh-setup[1]:: 240 Common git shell script setup code. 241 242gitlink:git-symbolic-ref[1]:: 243 Read and modify symbolic refs. 244 245gitlink:git-tag[1]:: 246 An example script to create a tag object signed with GPG. 247 248gitlink:git-update-ref[1]:: 249 Update the object name stored in a ref safely. 250 251 252Interrogators: 253 254gitlink:git-annotate[1]:: 255 Annotate file lines with commit info. 256 257gitlink:git-blame[1]:: 258 Find out where each line in a file came from. 259 260gitlink:git-check-ref-format[1]:: 261 Make sure ref name is well formed. 262 263gitlink:git-cherry[1]:: 264 Find commits not merged upstream. 265 266gitlink:git-count-objects[1]:: 267 Count unpacked number of objects and their disk consumption. 268 269gitlink:git-daemon[1]:: 270 A really simple server for git repositories. 271 272gitlink:git-fmt-merge-msg[1]:: 273 Produce a merge commit message. 274 275gitlink:git-get-tar-commit-id[1]:: 276 Extract commit ID from an archive created using git-tar-tree. 277 278gitlink:git-imap-send[1]:: 279 Dump a mailbox from stdin into an imap folder. 280 281gitlink:git-instaweb[1]:: 282 Instantly browse your working repository in gitweb. 283 284gitlink:git-mailinfo[1]:: 285 Extracts patch and authorship information from a single 286 e-mail message, optionally transliterating the commit 287 message into utf-8. 288 289gitlink:git-mailsplit[1]:: 290 A stupid program to split UNIX mbox format mailbox into 291 individual pieces of e-mail. 292 293gitlink:git-merge-tree[1]:: 294 Show three-way merge without touching index. 295 296gitlink:git-patch-id[1]:: 297 Compute unique ID for a patch. 298 299gitlink:git-parse-remote[1]:: 300 Routines to help parsing `$GIT_DIR/remotes/` files. 301 302gitlink:git-request-pull[1]:: 303 git-request-pull. 304 305gitlink:git-rev-parse[1]:: 306 Pick out and massage parameters. 307 308gitlink:git-runstatus[1]:: 309 A helper for git-status and git-commit. 310 311gitlink:git-send-email[1]:: 312 Send patch e-mails out of "format-patch --mbox" output. 313 314gitlink:git-symbolic-ref[1]:: 315 Read and modify symbolic refs. 316 317gitlink:git-stripspace[1]:: 318 Filter out empty lines. 319 320 321Low-level commands (plumbing) 322----------------------------- 323 324Although git includes its 325own porcelain layer, its low-level commands are sufficient to support 326development of alternative porcelains. Developers of such porcelains 327might start by reading about gitlink:git-update-index[1] and 328gitlink:git-read-tree[1]. 329 330We divide the low-level commands into commands that manipulate objects (in 331the repository, index, and working tree), commands that interrogate and 332compare objects, and commands that move objects and references between 333repositories. 334 335Manipulation commands 336~~~~~~~~~~~~~~~~~~~~~ 337gitlink:git-apply[1]:: 338 Reads a "diff -up1" or git generated patch file and 339 applies it to the working tree. 340 341gitlink:git-checkout-index[1]:: 342 Copy files from the index to the working tree. 343 344gitlink:git-commit-tree[1]:: 345 Creates a new commit object. 346 347gitlink:git-hash-object[1]:: 348 Computes the object ID from a file. 349 350gitlink:git-index-pack[1]:: 351 Build pack idx file for an existing packed archive. 352 353gitlink:git-init-db[1]:: 354 Creates an empty git object database, or reinitialize an 355 existing one. 356 357gitlink:git-merge-file[1]:: 358 Runs a threeway merge. 359 360gitlink:git-merge-index[1]:: 361 Runs a merge for files needing merging. 362 363gitlink:git-mktag[1]:: 364 Creates a tag object. 365 366gitlink:git-mktree[1]:: 367 Build a tree-object from ls-tree formatted text. 368 369gitlink:git-pack-objects[1]:: 370 Creates a packed archive of objects. 371 372gitlink:git-prune-packed[1]:: 373 Remove extra objects that are already in pack files. 374 375gitlink:git-read-tree[1]:: 376 Reads tree information into the index. 377 378gitlink:git-repo-config[1]:: 379 Get and set options in .git/config. 380 381gitlink:git-unpack-objects[1]:: 382 Unpacks objects out of a packed archive. 383 384gitlink:git-update-index[1]:: 385 Registers files in the working tree to the index. 386 387gitlink:git-write-tree[1]:: 388 Creates a tree from the index. 389 390 391Interrogation commands 392~~~~~~~~~~~~~~~~~~~~~~ 393 394gitlink:git-cat-file[1]:: 395 Provide content or type/size information for repository objects. 396 397gitlink:git-describe[1]:: 398 Show the most recent tag that is reachable from a commit. 399 400gitlink:git-diff-index[1]:: 401 Compares content and mode of blobs between the index and repository. 402 403gitlink:git-diff-files[1]:: 404 Compares files in the working tree and the index. 405 406gitlink:git-diff-stages[1]:: 407 Compares two "merge stages" in the index. 408 409gitlink:git-diff-tree[1]:: 410 Compares the content and mode of blobs found via two tree objects. 411 412gitlink:git-for-each-ref[1]:: 413 Output information on each ref. 414 415gitlink:git-fsck-objects[1]:: 416 Verifies the connectivity and validity of the objects in the database. 417 418gitlink:git-ls-files[1]:: 419 Information about files in the index and the working tree. 420 421gitlink:git-ls-tree[1]:: 422 Displays a tree object in human readable form. 423 424gitlink:git-merge-base[1]:: 425 Finds as good common ancestors as possible for a merge. 426 427gitlink:git-name-rev[1]:: 428 Find symbolic names for given revs. 429 430gitlink:git-pack-redundant[1]:: 431 Find redundant pack files. 432 433gitlink:git-rev-list[1]:: 434 Lists commit objects in reverse chronological order. 435 436gitlink:git-show-index[1]:: 437 Displays contents of a pack idx file. 438 439gitlink:git-show-ref[1]:: 440 List references in a local repository. 441 442gitlink:git-tar-tree[1]:: 443 Creates a tar archive of the files in the named tree object. 444 445gitlink:git-unpack-file[1]:: 446 Creates a temporary file with a blob's contents. 447 448gitlink:git-var[1]:: 449 Displays a git logical variable. 450 451gitlink:git-verify-pack[1]:: 452 Validates packed git archive files. 453 454In general, the interrogate commands do not touch the files in 455the working tree. 456 457 458Synching repositories 459~~~~~~~~~~~~~~~~~~~~~ 460 461gitlink:git-fetch-pack[1]:: 462 Updates from a remote repository (engine for ssh and 463 local transport). 464 465gitlink:git-http-fetch[1]:: 466 Downloads a remote git repository via HTTP by walking 467 commit chain. 468 469gitlink:git-local-fetch[1]:: 470 Duplicates another git repository on a local system by 471 walking commit chain. 472 473gitlink:git-peek-remote[1]:: 474 Lists references on a remote repository using 475 upload-pack protocol (engine for ssh and local 476 transport). 477 478gitlink:git-receive-pack[1]:: 479 Invoked by 'git-send-pack' to receive what is pushed to it. 480 481gitlink:git-send-pack[1]:: 482 Pushes to a remote repository, intelligently. 483 484gitlink:git-http-push[1]:: 485 Push missing objects using HTTP/DAV. 486 487gitlink:git-shell[1]:: 488 Restricted shell for GIT-only SSH access. 489 490gitlink:git-ssh-fetch[1]:: 491 Pulls from a remote repository over ssh connection by 492 walking commit chain. 493 494gitlink:git-ssh-upload[1]:: 495 Helper "server-side" program used by git-ssh-fetch. 496 497gitlink:git-update-server-info[1]:: 498 Updates auxiliary information on a dumb server to help 499 clients discover references and packs on it. 500 501gitlink:git-upload-archive[1]:: 502 Invoked by 'git-archive' to send a generated archive. 503 504gitlink:git-upload-pack[1]:: 505 Invoked by 'git-fetch-pack' to push 506 what are asked for. 507 508 509Configuration Mechanism 510----------------------- 511 512Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file 513is used to hold per-repository configuration options. It is a 514simple text file modeled after `.ini` format familiar to some 515people. Here is an example: 516 517------------ 518# 519# A '#' or ';' character indicates a comment. 520# 521 522; core variables 523[core] 524 ; Don't trust file modes 525 filemode = false 526 527; user identity 528[user] 529 name = "Junio C Hamano" 530 email = "junkio@twinsun.com" 531 532------------ 533 534Various commands read from the configuration file and adjust 535their operation accordingly. 536 537 538Identifier Terminology 539---------------------- 540<object>:: 541 Indicates the object name for any type of object. 542 543<blob>:: 544 Indicates a blob object name. 545 546<tree>:: 547 Indicates a tree object name. 548 549<commit>:: 550 Indicates a commit object name. 551 552<tree-ish>:: 553 Indicates a tree, commit or tag object name. A 554 command that takes a <tree-ish> argument ultimately wants to 555 operate on a <tree> object but automatically dereferences 556 <commit> and <tag> objects that point at a <tree>. 557 558<type>:: 559 Indicates that an object type is required. 560 Currently one of: `blob`, `tree`, `commit`, or `tag`. 561 562<file>:: 563 Indicates a filename - almost always relative to the 564 root of the tree structure `GIT_INDEX_FILE` describes. 565 566Symbolic Identifiers 567-------------------- 568Any git command accepting any <object> can also use the following 569symbolic notation: 570 571HEAD:: 572 indicates the head of the current branch (i.e. the 573 contents of `$GIT_DIR/HEAD`). 574 575<tag>:: 576 a valid tag 'name' 577 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). 578 579<head>:: 580 a valid head 'name' 581 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). 582 583For a more complete list of ways to spell object names, see 584"SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1]. 585 586 587File/Directory Structure 588------------------------ 589 590Please see link:repository-layout.html[repository layout] document. 591 592Read link:hooks.html[hooks] for more details about each hook. 593 594Higher level SCMs may provide and manage additional information in the 595`$GIT_DIR`. 596 597 598Terminology 599----------- 600Please see link:glossary.html[glossary] document. 601 602 603Environment Variables 604--------------------- 605Various git commands use the following environment variables: 606 607The git Repository 608~~~~~~~~~~~~~~~~~~ 609These environment variables apply to 'all' core git commands. Nb: it 610is worth noting that they may be used/overridden by SCMS sitting above 611git so take care if using Cogito etc. 612 613'GIT_INDEX_FILE':: 614 This environment allows the specification of an alternate 615 index file. If not specified, the default of `$GIT_DIR/index` 616 is used. 617 618'GIT_OBJECT_DIRECTORY':: 619 If the object storage directory is specified via this 620 environment variable then the sha1 directories are created 621 underneath - otherwise the default `$GIT_DIR/objects` 622 directory is used. 623 624'GIT_ALTERNATE_OBJECT_DIRECTORIES':: 625 Due to the immutable nature of git objects, old objects can be 626 archived into shared, read-only directories. This variable 627 specifies a ":" separated list of git object directories which 628 can be used to search for git objects. New objects will not be 629 written to these directories. 630 631'GIT_DIR':: 632 If the 'GIT_DIR' environment variable is set then it 633 specifies a path to use instead of the default `.git` 634 for the base of the repository. 635 636git Commits 637~~~~~~~~~~~ 638'GIT_AUTHOR_NAME':: 639'GIT_AUTHOR_EMAIL':: 640'GIT_AUTHOR_DATE':: 641'GIT_COMMITTER_NAME':: 642'GIT_COMMITTER_EMAIL':: 643 see gitlink:git-commit-tree[1] 644 645git Diffs 646~~~~~~~~~ 647'GIT_DIFF_OPTS':: 648 Only valid setting is "--unified=??" or "-u??" to set the 649 number of context lines shown when a unified diff is created. 650 This takes precedence over any "-U" or "--unified" option 651 value passed on the git diff command line. 652 653'GIT_EXTERNAL_DIFF':: 654 When the environment variable 'GIT_EXTERNAL_DIFF' is set, the 655 program named by it is called, instead of the diff invocation 656 described above. For a path that is added, removed, or modified, 657 'GIT_EXTERNAL_DIFF' is called with 7 parameters: 658 659 path old-file old-hex old-mode new-file new-hex new-mode 660+ 661where: 662 663 <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the 664 contents of <old|new>, 665 <old|new>-hex:: are the 40-hexdigit SHA1 hashes, 666 <old|new>-mode:: are the octal representation of the file modes. 667 668+ 669The file parameters can point at the user's working file 670(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file` 671when a new file is added), or a temporary file (e.g. `old-file` in the 672index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the 673temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits. 674+ 675For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1 676parameter, <path>. 677 678other 679~~~~~ 680'GIT_PAGER':: 681 This environment variable overrides `$PAGER`. 682 683'GIT_TRACE':: 684 If this variable is set to "1", "2" or "true" (comparison 685 is case insensitive), git will print `trace:` messages on 686 stderr telling about alias expansion, built-in command 687 execution and external command execution. 688 If this variable is set to an integer value greater than 1 689 and lower than 10 (strictly) then git will interpret this 690 value as an open file descriptor and will try to write the 691 trace messages into this file descriptor. 692 Alternatively, if this variable is set to an absolute path 693 (starting with a '/' character), git will interpret this 694 as a file path and will try to write the trace messages 695 into it. 696 697Discussion[[Discussion]] 698------------------------ 699include::README[] 700 701Authors 702------- 703* git's founding father is Linus Torvalds <torvalds@osdl.org>. 704* The current git nurse is Junio C Hamano <junkio@cox.net>. 705* The git potty was written by Andres Ericsson <ae@op5.se>. 706* General upbringing is handled by the git-list <git@vger.kernel.org>. 707 708Documentation 709-------------- 710The documentation for git suite was started by David Greaves 711<david@dgreaves.com>, and later enhanced greatly by the 712contributors on the git-list <git@vger.kernel.org>. 713 714GIT 715--- 716Part of the gitlink:git[7] suite 717