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