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