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