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