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-diff-index[1]::
 143         Compares content and mode of blobs between the index and repository.
 144
 145 gitlink:git-diff-files[1]::
 146         Compares files in the working tree and the index.
 147
 148 gitlink:git-diff-stages[1]::
 149         Compares two "merge stages" in the index.
 150
 151 gitlink:git-diff-tree[1]::
 152         Compares the content and mode of blobs found via two tree objects.
 153
 154 gitlink:git-fsck-objects[1]::
 155         Verifies the connectivity and validity of the objects in the database.
 156
 157 gitlink:git-ls-files[1]::
 158         Information about files in the index and the working tree.
 159
 160 gitlink:git-ls-tree[1]::
 161         Displays a tree object in human readable form.
 162
 163 gitlink:git-merge-base[1]::
 164         Finds as good common ancestors as possible for a merge.
 165
 166 gitlink:git-name-rev[1]::
 167         Find symbolic names for given revs.
 168
 169 gitlink:git-pack-redundant[1]::
 170         Find redundant pack files.
 171
 172 gitlink:git-rev-list[1]::
 173         Lists commit objects in reverse chronological order.
 174
 175 gitlink:git-show-index[1]::
 176         Displays contents of a pack idx file.
 177
 178 gitlink:git-tar-tree[1]::
 179         Creates a tar archive of the files in the named tree object.
 180
 181 gitlink:git-unpack-file[1]::
 182         Creates a temporary file with a blob's contents.
 183
 184 gitlink:git-var[1]::
 185         Displays a git logical variable.
 186
 187 gitlink:git-verify-pack[1]::
 188         Validates packed git archive files.
 189
 190 In general, the interrogate commands do not touch the files in
 191 the working tree.
 192
 193
 194 Synching repositories
 195 ~~~~~~~~~~~~~~~~~~~~~
 196
 197 gitlink:git-clone-pack[1]::
 198         Clones a repository into the current repository (engine
 199         for ssh and local transport).
 200
 201 gitlink:git-fetch-pack[1]::
 202         Updates from a remote repository (engine for ssh and
 203         local transport).
 204
 205 gitlink:git-http-fetch[1]::
 206         Downloads a remote git repository via HTTP by walking
 207         commit chain.
 208
 209 gitlink:git-local-fetch[1]::
 210         Duplicates another git repository on a local system by
 211         walking commit chain.
 212
 213 gitlink:git-peek-remote[1]::
 214         Lists references on a remote repository using
 215         upload-pack protocol (engine for ssh and local
 216         transport).
 217
 218 gitlink:git-receive-pack[1]::
 219         Invoked by 'git-send-pack' to receive what is pushed to it.
 220
 221 gitlink:git-send-pack[1]::
 222         Pushes to a remote repository, intelligently.
 223
 224 gitlink:git-http-push[1]::
 225         Push missing objects using HTTP/DAV.
 226
 227 gitlink:git-shell[1]::
 228         Restricted shell for GIT-only SSH access.
 229
 230 gitlink:git-ssh-fetch[1]::
 231         Pulls from a remote repository over ssh connection by
 232         walking commit chain.
 233
 234 gitlink:git-ssh-upload[1]::
 235         Helper "server-side" program used by git-ssh-fetch.
 236
 237 gitlink:git-update-server-info[1]::
 238         Updates auxiliary information on a dumb server to help
 239         clients discover references and packs on it.
 240
 241 gitlink:git-upload-pack[1]::
 242         Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
 243         what are asked for.
 244
 245
 246 Porcelain-ish Commands
 247 ----------------------
 248
 249 gitlink:git-add[1]::
 250         Add paths to the index.
 251
 252 gitlink:git-am[1]::
 253         Apply patches from a mailbox, but cooler.
 254
 255 gitlink:git-applymbox[1]::
 256         Apply patches from a mailbox, original version by Linus.
 257
 258 gitlink:git-bisect[1]::
 259         Find the change that introduced a bug by binary search.
 260
 261 gitlink:git-branch[1]::
 262         Create and Show branches.
 263
 264 gitlink:git-checkout[1]::
 265         Checkout and switch to a branch.
 266
 267 gitlink:git-cherry-pick[1]::
 268         Cherry-pick the effect of an existing commit.
 269
 270 gitlink:git-clone[1]::
 271         Clones a repository into a new directory.
 272
 273 gitlink:git-commit[1]::
 274         Record changes to the repository.
 275
 276 gitlink:git-diff[1]::
 277         Show changes between commits, commit and working tree, etc.
 278
 279 gitlink:git-fetch[1]::
 280         Download from a remote repository via various protocols.
 281
 282 gitlink:git-format-patch[1]::
 283         Prepare patches for e-mail submission.
 284
 285 gitlink:git-grep[1]::
 286         Print lines matching a pattern.
 287
 288 gitlink:git-log[1]::
 289         Shows commit logs.
 290
 291 gitlink:git-ls-remote[1]::
 292         Shows references in a remote or local repository.
 293
 294 gitlink:git-merge[1]::
 295         Grand unified merge driver.
 296
 297 gitlink:git-mv[1]::
 298         Move or rename a file, a directory, or a symlink.
 299
 300 gitlink:git-octopus[1]::
 301         Merge more than two commits.
 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-refs[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