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