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-pull[1]:: 145 Fetch from and merge with a remote repository or a local branch. 146 147gitlink:git-push[1]:: 148 Update remote refs along with associated objects. 149 150gitlink:git-rebase[1]:: 151 Rebase local commits to the updated upstream head. 152 153gitlink:git-repack[1]:: 154 Pack unpacked objects in a repository. 155 156gitlink:git-rerere[1]:: 157 Reuse recorded resolution of conflicted merges. 158 159gitlink:git-reset[1]:: 160 Reset current HEAD to the specified state. 161 162gitlink:git-resolve[1]:: 163 Merge two commits. 164 165gitlink:git-revert[1]:: 166 Revert an existing commit. 167 168gitlink:git-rm[1]:: 169 Remove files from the working tree and from the index. 170 171gitlink:git-shortlog[1]:: 172 Summarizes 'git log' output. 173 174gitlink:git-show[1]:: 175 Show one commit log and its diff. 176 177gitlink:git-show-branch[1]:: 178 Show branches and their commits. 179 180gitlink:git-status[1]:: 181 Shows the working tree status. 182 183gitlink:git-verify-tag[1]:: 184 Check the GPG signature of tag. 185 186gitlink:git-whatchanged[1]:: 187 Shows commit logs and differences they introduce. 188 189 190Ancillary Commands 191~~~~~~~~~~~~~~~~~~ 192Manipulators: 193 194gitlink:git-applypatch[1]:: 195 Apply one patch extracted from an e-mail. 196 197gitlink:git-archimport[1]:: 198 Import an arch repository into git. 199 200gitlink:git-convert-objects[1]:: 201 Converts old-style git repository. 202 203gitlink:git-cvsimport[1]:: 204 Salvage your data out of another SCM people love to hate. 205 206gitlink:git-cvsexportcommit[1]:: 207 Export a single commit to a CVS checkout. 208 209gitlink:git-cvsserver[1]:: 210 A CVS server emulator for git. 211 212gitlink:git-lost-found[1]:: 213 Recover lost refs that luckily have not yet been pruned. 214 215gitlink:git-merge-one-file[1]:: 216 The standard helper program to use with `git-merge-index`. 217 218gitlink:git-prune[1]:: 219 Prunes all unreachable objects from the object database. 220 221gitlink:git-quiltimport[1]:: 222 Applies a quilt patchset onto the current branch. 223 224gitlink:git-relink[1]:: 225 Hardlink common objects in local repositories. 226 227gitlink:git-svn[1]:: 228 Bidirectional operation between a single Subversion branch and git. 229 230gitlink:git-svnimport[1]:: 231 Import a SVN repository into git. 232 233gitlink:git-sh-setup[1]:: 234 Common git shell script setup code. 235 236gitlink:git-symbolic-ref[1]:: 237 Read and modify symbolic refs. 238 239gitlink:git-tag[1]:: 240 An example script to create a tag object signed with GPG. 241 242gitlink:git-update-ref[1]:: 243 Update the object name stored in a ref safely. 244 245 246Interrogators: 247 248gitlink:git-annotate[1]:: 249 Annotate file lines with commit info. 250 251gitlink:git-blame[1]:: 252 Blame file lines on commits. 253 254gitlink:git-check-ref-format[1]:: 255 Make sure ref name is well formed. 256 257gitlink:git-cherry[1]:: 258 Find commits not merged upstream. 259 260gitlink:git-count-objects[1]:: 261 Count unpacked number of objects and their disk consumption. 262 263gitlink:git-daemon[1]:: 264 A really simple server for git repositories. 265 266gitlink:git-fmt-merge-msg[1]:: 267 Produce a merge commit message. 268 269gitlink:git-get-tar-commit-id[1]:: 270 Extract commit ID from an archive created using git-tar-tree. 271 272gitlink:git-imap-send[1]:: 273 Dump a mailbox from stdin into an imap folder. 274 275gitlink:git-instaweb[1]:: 276 Instantly browse your working repository in gitweb. 277 278gitlink:git-mailinfo[1]:: 279 Extracts patch and authorship information from a single 280 e-mail message, optionally transliterating the commit 281 message into utf-8. 282 283gitlink:git-mailsplit[1]:: 284 A stupid program to split UNIX mbox format mailbox into 285 individual pieces of e-mail. 286 287gitlink:git-merge-tree[1]:: 288 Show three-way merge without touching index. 289 290gitlink:git-patch-id[1]:: 291 Compute unique ID for a patch. 292 293gitlink:git-parse-remote[1]:: 294 Routines to help parsing `$GIT_DIR/remotes/` files. 295 296gitlink:git-request-pull[1]:: 297 git-request-pull. 298 299gitlink:git-rev-parse[1]:: 300 Pick out and massage parameters. 301 302gitlink:git-send-email[1]:: 303 Send patch e-mails out of "format-patch --mbox" output. 304 305gitlink:git-symbolic-ref[1]:: 306 Read and modify symbolic refs. 307 308gitlink:git-stripspace[1]:: 309 Filter out empty lines. 310 311 312Low-level commands (plumbing) 313----------------------------- 314 315Although git includes its 316own porcelain layer, its low-level commands are sufficient to support 317development of alternative porcelains. Developers of such porcelains 318might start by reading about gitlink:git-update-index[1] and 319gitlink:git-read-tree[1]. 320 321We divide the low-level commands into commands that manipulate objects (in 322the repository, index, and working tree), commands that interrogate and 323compare objects, and commands that move objects and references between 324repositories. 325 326Manipulation commands 327~~~~~~~~~~~~~~~~~~~~~ 328gitlink:git-apply[1]:: 329 Reads a "diff -up1" or git generated patch file and 330 applies it to the working tree. 331 332gitlink:git-checkout-index[1]:: 333 Copy files from the index to the working tree. 334 335gitlink:git-commit-tree[1]:: 336 Creates a new commit object. 337 338gitlink:git-hash-object[1]:: 339 Computes the object ID from a file. 340 341gitlink:git-index-pack[1]:: 342 Build pack idx file for an existing packed archive. 343 344gitlink:git-init-db[1]:: 345 Creates an empty git object database, or reinitialize an 346 existing one. 347 348gitlink:git-merge-index[1]:: 349 Runs a merge for files needing merging. 350 351gitlink:git-mktag[1]:: 352 Creates a tag object. 353 354gitlink:git-mktree[1]:: 355 Build a tree-object from ls-tree formatted text. 356 357gitlink:git-pack-objects[1]:: 358 Creates a packed archive of objects. 359 360gitlink:git-prune-packed[1]:: 361 Remove extra objects that are already in pack files. 362 363gitlink:git-read-tree[1]:: 364 Reads tree information into the index. 365 366gitlink:git-repo-config[1]:: 367 Get and set options in .git/config. 368 369gitlink:git-unpack-objects[1]:: 370 Unpacks objects out of a packed archive. 371 372gitlink:git-update-index[1]:: 373 Registers files in the working tree to the index. 374 375gitlink:git-write-tree[1]:: 376 Creates a tree from the index. 377 378 379Interrogation commands 380~~~~~~~~~~~~~~~~~~~~~~ 381 382gitlink:git-cat-file[1]:: 383 Provide content or type/size information for repository objects. 384 385gitlink:git-describe[1]:: 386 Show the most recent tag that is reachable from a commit. 387 388gitlink:git-diff-index[1]:: 389 Compares content and mode of blobs between the index and repository. 390 391gitlink:git-diff-files[1]:: 392 Compares files in the working tree and the index. 393 394gitlink:git-diff-stages[1]:: 395 Compares two "merge stages" in the index. 396 397gitlink:git-diff-tree[1]:: 398 Compares the content and mode of blobs found via two tree objects. 399 400gitlink:git-for-each-ref[1]:: 401 Output information on each ref. 402 403gitlink:git-fsck-objects[1]:: 404 Verifies the connectivity and validity of the objects in the database. 405 406gitlink:git-ls-files[1]:: 407 Information about files in the index and the working tree. 408 409gitlink:git-ls-tree[1]:: 410 Displays a tree object in human readable form. 411 412gitlink:git-merge-base[1]:: 413 Finds as good common ancestors as possible for a merge. 414 415gitlink:git-name-rev[1]:: 416 Find symbolic names for given revs. 417 418gitlink:git-pack-redundant[1]:: 419 Find redundant pack files. 420 421gitlink:git-rev-list[1]:: 422 Lists commit objects in reverse chronological order. 423 424gitlink:git-show-index[1]:: 425 Displays contents of a pack idx file. 426 427gitlink:git-tar-tree[1]:: 428 Creates a tar archive of the files in the named tree object. 429 430gitlink:git-unpack-file[1]:: 431 Creates a temporary file with a blob's contents. 432 433gitlink:git-var[1]:: 434 Displays a git logical variable. 435 436gitlink:git-verify-pack[1]:: 437 Validates packed git archive files. 438 439In general, the interrogate commands do not touch the files in 440the working tree. 441 442 443Synching repositories 444~~~~~~~~~~~~~~~~~~~~~ 445 446gitlink:git-fetch-pack[1]:: 447 Updates from a remote repository (engine for ssh and 448 local transport). 449 450gitlink:git-http-fetch[1]:: 451 Downloads a remote git repository via HTTP by walking 452 commit chain. 453 454gitlink:git-local-fetch[1]:: 455 Duplicates another git repository on a local system by 456 walking commit chain. 457 458gitlink:git-peek-remote[1]:: 459 Lists references on a remote repository using 460 upload-pack protocol (engine for ssh and local 461 transport). 462 463gitlink:git-receive-pack[1]:: 464 Invoked by 'git-send-pack' to receive what is pushed to it. 465 466gitlink:git-send-pack[1]:: 467 Pushes to a remote repository, intelligently. 468 469gitlink:git-http-push[1]:: 470 Push missing objects using HTTP/DAV. 471 472gitlink:git-shell[1]:: 473 Restricted shell for GIT-only SSH access. 474 475gitlink:git-ssh-fetch[1]:: 476 Pulls from a remote repository over ssh connection by 477 walking commit chain. 478 479gitlink:git-ssh-upload[1]:: 480 Helper "server-side" program used by git-ssh-fetch. 481 482gitlink:git-update-server-info[1]:: 483 Updates auxiliary information on a dumb server to help 484 clients discover references and packs on it. 485 486gitlink:git-upload-archive[1]:: 487 Invoked by 'git-archive' to send a generated archive. 488 489gitlink:git-upload-pack[1]:: 490 Invoked by 'git-fetch-pack' to push 491 what are asked for. 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