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