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-gc[1]:: 216 Cleanup unnecessary files and optimize the local repository. 217 218gitlink:git-lost-found[1]:: 219 Recover lost refs that luckily have not yet been pruned. 220 221gitlink:git-merge-one-file[1]:: 222 The standard helper program to use with `git-merge-index`. 223 224gitlink:git-prune[1]:: 225 Prunes all unreachable objects from the object database. 226 227gitlink:git-quiltimport[1]:: 228 Applies a quilt patchset onto the current branch. 229 230gitlink:git-reflog[1]:: 231 Manage reflog information. 232 233gitlink:git-relink[1]:: 234 Hardlink common objects in local repositories. 235 236gitlink:git-svn[1]:: 237 Bidirectional operation between a single Subversion branch and git. 238 239gitlink:git-svnimport[1]:: 240 Import a SVN repository into git. 241 242gitlink:git-sh-setup[1]:: 243 Common git shell script setup code. 244 245gitlink:git-symbolic-ref[1]:: 246 Read and modify symbolic refs. 247 248gitlink:git-tag[1]:: 249 An example script to create a tag object signed with GPG. 250 251gitlink:git-update-ref[1]:: 252 Update the object name stored in a ref safely. 253 254 255Interrogators: 256 257gitlink:git-annotate[1]:: 258 Annotate file lines with commit info. 259 260gitlink:git-blame[1]:: 261 Find out where each line in a file came from. 262 263gitlink:git-check-ref-format[1]:: 264 Make sure ref name is well formed. 265 266gitlink:git-cherry[1]:: 267 Find commits not merged upstream. 268 269gitlink:git-count-objects[1]:: 270 Count unpacked number of objects and their disk consumption. 271 272gitlink:git-daemon[1]:: 273 A really simple server for git repositories. 274 275gitlink:git-fmt-merge-msg[1]:: 276 Produce a merge commit message. 277 278gitlink:git-get-tar-commit-id[1]:: 279 Extract commit ID from an archive created using git-tar-tree. 280 281gitlink:git-imap-send[1]:: 282 Dump a mailbox from stdin into an imap folder. 283 284gitlink:git-instaweb[1]:: 285 Instantly browse your working repository in gitweb. 286 287gitlink:git-mailinfo[1]:: 288 Extracts patch and authorship information from a single 289 e-mail message, optionally transliterating the commit 290 message into utf-8. 291 292gitlink:git-mailsplit[1]:: 293 A stupid program to split UNIX mbox format mailbox into 294 individual pieces of e-mail. 295 296gitlink:git-merge-tree[1]:: 297 Show three-way merge without touching index. 298 299gitlink:git-patch-id[1]:: 300 Compute unique ID for a patch. 301 302gitlink:git-parse-remote[1]:: 303 Routines to help parsing `$GIT_DIR/remotes/` files. 304 305gitlink:git-request-pull[1]:: 306 git-request-pull. 307 308gitlink:git-rev-parse[1]:: 309 Pick out and massage parameters. 310 311gitlink:git-runstatus[1]:: 312 A helper for git-status and git-commit. 313 314gitlink:git-send-email[1]:: 315 Send patch e-mails out of "format-patch --mbox" output. 316 317gitlink:git-symbolic-ref[1]:: 318 Read and modify symbolic refs. 319 320gitlink:git-stripspace[1]:: 321 Filter out empty lines. 322 323 324Low-level commands (plumbing) 325----------------------------- 326 327Although git includes its 328own porcelain layer, its low-level commands are sufficient to support 329development of alternative porcelains. Developers of such porcelains 330might start by reading about gitlink:git-update-index[1] and 331gitlink:git-read-tree[1]. 332 333We divide the low-level commands into commands that manipulate objects (in 334the repository, index, and working tree), commands that interrogate and 335compare objects, and commands that move objects and references between 336repositories. 337 338Manipulation commands 339~~~~~~~~~~~~~~~~~~~~~ 340gitlink:git-apply[1]:: 341 Reads a "diff -up1" or git generated patch file and 342 applies it to the working tree. 343 344gitlink:git-checkout-index[1]:: 345 Copy files from the index to the working tree. 346 347gitlink:git-commit-tree[1]:: 348 Creates a new commit object. 349 350gitlink:git-hash-object[1]:: 351 Computes the object ID from a file. 352 353gitlink:git-index-pack[1]:: 354 Build pack idx file for an existing packed archive. 355 356gitlink:git-init[1]:: 357gitlink:git-init-db[1]:: 358 Creates an empty git object database, or reinitialize an 359 existing one. 360 361gitlink:git-merge-file[1]:: 362 Runs a threeway merge. 363 364gitlink:git-merge-index[1]:: 365 Runs a merge for files needing merging. 366 367gitlink:git-mktag[1]:: 368 Creates a tag object. 369 370gitlink:git-mktree[1]:: 371 Build a tree-object from ls-tree formatted text. 372 373gitlink:git-pack-objects[1]:: 374 Creates a packed archive of objects. 375 376gitlink:git-prune-packed[1]:: 377 Remove extra objects that are already in pack files. 378 379gitlink:git-read-tree[1]:: 380 Reads tree information into the index. 381 382gitlink:git-repo-config[1]:: 383 Get and set options in .git/config. 384 385gitlink:git-unpack-objects[1]:: 386 Unpacks objects out of a packed archive. 387 388gitlink:git-update-index[1]:: 389 Registers files in the working tree to the index. 390 391gitlink:git-write-tree[1]:: 392 Creates a tree from the index. 393 394 395Interrogation commands 396~~~~~~~~~~~~~~~~~~~~~~ 397 398gitlink:git-cat-file[1]:: 399 Provide content or type/size information for repository objects. 400 401gitlink:git-describe[1]:: 402 Show the most recent tag that is reachable from a commit. 403 404gitlink:git-diff-index[1]:: 405 Compares content and mode of blobs between the index and repository. 406 407gitlink:git-diff-files[1]:: 408 Compares files in the working tree and the index. 409 410gitlink:git-diff-stages[1]:: 411 Compares two "merge stages" in the index. 412 413gitlink:git-diff-tree[1]:: 414 Compares the content and mode of blobs found via two tree objects. 415 416gitlink:git-for-each-ref[1]:: 417 Output information on each ref. 418 419gitlink:git-fsck-objects[1]:: 420 Verifies the connectivity and validity of the objects in the database. 421 422gitlink:git-ls-files[1]:: 423 Information about files in the index and the working tree. 424 425gitlink:git-ls-tree[1]:: 426 Displays a tree object in human readable form. 427 428gitlink:git-merge-base[1]:: 429 Finds as good common ancestors as possible for a merge. 430 431gitlink:git-name-rev[1]:: 432 Find symbolic names for given revs. 433 434gitlink:git-pack-redundant[1]:: 435 Find redundant pack files. 436 437gitlink:git-rev-list[1]:: 438 Lists commit objects in reverse chronological order. 439 440gitlink:git-show-index[1]:: 441 Displays contents of a pack idx file. 442 443gitlink:git-show-ref[1]:: 444 List references in a local repository. 445 446gitlink:git-tar-tree[1]:: 447 Creates a tar archive of the files in the named tree object. 448 449gitlink:git-unpack-file[1]:: 450 Creates a temporary file with a blob's contents. 451 452gitlink:git-var[1]:: 453 Displays a git logical variable. 454 455gitlink:git-verify-pack[1]:: 456 Validates packed git archive files. 457 458In general, the interrogate commands do not touch the files in 459the working tree. 460 461 462Synching repositories 463~~~~~~~~~~~~~~~~~~~~~ 464 465gitlink:git-fetch-pack[1]:: 466 Updates from a remote repository (engine for ssh and 467 local transport). 468 469gitlink:git-http-fetch[1]:: 470 Downloads a remote git repository via HTTP by walking 471 commit chain. 472 473gitlink:git-local-fetch[1]:: 474 Duplicates another git repository on a local system by 475 walking commit chain. 476 477gitlink:git-peek-remote[1]:: 478 Lists references on a remote repository using 479 upload-pack protocol (engine for ssh and local 480 transport). 481 482gitlink:git-receive-pack[1]:: 483 Invoked by 'git-send-pack' to receive what is pushed to it. 484 485gitlink:git-send-pack[1]:: 486 Pushes to a remote repository, intelligently. 487 488gitlink:git-http-push[1]:: 489 Push missing objects using HTTP/DAV. 490 491gitlink:git-shell[1]:: 492 Restricted shell for GIT-only SSH access. 493 494gitlink:git-ssh-fetch[1]:: 495 Pulls from a remote repository over ssh connection by 496 walking commit chain. 497 498gitlink:git-ssh-upload[1]:: 499 Helper "server-side" program used by git-ssh-fetch. 500 501gitlink:git-update-server-info[1]:: 502 Updates auxiliary information on a dumb server to help 503 clients discover references and packs on it. 504 505gitlink:git-upload-archive[1]:: 506 Invoked by 'git-archive' to send a generated archive. 507 508gitlink:git-upload-pack[1]:: 509 Invoked by 'git-fetch-pack' to push 510 what are asked for. 511 512 513Configuration Mechanism 514----------------------- 515 516Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file 517is used to hold per-repository configuration options. It is a 518simple text file modeled after `.ini` format familiar to some 519people. Here is an example: 520 521------------ 522# 523# A '#' or ';' character indicates a comment. 524# 525 526; core variables 527[core] 528 ; Don't trust file modes 529 filemode = false 530 531; user identity 532[user] 533 name = "Junio C Hamano" 534 email = "junkio@twinsun.com" 535 536------------ 537 538Various commands read from the configuration file and adjust 539their operation accordingly. 540 541 542Identifier Terminology 543---------------------- 544<object>:: 545 Indicates the object name for any type of object. 546 547<blob>:: 548 Indicates a blob object name. 549 550<tree>:: 551 Indicates a tree object name. 552 553<commit>:: 554 Indicates a commit object name. 555 556<tree-ish>:: 557 Indicates a tree, commit or tag object name. A 558 command that takes a <tree-ish> argument ultimately wants to 559 operate on a <tree> object but automatically dereferences 560 <commit> and <tag> objects that point at a <tree>. 561 562<type>:: 563 Indicates that an object type is required. 564 Currently one of: `blob`, `tree`, `commit`, or `tag`. 565 566<file>:: 567 Indicates a filename - almost always relative to the 568 root of the tree structure `GIT_INDEX_FILE` describes. 569 570Symbolic Identifiers 571-------------------- 572Any git command accepting any <object> can also use the following 573symbolic notation: 574 575HEAD:: 576 indicates the head of the current branch (i.e. the 577 contents of `$GIT_DIR/HEAD`). 578 579<tag>:: 580 a valid tag 'name' 581 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). 582 583<head>:: 584 a valid head 'name' 585 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). 586 587For a more complete list of ways to spell object names, see 588"SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1]. 589 590 591File/Directory Structure 592------------------------ 593 594Please see link:repository-layout.html[repository layout] document. 595 596Read link:hooks.html[hooks] for more details about each hook. 597 598Higher level SCMs may provide and manage additional information in the 599`$GIT_DIR`. 600 601 602Terminology 603----------- 604Please see link:glossary.html[glossary] document. 605 606 607Environment Variables 608--------------------- 609Various git commands use the following environment variables: 610 611The git Repository 612~~~~~~~~~~~~~~~~~~ 613These environment variables apply to 'all' core git commands. Nb: it 614is worth noting that they may be used/overridden by SCMS sitting above 615git so take care if using Cogito etc. 616 617'GIT_INDEX_FILE':: 618 This environment allows the specification of an alternate 619 index file. If not specified, the default of `$GIT_DIR/index` 620 is used. 621 622'GIT_OBJECT_DIRECTORY':: 623 If the object storage directory is specified via this 624 environment variable then the sha1 directories are created 625 underneath - otherwise the default `$GIT_DIR/objects` 626 directory is used. 627 628'GIT_ALTERNATE_OBJECT_DIRECTORIES':: 629 Due to the immutable nature of git objects, old objects can be 630 archived into shared, read-only directories. This variable 631 specifies a ":" separated list of git object directories which 632 can be used to search for git objects. New objects will not be 633 written to these directories. 634 635'GIT_DIR':: 636 If the 'GIT_DIR' environment variable is set then it 637 specifies a path to use instead of the default `.git` 638 for the base of the repository. 639 640git Commits 641~~~~~~~~~~~ 642'GIT_AUTHOR_NAME':: 643'GIT_AUTHOR_EMAIL':: 644'GIT_AUTHOR_DATE':: 645'GIT_COMMITTER_NAME':: 646'GIT_COMMITTER_EMAIL':: 647 see gitlink:git-commit-tree[1] 648 649git Diffs 650~~~~~~~~~ 651'GIT_DIFF_OPTS':: 652 Only valid setting is "--unified=??" or "-u??" to set the 653 number of context lines shown when a unified diff is created. 654 This takes precedence over any "-U" or "--unified" option 655 value passed on the git diff command line. 656 657'GIT_EXTERNAL_DIFF':: 658 When the environment variable 'GIT_EXTERNAL_DIFF' is set, the 659 program named by it is called, instead of the diff invocation 660 described above. For a path that is added, removed, or modified, 661 'GIT_EXTERNAL_DIFF' is called with 7 parameters: 662 663 path old-file old-hex old-mode new-file new-hex new-mode 664+ 665where: 666 667 <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the 668 contents of <old|new>, 669 <old|new>-hex:: are the 40-hexdigit SHA1 hashes, 670 <old|new>-mode:: are the octal representation of the file modes. 671 672+ 673The file parameters can point at the user's working file 674(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file` 675when a new file is added), or a temporary file (e.g. `old-file` in the 676index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the 677temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits. 678+ 679For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1 680parameter, <path>. 681 682other 683~~~~~ 684'GIT_PAGER':: 685 This environment variable overrides `$PAGER`. 686 687'GIT_TRACE':: 688 If this variable is set to "1", "2" or "true" (comparison 689 is case insensitive), git will print `trace:` messages on 690 stderr telling about alias expansion, built-in command 691 execution and external command execution. 692 If this variable is set to an integer value greater than 1 693 and lower than 10 (strictly) then git will interpret this 694 value as an open file descriptor and will try to write the 695 trace messages into this file descriptor. 696 Alternatively, if this variable is set to an absolute path 697 (starting with a '/' character), git will interpret this 698 as a file path and will try to write the trace messages 699 into it. 700 701Discussion[[Discussion]] 702------------------------ 703include::README[] 704 705Authors 706------- 707* git's founding father is Linus Torvalds <torvalds@osdl.org>. 708* The current git nurse is Junio C Hamano <junkio@cox.net>. 709* The git potty was written by Andres Ericsson <ae@op5.se>. 710* General upbringing is handled by the git-list <git@vger.kernel.org>. 711 712Documentation 713-------------- 714The documentation for git suite was started by David Greaves 715<david@dgreaves.com>, and later enhanced greatly by the 716contributors on the git-list <git@vger.kernel.org>. 717 718GIT 719--- 720Part of the gitlink:git[7] suite 721