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