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-svnimport[1]::
 401         Import a SVN repository into git.
 402
 403 gitlink:git-sh-setup[1]::
 404         Common git shell script setup code.
 405
 406 gitlink:git-symbolic-ref[1]::
 407         Read and modify symbolic refs.
 408
 409 gitlink:git-tag[1]::
 410         An example script to create a tag object signed with GPG.
 411
 412 gitlink:git-update-ref[1]::
 413         Update the object name stored in a ref safely.
 414
 415
 416 Interrogators:
 417
 418 gitlink:git-annotate[1]::
 419         Annotate file lines with commit info.
 420
 421 gitlink:git-blame[1]::
 422         Blame file lines on commits.
 423
 424 gitlink:git-check-ref-format[1]::
 425         Make sure ref name is well formed.
 426
 427 gitlink:git-cherry[1]::
 428         Find commits not merged upstream.
 429
 430 gitlink:git-count-objects[1]::
 431         Count unpacked number of objects and their disk consumption.
 432
 433 gitlink:git-daemon[1]::
 434         A really simple server for git repositories.
 435
 436 gitlink:git-fmt-merge-msg[1]::
 437         Produce a merge commit message.
 438
 439 gitlink:git-get-tar-commit-id[1]::
 440         Extract commit ID from an archive created using git-tar-tree.
 441
 442 gitlink:git-imap-send[1]::
 443         Dump a mailbox from stdin into an imap folder.
 444
 445 gitlink:git-mailinfo[1]::
 446         Extracts patch and authorship information from a single
 447         e-mail message, optionally transliterating the commit
 448         message into utf-8.
 449
 450 gitlink:git-mailsplit[1]::
 451         A stupid program to split UNIX mbox format mailbox into
 452         individual pieces of e-mail.
 453
 454 gitlink:git-merge-tree[1]::
 455         Show three-way merge without touching index.
 456
 457 gitlink:git-patch-id[1]::
 458         Compute unique ID for a patch.
 459
 460 gitlink:git-parse-remote[1]::
 461         Routines to help parsing `$GIT_DIR/remotes/` files.
 462
 463 gitlink:git-request-pull[1]::
 464         git-request-pull.
 465
 466 gitlink:git-rev-parse[1]::
 467         Pick out and massage parameters.
 468
 469 gitlink:git-send-email[1]::
 470         Send patch e-mails out of "format-patch --mbox" output.
 471
 472 gitlink:git-symbolic-ref[1]::
 473         Read and modify symbolic refs.
 474
 475 gitlink:git-stripspace[1]::
 476         Filter out empty lines.
 477
 478
 479 Commands not yet documented
 480 ---------------------------
 481
 482 gitlink:gitk[1]::
 483         The gitk repository browser.
 484
 485
 486 Configuration Mechanism
 487 -----------------------
 488
 489 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
 490 is used to hold per-repository configuration options.  It is a
 491 simple text file modeled after `.ini` format familiar to some
 492 people.  Here is an example:
 493
 494 ------------
 495 #
 496 # A '#' or ';' character indicates a comment.
 497 #
 498
 499 ; core variables
 500 [core]
 501         ; Don't trust file modes
 502         filemode = false
 503
 504 ; user identity
 505 [user]
 506         name = "Junio C Hamano"
 507         email = "junkio@twinsun.com"
 508
 509 ------------
 510
 511 Various commands read from the configuration file and adjust
 512 their operation accordingly.
 513
 514
 515 Identifier Terminology
 516 ----------------------
 517 <object>::
 518         Indicates the object name for any type of object.
 519
 520 <blob>::
 521         Indicates a blob object name.
 522
 523 <tree>::
 524         Indicates a tree object name.
 525
 526 <commit>::
 527         Indicates a commit object name.
 528
 529 <tree-ish>::
 530         Indicates a tree, commit or tag object name.  A
 531         command that takes a <tree-ish> argument ultimately wants to
 532         operate on a <tree> object but automatically dereferences
 533         <commit> and <tag> objects that point at a <tree>.
 534
 535 <type>::
 536         Indicates that an object type is required.
 537         Currently one of: `blob`, `tree`, `commit`, or `tag`.
 538
 539 <file>::
 540         Indicates a filename - almost always relative to the
 541         root of the tree structure `GIT_INDEX_FILE` describes.
 542
 543 Symbolic Identifiers
 544 --------------------
 545 Any git command accepting any <object> can also use the following
 546 symbolic notation:
 547
 548 HEAD::
 549         indicates the head of the current branch (i.e. the
 550         contents of `$GIT_DIR/HEAD`).
 551
 552 <tag>::
 553         a valid tag 'name'
 554         (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
 555
 556 <head>::
 557         a valid head 'name'
 558         (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
 559
 560
 561 File/Directory Structure
 562 ------------------------
 563
 564 Please see link:repository-layout.html[repository layout] document.
 565
 566 Read link:hooks.html[hooks] for more details about each hook.
 567
 568 Higher level SCMs may provide and manage additional information in the
 569 `$GIT_DIR`.
 570
 571
 572 Terminology
 573 -----------
 574 Please see link:glossary.html[glossary] document.
 575
 576
 577 Environment Variables
 578 ---------------------
 579 Various git commands use the following environment variables:
 580
 581 The git Repository
 582 ~~~~~~~~~~~~~~~~~~
 583 These environment variables apply to 'all' core git commands. Nb: it
 584 is worth noting that they may be used/overridden by SCMS sitting above
 585 git so take care if using Cogito etc.
 586
 587 'GIT_INDEX_FILE'::
 588         This environment allows the specification of an alternate
 589         index file. If not specified, the default of `$GIT_DIR/index`
 590         is used.
 591
 592 'GIT_OBJECT_DIRECTORY'::
 593         If the object storage directory is specified via this
 594         environment variable then the sha1 directories are created
 595         underneath - otherwise the default `$GIT_DIR/objects`
 596         directory is used.
 597
 598 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
 599         Due to the immutable nature of git objects, old objects can be
 600         archived into shared, read-only directories. This variable
 601         specifies a ":" separated list of git object directories which
 602         can be used to search for git objects. New objects will not be
 603         written to these directories.
 604
 605 'GIT_DIR'::
 606         If the 'GIT_DIR' environment variable is set then it
 607         specifies a path to use instead of the default `.git`
 608         for the base of the repository.
 609
 610 git Commits
 611 ~~~~~~~~~~~
 612 'GIT_AUTHOR_NAME'::
 613 'GIT_AUTHOR_EMAIL'::
 614 'GIT_AUTHOR_DATE'::
 615 'GIT_COMMITTER_NAME'::
 616 'GIT_COMMITTER_EMAIL'::
 617         see gitlink:git-commit-tree[1]
 618
 619 git Diffs
 620 ~~~~~~~~~
 621 'GIT_DIFF_OPTS'::
 622 'GIT_EXTERNAL_DIFF'::
 623         see the "generating patches" section in :
 624         gitlink:git-diff-index[1];
 625         gitlink:git-diff-files[1];
 626         gitlink:git-diff-tree[1]
 627
 628 other
 629 ~~~~~
 630 'GIT_TRACE'::
 631         If this variable is set git will print `trace:` messages on
 632         stderr telling about alias expansion, built-in command
 633         execution and external command execution.
 634
 635 Discussion[[Discussion]]
 636 ------------------------
 637 include::README[]
 638
 639 Authors
 640 -------
 641 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
 642 * The current git nurse is Junio C Hamano <junkio@cox.net>.
 643 * The git potty was written by Andres Ericsson <ae@op5.se>.
 644 * General upbringing is handled by the git-list <git@vger.kernel.org>.
 645
 646 Documentation
 647 --------------
 648 The documentation for git suite was started by David Greaves
 649 <david@dgreaves.com>, and later enhanced greatly by the
 650 contributors on the git-list <git@vger.kernel.org>.
 651
 652 GIT
 653 ---
 654 Part of the gitlink:git[7] suite
 655