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