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 Low-level commands (plumbing)
  76 -----------------------------
  77
  78 Although git includes its
  79 own porcelain layer, its low-level commands are sufficient to support
  80 development of alternative porcelains.  Developers of such porcelains
  81 might start by reading about gitlink:git-update-index[1] and
  82 gitlink:git-read-tree[1].
  83
  84 We divide the low-level commands into commands that manipulate objects (in
  85 the repository, index, and working tree), commands that interrogate and
  86 compare objects, and commands that move objects and references between
  87 repositories.
  88
  89 Manipulation commands
  90 ~~~~~~~~~~~~~~~~~~~~~
  91 gitlink:git-apply[1]::
  92         Reads a "diff -up1" or git generated patch file and
  93         applies it to the working tree.
  94
  95 gitlink:git-checkout-index[1]::
  96         Copy files from the index to the working tree.
  97
  98 gitlink:git-commit-tree[1]::
  99         Creates a new commit object.
 100
 101 gitlink:git-hash-object[1]::
 102         Computes the object ID from a file.
 103
 104 gitlink:git-index-pack[1]::
 105         Build pack idx file for an existing packed archive.
 106
 107 gitlink:git-init-db[1]::
 108         Creates an empty git object database, or reinitialize an
 109         existing one.
 110
 111 gitlink:git-merge-index[1]::
 112         Runs a merge for files needing merging.
 113
 114 gitlink:git-mktag[1]::
 115         Creates a tag object.
 116
 117 gitlink:git-mktree[1]::
 118         Build a tree-object from ls-tree formatted text.
 119
 120 gitlink:git-pack-objects[1]::
 121         Creates a packed archive of objects.
 122
 123 gitlink:git-prune-packed[1]::
 124         Remove extra objects that are already in pack files.
 125
 126 gitlink:git-read-tree[1]::
 127         Reads tree information into the index.
 128
 129 gitlink:git-repo-config[1]::
 130         Get and set options in .git/config.
 131
 132 gitlink:git-unpack-objects[1]::
 133         Unpacks objects out of a packed archive.
 134
 135 gitlink:git-update-index[1]::
 136         Registers files in the working tree to the index.
 137
 138 gitlink:git-write-tree[1]::
 139         Creates a tree from the index.
 140
 141
 142 Interrogation commands
 143 ~~~~~~~~~~~~~~~~~~~~~~
 144
 145 gitlink:git-cat-file[1]::
 146         Provide content or type/size information for repository objects.
 147
 148 gitlink:git-describe[1]::
 149         Show the most recent tag that is reachable from a commit.
 150
 151 gitlink:git-diff-index[1]::
 152         Compares content and mode of blobs between the index and repository.
 153
 154 gitlink:git-diff-files[1]::
 155         Compares files in the working tree and the index.
 156
 157 gitlink:git-diff-stages[1]::
 158         Compares two "merge stages" in the index.
 159
 160 gitlink:git-diff-tree[1]::
 161         Compares the content and mode of blobs found via two tree objects.
 162
 163 gitlink:git-for-each-ref[1]::
 164         Output information on each ref.
 165
 166 gitlink:git-fsck-objects[1]::
 167         Verifies the connectivity and validity of the objects in the database.
 168
 169 gitlink:git-ls-files[1]::
 170         Information about files in the index and the working tree.
 171
 172 gitlink:git-ls-tree[1]::
 173         Displays a tree object in human readable form.
 174
 175 gitlink:git-merge-base[1]::
 176         Finds as good common ancestors as possible for a merge.
 177
 178 gitlink:git-name-rev[1]::
 179         Find symbolic names for given revs.
 180
 181 gitlink:git-pack-redundant[1]::
 182         Find redundant pack files.
 183
 184 gitlink:git-rev-list[1]::
 185         Lists commit objects in reverse chronological order.
 186
 187 gitlink:git-show-index[1]::
 188         Displays contents of a pack idx file.
 189
 190 gitlink:git-tar-tree[1]::
 191         Creates a tar archive of the files in the named tree object.
 192
 193 gitlink:git-unpack-file[1]::
 194         Creates a temporary file with a blob's contents.
 195
 196 gitlink:git-var[1]::
 197         Displays a git logical variable.
 198
 199 gitlink:git-verify-pack[1]::
 200         Validates packed git archive files.
 201
 202 In general, the interrogate commands do not touch the files in
 203 the working tree.
 204
 205
 206 Synching repositories
 207 ~~~~~~~~~~~~~~~~~~~~~
 208
 209 gitlink:git-fetch-pack[1]::
 210         Updates from a remote repository (engine for ssh and
 211         local transport).
 212
 213 gitlink:git-http-fetch[1]::
 214         Downloads a remote git repository via HTTP by walking
 215         commit chain.
 216
 217 gitlink:git-local-fetch[1]::
 218         Duplicates another git repository on a local system by
 219         walking commit chain.
 220
 221 gitlink:git-peek-remote[1]::
 222         Lists references on a remote repository using
 223         upload-pack protocol (engine for ssh and local
 224         transport).
 225
 226 gitlink:git-receive-pack[1]::
 227         Invoked by 'git-send-pack' to receive what is pushed to it.
 228
 229 gitlink:git-send-pack[1]::
 230         Pushes to a remote repository, intelligently.
 231
 232 gitlink:git-http-push[1]::
 233         Push missing objects using HTTP/DAV.
 234
 235 gitlink:git-shell[1]::
 236         Restricted shell for GIT-only SSH access.
 237
 238 gitlink:git-ssh-fetch[1]::
 239         Pulls from a remote repository over ssh connection by
 240         walking commit chain.
 241
 242 gitlink:git-ssh-upload[1]::
 243         Helper "server-side" program used by git-ssh-fetch.
 244
 245 gitlink:git-update-server-info[1]::
 246         Updates auxiliary information on a dumb server to help
 247         clients discover references and packs on it.
 248
 249 gitlink:git-upload-archive[1]::
 250         Invoked by 'git-archive' to send a generated archive.
 251
 252 gitlink:git-upload-pack[1]::
 253         Invoked by 'git-fetch-pack' to push
 254         what are asked for.
 255
 256
 257 High-level commands (porcelain)
 258 -------------------------------
 259
 260 We separate the porcelain commands into the main commands and some
 261 ancillary user utilities.
 262
 263 Main porcelain commands
 264 ~~~~~~~~~~~~~~~~~~~~~~~
 265
 266 gitlink:git-add[1]::
 267         Add paths to the index.
 268
 269 gitlink:git-am[1]::
 270         Apply patches from a mailbox, but cooler.
 271
 272 gitlink:git-applymbox[1]::
 273         Apply patches from a mailbox, original version by Linus.
 274
 275 gitlink:git-archive[1]::
 276         Creates an archive of files from a named tree.
 277
 278 gitlink:git-bisect[1]::
 279         Find the change that introduced a bug by binary search.
 280
 281 gitlink:git-branch[1]::
 282         Create and Show branches.
 283
 284 gitlink:git-checkout[1]::
 285         Checkout and switch to a branch.
 286
 287 gitlink:git-cherry-pick[1]::
 288         Cherry-pick the effect of an existing commit.
 289
 290 gitlink:git-clean[1]::
 291         Remove untracked files from the working tree.
 292
 293 gitlink:git-clone[1]::
 294         Clones a repository into a new directory.
 295
 296 gitlink:git-commit[1]::
 297         Record changes to the repository.
 298
 299 gitlink:git-diff[1]::
 300         Show changes between commits, commit and working tree, etc.
 301
 302 gitlink:git-fetch[1]::
 303         Download from a remote repository via various protocols.
 304
 305 gitlink:git-format-patch[1]::
 306         Prepare patches for e-mail submission.
 307
 308 gitlink:git-grep[1]::
 309         Print lines matching a pattern.
 310
 311 gitlink:gitk[1]::
 312         The git repository browser.
 313
 314 gitlink:git-log[1]::
 315         Shows commit logs.
 316
 317 gitlink:git-ls-remote[1]::
 318         Shows references in a remote or local repository.
 319
 320 gitlink:git-merge[1]::
 321         Grand unified merge driver.
 322
 323 gitlink:git-mv[1]::
 324         Move or rename a file, a directory, or a symlink.
 325
 326 gitlink:git-pull[1]::
 327         Fetch from and merge with a remote repository.
 328
 329 gitlink:git-push[1]::
 330         Update remote refs along with associated objects.
 331
 332 gitlink:git-rebase[1]::
 333         Rebase local commits to the updated upstream head.
 334
 335 gitlink:git-repack[1]::
 336         Pack unpacked objects in a repository.
 337
 338 gitlink:git-rerere[1]::
 339         Reuse recorded resolution of conflicted merges.
 340
 341 gitlink:git-reset[1]::
 342         Reset current HEAD to the specified state.
 343
 344 gitlink:git-resolve[1]::
 345         Merge two commits.
 346
 347 gitlink:git-revert[1]::
 348         Revert an existing commit.
 349
 350 gitlink:git-rm[1]::
 351         Remove files from the working tree and from the index.
 352
 353 gitlink:git-shortlog[1]::
 354         Summarizes 'git log' output.
 355
 356 gitlink:git-show[1]::
 357         Show one commit log and its diff.
 358
 359 gitlink:git-show-branch[1]::
 360         Show branches and their commits.
 361
 362 gitlink:git-status[1]::
 363         Shows the working tree status.
 364
 365 gitlink:git-verify-tag[1]::
 366         Check the GPG signature of tag.
 367
 368 gitlink:git-whatchanged[1]::
 369         Shows commit logs and differences they introduce.
 370
 371
 372 Ancillary Commands
 373 ~~~~~~~~~~~~~~~~~~
 374 Manipulators:
 375
 376 gitlink:git-applypatch[1]::
 377         Apply one patch extracted from an e-mail.
 378
 379 gitlink:git-archimport[1]::
 380         Import an arch repository into git.
 381
 382 gitlink:git-convert-objects[1]::
 383         Converts old-style git repository.
 384
 385 gitlink:git-cvsimport[1]::
 386         Salvage your data out of another SCM people love to hate.
 387
 388 gitlink:git-cvsexportcommit[1]::
 389         Export a single commit to a CVS checkout.
 390
 391 gitlink:git-cvsserver[1]::
 392         A CVS server emulator for git.
 393
 394 gitlink:git-lost-found[1]::
 395         Recover lost refs that luckily have not yet been pruned.
 396
 397 gitlink:git-merge-one-file[1]::
 398         The standard helper program to use with `git-merge-index`.
 399
 400 gitlink:git-prune[1]::
 401         Prunes all unreachable objects from the object database.
 402
 403 gitlink:git-quiltimport[1]::
 404         Applies a quilt patchset onto the current branch.
 405
 406 gitlink:git-relink[1]::
 407         Hardlink common objects in local repositories.
 408
 409 gitlink:git-svn[1]::
 410         Bidirectional operation between a single Subversion branch and git.
 411
 412 gitlink:git-svnimport[1]::
 413         Import a SVN repository into git.
 414
 415 gitlink:git-sh-setup[1]::
 416         Common git shell script setup code.
 417
 418 gitlink:git-symbolic-ref[1]::
 419         Read and modify symbolic refs.
 420
 421 gitlink:git-tag[1]::
 422         An example script to create a tag object signed with GPG.
 423
 424 gitlink:git-update-ref[1]::
 425         Update the object name stored in a ref safely.
 426
 427
 428 Interrogators:
 429
 430 gitlink:git-annotate[1]::
 431         Annotate file lines with commit info.
 432
 433 gitlink:git-blame[1]::
 434         Blame file lines on commits.
 435
 436 gitlink:git-check-ref-format[1]::
 437         Make sure ref name is well formed.
 438
 439 gitlink:git-cherry[1]::
 440         Find commits not merged upstream.
 441
 442 gitlink:git-count-objects[1]::
 443         Count unpacked number of objects and their disk consumption.
 444
 445 gitlink:git-daemon[1]::
 446         A really simple server for git repositories.
 447
 448 gitlink:git-fmt-merge-msg[1]::
 449         Produce a merge commit message.
 450
 451 gitlink:git-get-tar-commit-id[1]::
 452         Extract commit ID from an archive created using git-tar-tree.
 453
 454 gitlink:git-imap-send[1]::
 455         Dump a mailbox from stdin into an imap folder.
 456
 457 gitlink:git-instaweb[1]::
 458         Instantly browse your working repository in gitweb.
 459
 460 gitlink:git-mailinfo[1]::
 461         Extracts patch and authorship information from a single
 462         e-mail message, optionally transliterating the commit
 463         message into utf-8.
 464
 465 gitlink:git-mailsplit[1]::
 466         A stupid program to split UNIX mbox format mailbox into
 467         individual pieces of e-mail.
 468
 469 gitlink:git-merge-tree[1]::
 470         Show three-way merge without touching index.
 471
 472 gitlink:git-patch-id[1]::
 473         Compute unique ID for a patch.
 474
 475 gitlink:git-parse-remote[1]::
 476         Routines to help parsing `$GIT_DIR/remotes/` files.
 477
 478 gitlink:git-request-pull[1]::
 479         git-request-pull.
 480
 481 gitlink:git-rev-parse[1]::
 482         Pick out and massage parameters.
 483
 484 gitlink:git-send-email[1]::
 485         Send patch e-mails out of "format-patch --mbox" output.
 486
 487 gitlink:git-symbolic-ref[1]::
 488         Read and modify symbolic refs.
 489
 490 gitlink:git-stripspace[1]::
 491         Filter out empty lines.
 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