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