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-gc[1]::
 216         Cleanup unnecessary files and optimize the local repository.
 217
 218 gitlink:git-lost-found[1]::
 219         Recover lost refs that luckily have not yet been pruned.
 220
 221 gitlink:git-merge-one-file[1]::
 222         The standard helper program to use with `git-merge-index`.
 223
 224 gitlink:git-prune[1]::
 225         Prunes all unreachable objects from the object database.
 226
 227 gitlink:git-quiltimport[1]::
 228         Applies a quilt patchset onto the current branch.
 229
 230 gitlink:git-reflog[1]::
 231         Manage reflog information.
 232
 233 gitlink:git-relink[1]::
 234         Hardlink common objects in local repositories.
 235
 236 gitlink:git-svn[1]::
 237         Bidirectional operation between a single Subversion branch and git.
 238
 239 gitlink:git-svnimport[1]::
 240         Import a SVN repository into git.
 241
 242 gitlink:git-sh-setup[1]::
 243         Common git shell script setup code.
 244
 245 gitlink:git-symbolic-ref[1]::
 246         Read and modify symbolic refs.
 247
 248 gitlink:git-tag[1]::
 249         An example script to create a tag object signed with GPG.
 250
 251 gitlink:git-update-ref[1]::
 252         Update the object name stored in a ref safely.
 253
 254
 255 Interrogators:
 256
 257 gitlink:git-annotate[1]::
 258         Annotate file lines with commit info.
 259
 260 gitlink:git-blame[1]::
 261         Find out where each line in a file came from.
 262
 263 gitlink:git-check-ref-format[1]::
 264         Make sure ref name is well formed.
 265
 266 gitlink:git-cherry[1]::
 267         Find commits not merged upstream.
 268
 269 gitlink:git-count-objects[1]::
 270         Count unpacked number of objects and their disk consumption.
 271
 272 gitlink:git-daemon[1]::
 273         A really simple server for git repositories.
 274
 275 gitlink:git-fmt-merge-msg[1]::
 276         Produce a merge commit message.
 277
 278 gitlink:git-get-tar-commit-id[1]::
 279         Extract commit ID from an archive created using git-tar-tree.
 280
 281 gitlink:git-imap-send[1]::
 282         Dump a mailbox from stdin into an imap folder.
 283
 284 gitlink:git-instaweb[1]::
 285         Instantly browse your working repository in gitweb.
 286
 287 gitlink:git-mailinfo[1]::
 288         Extracts patch and authorship information from a single
 289         e-mail message, optionally transliterating the commit
 290         message into utf-8.
 291
 292 gitlink:git-mailsplit[1]::
 293         A stupid program to split UNIX mbox format mailbox into
 294         individual pieces of e-mail.
 295
 296 gitlink:git-merge-tree[1]::
 297         Show three-way merge without touching index.
 298
 299 gitlink:git-patch-id[1]::
 300         Compute unique ID for a patch.
 301
 302 gitlink:git-parse-remote[1]::
 303         Routines to help parsing `$GIT_DIR/remotes/` files.
 304
 305 gitlink:git-request-pull[1]::
 306         git-request-pull.
 307
 308 gitlink:git-rev-parse[1]::
 309         Pick out and massage parameters.
 310
 311 gitlink:git-runstatus[1]::
 312         A helper for git-status and git-commit.
 313
 314 gitlink:git-send-email[1]::
 315         Send patch e-mails out of "format-patch --mbox" output.
 316
 317 gitlink:git-symbolic-ref[1]::
 318         Read and modify symbolic refs.
 319
 320 gitlink:git-stripspace[1]::
 321         Filter out empty lines.
 322
 323
 324 Low-level commands (plumbing)
 325 -----------------------------
 326
 327 Although git includes its
 328 own porcelain layer, its low-level commands are sufficient to support
 329 development of alternative porcelains.  Developers of such porcelains
 330 might start by reading about gitlink:git-update-index[1] and
 331 gitlink:git-read-tree[1].
 332
 333 We divide the low-level commands into commands that manipulate objects (in
 334 the repository, index, and working tree), commands that interrogate and
 335 compare objects, and commands that move objects and references between
 336 repositories.
 337
 338 Manipulation commands
 339 ~~~~~~~~~~~~~~~~~~~~~
 340 gitlink:git-apply[1]::
 341         Reads a "diff -up1" or git generated patch file and
 342         applies it to the working tree.
 343
 344 gitlink:git-checkout-index[1]::
 345         Copy files from the index to the working tree.
 346
 347 gitlink:git-commit-tree[1]::
 348         Creates a new commit object.
 349
 350 gitlink:git-hash-object[1]::
 351         Computes the object ID from a file.
 352
 353 gitlink:git-index-pack[1]::
 354         Build pack idx file for an existing packed archive.
 355
 356 gitlink:git-init[1]::
 357 gitlink:git-init-db[1]::
 358         Creates an empty git object database, or reinitialize an
 359         existing one.
 360
 361 gitlink:git-merge-file[1]::
 362         Runs a threeway merge.
 363
 364 gitlink:git-merge-index[1]::
 365         Runs a merge for files needing merging.
 366
 367 gitlink:git-mktag[1]::
 368         Creates a tag object.
 369
 370 gitlink:git-mktree[1]::
 371         Build a tree-object from ls-tree formatted text.
 372
 373 gitlink:git-pack-objects[1]::
 374         Creates a packed archive of objects.
 375
 376 gitlink:git-prune-packed[1]::
 377         Remove extra objects that are already in pack files.
 378
 379 gitlink:git-read-tree[1]::
 380         Reads tree information into the index.
 381
 382 gitlink:git-repo-config[1]::
 383         Get and set options in .git/config.
 384
 385 gitlink:git-unpack-objects[1]::
 386         Unpacks objects out of a packed archive.
 387
 388 gitlink:git-update-index[1]::
 389         Registers files in the working tree to the index.
 390
 391 gitlink:git-write-tree[1]::
 392         Creates a tree from the index.
 393
 394
 395 Interrogation commands
 396 ~~~~~~~~~~~~~~~~~~~~~~
 397
 398 gitlink:git-cat-file[1]::
 399         Provide content or type/size information for repository objects.
 400
 401 gitlink:git-describe[1]::
 402         Show the most recent tag that is reachable from a commit.
 403
 404 gitlink:git-diff-index[1]::
 405         Compares content and mode of blobs between the index and repository.
 406
 407 gitlink:git-diff-files[1]::
 408         Compares files in the working tree and the index.
 409
 410 gitlink:git-diff-stages[1]::
 411         Compares two "merge stages" in the index.
 412
 413 gitlink:git-diff-tree[1]::
 414         Compares the content and mode of blobs found via two tree objects.
 415
 416 gitlink:git-for-each-ref[1]::
 417         Output information on each ref.
 418
 419 gitlink:git-fsck-objects[1]::
 420         Verifies the connectivity and validity of the objects in the database.
 421
 422 gitlink:git-ls-files[1]::
 423         Information about files in the index and the working tree.
 424
 425 gitlink:git-ls-tree[1]::
 426         Displays a tree object in human readable form.
 427
 428 gitlink:git-merge-base[1]::
 429         Finds as good common ancestors as possible for a merge.
 430
 431 gitlink:git-name-rev[1]::
 432         Find symbolic names for given revs.
 433
 434 gitlink:git-pack-redundant[1]::
 435         Find redundant pack files.
 436
 437 gitlink:git-rev-list[1]::
 438         Lists commit objects in reverse chronological order.
 439
 440 gitlink:git-show-index[1]::
 441         Displays contents of a pack idx file.
 442
 443 gitlink:git-show-ref[1]::
 444         List references in a local repository.
 445
 446 gitlink:git-tar-tree[1]::
 447         Creates a tar archive of the files in the named tree object.
 448
 449 gitlink:git-unpack-file[1]::
 450         Creates a temporary file with a blob's contents.
 451
 452 gitlink:git-var[1]::
 453         Displays a git logical variable.
 454
 455 gitlink:git-verify-pack[1]::
 456         Validates packed git archive files.
 457
 458 In general, the interrogate commands do not touch the files in
 459 the working tree.
 460
 461
 462 Synching repositories
 463 ~~~~~~~~~~~~~~~~~~~~~
 464
 465 gitlink:git-fetch-pack[1]::
 466         Updates from a remote repository (engine for ssh and
 467         local transport).
 468
 469 gitlink:git-http-fetch[1]::
 470         Downloads a remote git repository via HTTP by walking
 471         commit chain.
 472
 473 gitlink:git-local-fetch[1]::
 474         Duplicates another git repository on a local system by
 475         walking commit chain.
 476
 477 gitlink:git-peek-remote[1]::
 478         Lists references on a remote repository using
 479         upload-pack protocol (engine for ssh and local
 480         transport).
 481
 482 gitlink:git-receive-pack[1]::
 483         Invoked by 'git-send-pack' to receive what is pushed to it.
 484
 485 gitlink:git-send-pack[1]::
 486         Pushes to a remote repository, intelligently.
 487
 488 gitlink:git-http-push[1]::
 489         Push missing objects using HTTP/DAV.
 490
 491 gitlink:git-shell[1]::
 492         Restricted shell for GIT-only SSH access.
 493
 494 gitlink:git-ssh-fetch[1]::
 495         Pulls from a remote repository over ssh connection by
 496         walking commit chain.
 497
 498 gitlink:git-ssh-upload[1]::
 499         Helper "server-side" program used by git-ssh-fetch.
 500
 501 gitlink:git-update-server-info[1]::
 502         Updates auxiliary information on a dumb server to help
 503         clients discover references and packs on it.
 504
 505 gitlink:git-upload-archive[1]::
 506         Invoked by 'git-archive' to send a generated archive.
 507
 508 gitlink:git-upload-pack[1]::
 509         Invoked by 'git-fetch-pack' to push
 510         what are asked for.
 511
 512
 513 Configuration Mechanism
 514 -----------------------
 515
 516 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
 517 is used to hold per-repository configuration options.  It is a
 518 simple text file modeled after `.ini` format familiar to some
 519 people.  Here is an example:
 520
 521 ------------
 522 #
 523 # A '#' or ';' character indicates a comment.
 524 #
 525
 526 ; core variables
 527 [core]
 528         ; Don't trust file modes
 529         filemode = false
 530
 531 ; user identity
 532 [user]
 533         name = "Junio C Hamano"
 534         email = "junkio@twinsun.com"
 535
 536 ------------
 537
 538 Various commands read from the configuration file and adjust
 539 their operation accordingly.
 540
 541
 542 Identifier Terminology
 543 ----------------------
 544 <object>::
 545         Indicates the object name for any type of object.
 546
 547 <blob>::
 548         Indicates a blob object name.
 549
 550 <tree>::
 551         Indicates a tree object name.
 552
 553 <commit>::
 554         Indicates a commit object name.
 555
 556 <tree-ish>::
 557         Indicates a tree, commit or tag object name.  A
 558         command that takes a <tree-ish> argument ultimately wants to
 559         operate on a <tree> object but automatically dereferences
 560         <commit> and <tag> objects that point at a <tree>.
 561
 562 <type>::
 563         Indicates that an object type is required.
 564         Currently one of: `blob`, `tree`, `commit`, or `tag`.
 565
 566 <file>::
 567         Indicates a filename - almost always relative to the
 568         root of the tree structure `GIT_INDEX_FILE` describes.
 569
 570 Symbolic Identifiers
 571 --------------------
 572 Any git command accepting any <object> can also use the following
 573 symbolic notation:
 574
 575 HEAD::
 576         indicates the head of the current branch (i.e. the
 577         contents of `$GIT_DIR/HEAD`).
 578
 579 <tag>::
 580         a valid tag 'name'
 581         (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
 582
 583 <head>::
 584         a valid head 'name'
 585         (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
 586
 587 For a more complete list of ways to spell object names, see
 588 "SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1].
 589
 590
 591 File/Directory Structure
 592 ------------------------
 593
 594 Please see link:repository-layout.html[repository layout] document.
 595
 596 Read link:hooks.html[hooks] for more details about each hook.
 597
 598 Higher level SCMs may provide and manage additional information in the
 599 `$GIT_DIR`.
 600
 601
 602 Terminology
 603 -----------
 604 Please see link:glossary.html[glossary] document.
 605
 606
 607 Environment Variables
 608 ---------------------
 609 Various git commands use the following environment variables:
 610
 611 The git Repository
 612 ~~~~~~~~~~~~~~~~~~
 613 These environment variables apply to 'all' core git commands. Nb: it
 614 is worth noting that they may be used/overridden by SCMS sitting above
 615 git so take care if using Cogito etc.
 616
 617 'GIT_INDEX_FILE'::
 618         This environment allows the specification of an alternate
 619         index file. If not specified, the default of `$GIT_DIR/index`
 620         is used.
 621
 622 'GIT_OBJECT_DIRECTORY'::
 623         If the object storage directory is specified via this
 624         environment variable then the sha1 directories are created
 625         underneath - otherwise the default `$GIT_DIR/objects`
 626         directory is used.
 627
 628 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
 629         Due to the immutable nature of git objects, old objects can be
 630         archived into shared, read-only directories. This variable
 631         specifies a ":" separated list of git object directories which
 632         can be used to search for git objects. New objects will not be
 633         written to these directories.
 634
 635 'GIT_DIR'::
 636         If the 'GIT_DIR' environment variable is set then it
 637         specifies a path to use instead of the default `.git`
 638         for the base of the repository.
 639
 640 git Commits
 641 ~~~~~~~~~~~
 642 'GIT_AUTHOR_NAME'::
 643 'GIT_AUTHOR_EMAIL'::
 644 'GIT_AUTHOR_DATE'::
 645 'GIT_COMMITTER_NAME'::
 646 'GIT_COMMITTER_EMAIL'::
 647         see gitlink:git-commit-tree[1]
 648
 649 git Diffs
 650 ~~~~~~~~~
 651 'GIT_DIFF_OPTS'::
 652         Only valid setting is "--unified=??" or "-u??" to set the
 653         number of context lines shown when a unified diff is created.
 654         This takes precedence over any "-U" or "--unified" option
 655         value passed on the git diff command line.
 656
 657 'GIT_EXTERNAL_DIFF'::
 658         When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
 659         program named by it is called, instead of the diff invocation
 660         described above.  For a path that is added, removed, or modified,
 661         'GIT_EXTERNAL_DIFF' is called with 7 parameters:
 662
 663         path old-file old-hex old-mode new-file new-hex new-mode
 664 +
 665 where:
 666
 667         <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
 668                          contents of <old|new>,
 669         <old|new>-hex:: are the 40-hexdigit SHA1 hashes,
 670         <old|new>-mode:: are the octal representation of the file modes.
 671
 672 +
 673 The file parameters can point at the user's working file
 674 (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
 675 when a new file is added), or a temporary file (e.g. `old-file` in the
 676 index).  'GIT_EXTERNAL_DIFF' should not worry about unlinking the
 677 temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
 678 +
 679 For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
 680 parameter, <path>.
 681
 682 other
 683 ~~~~~
 684 'GIT_PAGER'::
 685         This environment variable overrides `$PAGER`.
 686
 687 'GIT_TRACE'::
 688         If this variable is set to "1", "2" or "true" (comparison
 689         is case insensitive), git will print `trace:` messages on
 690         stderr telling about alias expansion, built-in command
 691         execution and external command execution.
 692         If this variable is set to an integer value greater than 1
 693         and lower than 10 (strictly) then git will interpret this
 694         value as an open file descriptor and will try to write the
 695         trace messages into this file descriptor.
 696         Alternatively, if this variable is set to an absolute path
 697         (starting with a '/' character), git will interpret this
 698         as a file path and will try to write the trace messages
 699         into it.
 700
 701 Discussion[[Discussion]]
 702 ------------------------
 703 include::README[]
 704
 705 Authors
 706 -------
 707 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
 708 * The current git nurse is Junio C Hamano <junkio@cox.net>.
 709 * The git potty was written by Andres Ericsson <ae@op5.se>.
 710 * General upbringing is handled by the git-list <git@vger.kernel.org>.
 711
 712 Documentation
 713 --------------
 714 The documentation for git suite was started by David Greaves
 715 <david@dgreaves.com>, and later enhanced greatly by the
 716 contributors on the git-list <git@vger.kernel.org>.
 717
 718 GIT
 719 ---
 720 Part of the gitlink:git[7] suite
 721