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