Documentation/git.txt

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