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