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