Documentation/git.txt

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