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