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