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