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