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 both a program and a directory content tracker system.
  16 The program 'git' is just a wrapper to reach the core git programs
  17 (or a potty if you like, as it's not exactly porcelain but still
  18 brings your stuff to the plumbing).
  19
  20 OPTIONS
  21 -------
  22 --version::
  23         Prints the git suite version that the 'git' program came from.
  24
  25 --help::
  26         Prints the synopsis and a list of the most commonly used
  27         commands.  If a git command is named this option will bring up
  28         the man-page for that command. If the option '--all' or '-a' is
  29         given then all available commands are printed.
  30
  31 --exec-path::
  32         Path to wherever your core git programs are installed.
  33         This can also be controlled by setting the GIT_EXEC_PATH
  34         environment variable. If no path is given 'git' will print
  35         the current setting and then exit.
  36
  37
  38 NOT LEARNING CORE GIT COMMANDS
  39 ------------------------------
  40
  41 This manual is intended to give complete background information
  42 and internal workings of git, which may be too much for most
  43 people.  The <<Discussion>> section below contains much useful
  44 definition and clarification - read that first.
  45
  46 If you are interested in using git to manage (version control)
  47 projects, use link:tutorial.html[The Tutorial] to get you started,
  48 and then link:everyday.html[Everyday GIT] as a guide to the
  49 minimum set of commands you need to know for day-to-day work.
  50 Most likely, that will get you started, and you can go a long
  51 way without knowing the low level details too much.
  52
  53 The link:core-tutorial.html[Core tutorial] document covers how things
  54 internally work.
  55
  56 If you are migrating from CVS, link:cvs-migration.html[cvs
  57 migration] document may be helpful after you finish the
  58 tutorial.
  59
  60 After you get the general feel from the tutorial and this
  61 overview page, you may want to take a look at the
  62 link:howto-index.html[howto] documents.
  63
  64
  65 CORE GIT COMMANDS
  66 -----------------
  67
  68 If you are writing your own Porcelain, you need to be familiar
  69 with most of the low level commands --- I suggest starting from
  70 gitlink:git-update-index[1] and gitlink:git-read-tree[1].
  71
  72
  73 Commands Overview
  74 -----------------
  75 The git commands can helpfully be split into those that manipulate
  76 the repository, the index and the files in the working tree, those that
  77 interrogate and compare them, and those that moves objects and
  78 references between repositories.
  79
  80 In addition, git itself comes with a spartan set of porcelain
  81 commands.  They are usable but are not meant to compete with real
  82 Porcelains.
  83
  84 There are also some ancillary programs that can be viewed as useful
  85 aids for using the core commands but which are unlikely to be used by
  86 SCMs layered over git.
  87
  88 Manipulation commands
  89 ~~~~~~~~~~~~~~~~~~~~~
  90 gitlink:git-apply[1]::
  91         Reads a "diff -up1" or git generated patch file and
  92         applies it to the working tree.
  93
  94 gitlink:git-checkout-index[1]::
  95         Copy files from the index to the working tree.
  96
  97 gitlink:git-commit-tree[1]::
  98         Creates a new commit object.
  99
 100 gitlink:git-hash-object[1]::
 101         Computes the object ID from a file.
 102
 103 gitlink:git-index-pack[1]::
 104         Build pack idx file for an existing packed archive.
 105
 106 gitlink:git-init-db[1]::
 107         Creates an empty git object database, or reinitialize an
 108         existing one.
 109
 110 gitlink:git-merge-index[1]::
 111         Runs a merge for files needing merging.
 112
 113 gitlink:git-mktag[1]::
 114         Creates a tag object.
 115
 116 gitlink:git-pack-objects[1]::
 117         Creates a packed archive of objects.
 118
 119 gitlink:git-prune-packed[1]::
 120         Remove extra objects that are already in pack files.
 121
 122 gitlink:git-read-tree[1]::
 123         Reads tree information into the index.
 124
 125 gitlink:git-repo-config[1]::
 126         Get and set options in .git/config.
 127
 128 gitlink:git-unpack-objects[1]::
 129         Unpacks objects out of a packed archive.
 130
 131 gitlink:git-update-index[1]::
 132         Registers files in the working tree to the index.
 133
 134 gitlink:git-write-tree[1]::
 135         Creates a tree from the index.
 136
 137
 138 Interrogation commands
 139 ~~~~~~~~~~~~~~~~~~~~~~
 140
 141 gitlink:git-cat-file[1]::
 142         Provide content or type/size information for repository objects.
 143
 144 gitlink:git-describe[1]::
 145         Show the most recent tag that is reachable from a commit.
 146
 147 gitlink:git-diff-index[1]::
 148         Compares content and mode of blobs between the index and repository.
 149
 150 gitlink:git-diff-files[1]::
 151         Compares files in the working tree and the index.
 152
 153 gitlink:git-diff-stages[1]::
 154         Compares two "merge stages" in the index.
 155
 156 gitlink:git-diff-tree[1]::
 157         Compares the content and mode of blobs found via two tree objects.
 158
 159 gitlink:git-fsck-objects[1]::
 160         Verifies the connectivity and validity of the objects in the database.
 161
 162 gitlink:git-ls-files[1]::
 163         Information about files in the index and the working tree.
 164
 165 gitlink:git-ls-tree[1]::
 166         Displays a tree object in human readable form.
 167
 168 gitlink:git-merge-base[1]::
 169         Finds as good common ancestors as possible for a merge.
 170
 171 gitlink:git-name-rev[1]::
 172         Find symbolic names for given revs.
 173
 174 gitlink:git-pack-redundant[1]::
 175         Find redundant pack files.
 176
 177 gitlink:git-rev-list[1]::
 178         Lists commit objects in reverse chronological order.
 179
 180 gitlink:git-show-index[1]::
 181         Displays contents of a pack idx file.
 182
 183 gitlink:git-tar-tree[1]::
 184         Creates a tar archive of the files in the named tree object.
 185
 186 gitlink:git-unpack-file[1]::
 187         Creates a temporary file with a blob's contents.
 188
 189 gitlink:git-var[1]::
 190         Displays a git logical variable.
 191
 192 gitlink:git-verify-pack[1]::
 193         Validates packed git archive files.
 194
 195 In general, the interrogate commands do not touch the files in
 196 the working tree.
 197
 198
 199 Synching repositories
 200 ~~~~~~~~~~~~~~~~~~~~~
 201
 202 gitlink:git-clone-pack[1]::
 203         Clones a repository into the current repository (engine
 204         for ssh and local transport).
 205
 206 gitlink:git-fetch-pack[1]::
 207         Updates from a remote repository (engine for ssh and
 208         local transport).
 209
 210 gitlink:git-http-fetch[1]::
 211         Downloads a remote git repository via HTTP by walking
 212         commit chain.
 213
 214 gitlink:git-local-fetch[1]::
 215         Duplicates another git repository on a local system by
 216         walking commit chain.
 217
 218 gitlink:git-peek-remote[1]::
 219         Lists references on a remote repository using
 220         upload-pack protocol (engine for ssh and local
 221         transport).
 222
 223 gitlink:git-receive-pack[1]::
 224         Invoked by 'git-send-pack' to receive what is pushed to it.
 225
 226 gitlink:git-send-pack[1]::
 227         Pushes to a remote repository, intelligently.
 228
 229 gitlink:git-http-push[1]::
 230         Push missing objects using HTTP/DAV.
 231
 232 gitlink:git-shell[1]::
 233         Restricted shell for GIT-only SSH access.
 234
 235 gitlink:git-ssh-fetch[1]::
 236         Pulls from a remote repository over ssh connection by
 237         walking commit chain.
 238
 239 gitlink:git-ssh-upload[1]::
 240         Helper "server-side" program used by git-ssh-fetch.
 241
 242 gitlink:git-update-server-info[1]::
 243         Updates auxiliary information on a dumb server to help
 244         clients discover references and packs on it.
 245
 246 gitlink:git-upload-pack[1]::
 247         Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
 248         what are asked for.
 249
 250
 251 Porcelain-ish 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-clone[1]::
 276         Clones a repository into a new directory.
 277
 278 gitlink:git-commit[1]::
 279         Record changes to the repository.
 280
 281 gitlink:git-diff[1]::
 282         Show changes between commits, commit and working tree, etc.
 283
 284 gitlink:git-fetch[1]::
 285         Download from a remote repository via various protocols.
 286
 287 gitlink:git-format-patch[1]::
 288         Prepare patches for e-mail submission.
 289
 290 gitlink:git-grep[1]::
 291         Print lines matching a pattern.
 292
 293 gitlink:git-log[1]::
 294         Shows commit logs.
 295
 296 gitlink:git-ls-remote[1]::
 297         Shows references in a remote or local repository.
 298
 299 gitlink:git-merge[1]::
 300         Grand unified merge driver.
 301
 302 gitlink:git-mv[1]::
 303         Move or rename a file, a directory, or a symlink.
 304
 305 gitlink:git-pull[1]::
 306         Fetch from and merge with a remote repository.
 307
 308 gitlink:git-push[1]::
 309         Update remote refs along with associated objects.
 310
 311 gitlink:git-rebase[1]::
 312         Rebase local commits to the updated upstream head.
 313
 314 gitlink:git-repack[1]::
 315         Pack unpacked objects in a repository.
 316
 317 gitlink:git-rerere[1]::
 318         Reuse recorded resolution of conflicted merges.
 319
 320 gitlink:git-reset[1]::
 321         Reset current HEAD to the specified state.
 322
 323 gitlink:git-resolve[1]::
 324         Merge two commits.
 325
 326 gitlink:git-revert[1]::
 327         Revert an existing commit.
 328
 329 gitlink:git-shortlog[1]::
 330         Summarizes 'git log' output.
 331
 332 gitlink:git-show[1]::
 333         Show one commit log and its diff.
 334
 335 gitlink:git-show-branch[1]::
 336         Show branches and their commits.
 337
 338 gitlink:git-status[1]::
 339         Shows the working tree status.
 340
 341 gitlink:git-verify-tag[1]::
 342         Check the GPG signature of tag.
 343
 344 gitlink:git-whatchanged[1]::
 345         Shows commit logs and differences they introduce.
 346
 347
 348 Ancillary Commands
 349 ------------------
 350 Manipulators:
 351
 352 gitlink:git-applypatch[1]::
 353         Apply one patch extracted from an e-mail.
 354
 355 gitlink:git-archimport[1]::
 356         Import an arch repository into git.
 357
 358 gitlink:git-convert-objects[1]::
 359         Converts old-style git repository.
 360
 361 gitlink:git-cvsimport[1]::
 362         Salvage your data out of another SCM people love to hate.
 363
 364 gitlink:git-cvsexportcommit[1]::
 365         Export a single commit to a CVS checkout.
 366
 367 gitlink:git-lost-found[1]::
 368         Recover lost refs that luckily have not yet been pruned.
 369
 370 gitlink:git-merge-one-file[1]::
 371         The standard helper program to use with `git-merge-index`.
 372
 373 gitlink:git-prune[1]::
 374         Prunes all unreachable objects from the object database.
 375
 376 gitlink:git-relink[1]::
 377         Hardlink common objects in local repositories.
 378
 379 gitlink:git-svnimport[1]::
 380         Import a SVN repository into git.
 381
 382 gitlink:git-sh-setup[1]::
 383         Common git shell script setup code.
 384
 385 gitlink:git-symbolic-ref[1]::
 386         Read and modify symbolic refs.
 387
 388 gitlink:git-tag[1]::
 389         An example script to create a tag object signed with GPG.
 390
 391 gitlink:git-update-ref[1]::
 392         Update the object name stored in a ref safely.
 393
 394
 395 Interrogators:
 396
 397 gitlink:git-check-ref-format[1]::
 398         Make sure ref name is well formed.
 399
 400 gitlink:git-cherry[1]::
 401         Find commits not merged upstream.
 402
 403 gitlink:git-count-objects[1]::
 404         Count unpacked number of objects and their disk consumption.
 405
 406 gitlink:git-daemon[1]::
 407         A really simple server for git repositories.
 408
 409 gitlink:git-get-tar-commit-id[1]::
 410         Extract commit ID from an archive created using git-tar-tree.
 411
 412 gitlink:git-mailinfo[1]::
 413         Extracts patch and authorship information from a single
 414         e-mail message, optionally transliterating the commit
 415         message into utf-8.
 416
 417 gitlink:git-mailsplit[1]::
 418         A stupid program to split UNIX mbox format mailbox into
 419         individual pieces of e-mail.
 420
 421 gitlink:git-patch-id[1]::
 422         Compute unique ID for a patch.
 423
 424 gitlink:git-parse-remote[1]::
 425         Routines to help parsing `$GIT_DIR/remotes/` files.
 426
 427 gitlink:git-request-pull[1]::
 428         git-request-pull.
 429
 430 gitlink:git-rev-parse[1]::
 431         Pick out and massage parameters.
 432
 433 gitlink:git-send-email[1]::
 434         Send patch e-mails out of "format-patch --mbox" output.
 435
 436 gitlink:git-symbolic-ref[1]::
 437         Read and modify symbolic refs.
 438
 439 gitlink:git-stripspace[1]::
 440         Filter out empty lines.
 441
 442
 443 Commands not yet documented
 444 ---------------------------
 445
 446 gitlink:gitk[1]::
 447         The gitk repository browser.
 448
 449
 450 Configuration Mechanism
 451 -----------------------
 452
 453 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
 454 is used to hold per-repository configuration options.  It is a
 455 simple text file modelled after `.ini` format familiar to some
 456 people.  Here is an example:
 457
 458 ------------
 459 #
 460 # A '#' or ';' character indicates a comment.
 461 #
 462
 463 ; core variables
 464 [core]
 465         ; Don't trust file modes
 466         filemode = false
 467
 468 ; user identity
 469 [user]
 470         name = "Junio C Hamano"
 471         email = "junkio@twinsun.com"
 472
 473 ------------
 474
 475 Various commands read from the configuration file and adjust
 476 their operation accordingly.
 477
 478
 479 Identifier Terminology
 480 ----------------------
 481 <object>::
 482         Indicates the object name for any type of object.
 483
 484 <blob>::
 485         Indicates a blob object name.
 486
 487 <tree>::
 488         Indicates a tree object name.
 489
 490 <commit>::
 491         Indicates a commit object name.
 492
 493 <tree-ish>::
 494         Indicates a tree, commit or tag object name.  A
 495         command that takes a <tree-ish> argument ultimately wants to
 496         operate on a <tree> object but automatically dereferences
 497         <commit> and <tag> objects that point at a <tree>.
 498
 499 <type>::
 500         Indicates that an object type is required.
 501         Currently one of: `blob`, `tree`, `commit`, or `tag`.
 502
 503 <file>::
 504         Indicates a filename - almost always relative to the
 505         root of the tree structure `GIT_INDEX_FILE` describes.
 506
 507 Symbolic Identifiers
 508 --------------------
 509 Any git command accepting any <object> can also use the following
 510 symbolic notation:
 511
 512 HEAD::
 513         indicates the head of the current branch (i.e. the
 514         contents of `$GIT_DIR/HEAD`).
 515
 516 <tag>::
 517         a valid tag 'name'
 518         (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
 519
 520 <head>::
 521         a valid head 'name'
 522         (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
 523
 524 <snap>::
 525         a valid snapshot 'name'
 526         (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
 527
 528
 529 File/Directory Structure
 530 ------------------------
 531
 532 Please see link:repository-layout.html[repository layout] document.
 533
 534 Higher level SCMs may provide and manage additional information in the
 535 `$GIT_DIR`.
 536
 537
 538 Terminology
 539 -----------
 540 Please see link:glossary.html[glossary] document.
 541
 542
 543 Environment Variables
 544 ---------------------
 545 Various git commands use the following environment variables:
 546
 547 The git Repository
 548 ~~~~~~~~~~~~~~~~~~
 549 These environment variables apply to 'all' core git commands. Nb: it
 550 is worth noting that they may be used/overridden by SCMS sitting above
 551 git so take care if using Cogito etc.
 552
 553 'GIT_INDEX_FILE'::
 554         This environment allows the specification of an alternate
 555         index file. If not specified, the default of `$GIT_DIR/index`
 556         is used.
 557
 558 'GIT_OBJECT_DIRECTORY'::
 559         If the object storage directory is specified via this
 560         environment variable then the sha1 directories are created
 561         underneath - otherwise the default `$GIT_DIR/objects`
 562         directory is used.
 563
 564 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
 565         Due to the immutable nature of git objects, old objects can be
 566         archived into shared, read-only directories. This variable
 567         specifies a ":" separated list of git object directories which
 568         can be used to search for git objects. New objects will not be
 569         written to these directories.
 570
 571 'GIT_DIR'::
 572         If the 'GIT_DIR' environment variable is set then it
 573         specifies a path to use instead of the default `.git`
 574         for the base of the repository.
 575
 576 git Commits
 577 ~~~~~~~~~~~
 578 'GIT_AUTHOR_NAME'::
 579 'GIT_AUTHOR_EMAIL'::
 580 'GIT_AUTHOR_DATE'::
 581 'GIT_COMMITTER_NAME'::
 582 'GIT_COMMITTER_EMAIL'::
 583         see gitlink:git-commit-tree[1]
 584
 585 git Diffs
 586 ~~~~~~~~~
 587 'GIT_DIFF_OPTS'::
 588 'GIT_EXTERNAL_DIFF'::
 589         see the "generating patches" section in :
 590         gitlink:git-diff-index[1];
 591         gitlink:git-diff-files[1];
 592         gitlink:git-diff-tree[1]
 593
 594 Discussion[[Discussion]]
 595 ------------------------
 596 include::README[]
 597
 598 Authors
 599 -------
 600 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
 601 * The current git nurse is Junio C Hamano <junkio@cox.net>.
 602 * The git potty was written by Andres Ericsson <ae@op5.se>.
 603 * General upbringing is handled by the git-list <git@vger.kernel.org>.
 604
 605 Documentation
 606 --------------
 607 The documentation for git suite was started by David Greaves
 608 <david@dgreaves.com>, and later enhanced greatly by the
 609 contributors on the git-list <git@vger.kernel.org>.
 610
 611 GIT
 612 ---
 613 Part of the gitlink:git[7] suite
 614