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-branch[1]::
 333         Show branches and their commits.
 334
 335 gitlink:git-status[1]::
 336         Shows the working tree status.
 337
 338 gitlink:git-verify-tag[1]::
 339         Check the GPG signature of tag.
 340
 341 gitlink:git-whatchanged[1]::
 342         Shows commit logs and differences they introduce.
 343
 344
 345 Ancillary Commands
 346 ------------------
 347 Manipulators:
 348
 349 gitlink:git-applypatch[1]::
 350         Apply one patch extracted from an e-mail.
 351
 352 gitlink:git-archimport[1]::
 353         Import an arch repository into git.
 354
 355 gitlink:git-convert-objects[1]::
 356         Converts old-style git repository.
 357
 358 gitlink:git-cvsimport[1]::
 359         Salvage your data out of another SCM people love to hate.
 360
 361 gitlink:git-cvsexportcommit[1]::
 362         Export a single commit to a CVS checkout.
 363
 364 gitlink:git-lost-found[1]::
 365         Recover lost refs that luckily have not yet been pruned.
 366
 367 gitlink:git-merge-one-file[1]::
 368         The standard helper program to use with `git-merge-index`.
 369
 370 gitlink:git-prune[1]::
 371         Prunes all unreachable objects from the object database.
 372
 373 gitlink:git-relink[1]::
 374         Hardlink common objects in local repositories.
 375
 376 gitlink:git-svnimport[1]::
 377         Import a SVN repository into git.
 378
 379 gitlink:git-sh-setup[1]::
 380         Common git shell script setup code.
 381
 382 gitlink:git-symbolic-ref[1]::
 383         Read and modify symbolic refs.
 384
 385 gitlink:git-tag[1]::
 386         An example script to create a tag object signed with GPG.
 387
 388 gitlink:git-update-ref[1]::
 389         Update the object name stored in a ref safely.
 390
 391
 392 Interrogators:
 393
 394 gitlink:git-check-ref-format[1]::
 395         Make sure ref name is well formed.
 396
 397 gitlink:git-cherry[1]::
 398         Find commits not merged upstream.
 399
 400 gitlink:git-count-objects[1]::
 401         Count unpacked number of objects and their disk consumption.
 402
 403 gitlink:git-daemon[1]::
 404         A really simple server for git repositories.
 405
 406 gitlink:git-get-tar-commit-id[1]::
 407         Extract commit ID from an archive created using git-tar-tree.
 408
 409 gitlink:git-mailinfo[1]::
 410         Extracts patch and authorship information from a single
 411         e-mail message, optionally transliterating the commit
 412         message into utf-8.
 413
 414 gitlink:git-mailsplit[1]::
 415         A stupid program to split UNIX mbox format mailbox into
 416         individual pieces of e-mail.
 417
 418 gitlink:git-patch-id[1]::
 419         Compute unique ID for a patch.
 420
 421 gitlink:git-parse-remote[1]::
 422         Routines to help parsing `$GIT_DIR/remotes/` files.
 423
 424 gitlink:git-request-pull[1]::
 425         git-request-pull.
 426
 427 gitlink:git-rev-parse[1]::
 428         Pick out and massage parameters.
 429
 430 gitlink:git-send-email[1]::
 431         Send patch e-mails out of "format-patch --mbox" output.
 432
 433 gitlink:git-symbolic-ref[1]::
 434         Read and modify symbolic refs.
 435
 436 gitlink:git-stripspace[1]::
 437         Filter out empty lines.
 438
 439
 440 Commands not yet documented
 441 ---------------------------
 442
 443 gitlink:gitk[1]::
 444         The gitk repository browser.
 445
 446
 447 Configuration Mechanism
 448 -----------------------
 449
 450 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
 451 is used to hold per-repository configuration options.  It is a
 452 simple text file modelled after `.ini` format familiar to some
 453 people.  Here is an example:
 454
 455 ------------
 456 #
 457 # A '#' or ';' character indicates a comment.
 458 #
 459
 460 ; core variables
 461 [core]
 462         ; Don't trust file modes
 463         filemode = false
 464
 465 ; user identity
 466 [user]
 467         name = "Junio C Hamano"
 468         email = "junkio@twinsun.com"
 469
 470 ------------
 471
 472 Various commands read from the configuration file and adjust
 473 their operation accordingly.
 474
 475
 476 Identifier Terminology
 477 ----------------------
 478 <object>::
 479         Indicates the object name for any type of object.
 480
 481 <blob>::
 482         Indicates a blob object name.
 483
 484 <tree>::
 485         Indicates a tree object name.
 486
 487 <commit>::
 488         Indicates a commit object name.
 489
 490 <tree-ish>::
 491         Indicates a tree, commit or tag object name.  A
 492         command that takes a <tree-ish> argument ultimately wants to
 493         operate on a <tree> object but automatically dereferences
 494         <commit> and <tag> objects that point at a <tree>.
 495
 496 <type>::
 497         Indicates that an object type is required.
 498         Currently one of: `blob`, `tree`, `commit`, or `tag`.
 499
 500 <file>::
 501         Indicates a filename - almost always relative to the
 502         root of the tree structure `GIT_INDEX_FILE` describes.
 503
 504 Symbolic Identifiers
 505 --------------------
 506 Any git command accepting any <object> can also use the following
 507 symbolic notation:
 508
 509 HEAD::
 510         indicates the head of the current branch (i.e. the
 511         contents of `$GIT_DIR/HEAD`).
 512
 513 <tag>::
 514         a valid tag 'name'
 515         (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
 516
 517 <head>::
 518         a valid head 'name'
 519         (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
 520
 521 <snap>::
 522         a valid snapshot 'name'
 523         (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
 524
 525
 526 File/Directory Structure
 527 ------------------------
 528
 529 Please see link:repository-layout.html[repository layout] document.
 530
 531 Higher level SCMs may provide and manage additional information in the
 532 `$GIT_DIR`.
 533
 534
 535 Terminology
 536 -----------
 537 Please see link:glossary.html[glossary] document.
 538
 539
 540 Environment Variables
 541 ---------------------
 542 Various git commands use the following environment variables:
 543
 544 The git Repository
 545 ~~~~~~~~~~~~~~~~~~
 546 These environment variables apply to 'all' core git commands. Nb: it
 547 is worth noting that they may be used/overridden by SCMS sitting above
 548 git so take care if using Cogito etc.
 549
 550 'GIT_INDEX_FILE'::
 551         This environment allows the specification of an alternate
 552         index file. If not specified, the default of `$GIT_DIR/index`
 553         is used.
 554
 555 'GIT_OBJECT_DIRECTORY'::
 556         If the object storage directory is specified via this
 557         environment variable then the sha1 directories are created
 558         underneath - otherwise the default `$GIT_DIR/objects`
 559         directory is used.
 560
 561 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
 562         Due to the immutable nature of git objects, old objects can be
 563         archived into shared, read-only directories. This variable
 564         specifies a ":" separated list of git object directories which
 565         can be used to search for git objects. New objects will not be
 566         written to these directories.
 567
 568 'GIT_DIR'::
 569         If the 'GIT_DIR' environment variable is set then it
 570         specifies a path to use instead of the default `.git`
 571         for the base of the repository.
 572
 573 git Commits
 574 ~~~~~~~~~~~
 575 'GIT_AUTHOR_NAME'::
 576 'GIT_AUTHOR_EMAIL'::
 577 'GIT_AUTHOR_DATE'::
 578 'GIT_COMMITTER_NAME'::
 579 'GIT_COMMITTER_EMAIL'::
 580         see gitlink:git-commit-tree[1]
 581
 582 git Diffs
 583 ~~~~~~~~~
 584 'GIT_DIFF_OPTS'::
 585 'GIT_EXTERNAL_DIFF'::
 586         see the "generating patches" section in :
 587         gitlink:git-diff-index[1];
 588         gitlink:git-diff-files[1];
 589         gitlink:git-diff-tree[1]
 590
 591 Discussion[[Discussion]]
 592 ------------------------
 593 include::README[]
 594
 595 Authors
 596 -------
 597 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
 598 * The current git nurse is Junio C Hamano <junkio@cox.net>.
 599 * The git potty was written by Andres Ericsson <ae@op5.se>.
 600 * General upbringing is handled by the git-list <git@vger.kernel.org>.
 601
 602 Documentation
 603 --------------
 604 The documentation for git suite was started by David Greaves
 605 <david@dgreaves.com>, and later enhanced greatly by the
 606 contributors on the git-list <git@vger.kernel.org>.
 607
 608 GIT
 609 ---
 610 Part of the gitlink:git[7] suite
 611