Documentation/git.txt

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