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