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-diff-helper[1]::
 367         Generates patch format output for git-diff-*
 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         Previously this command was known as git-parse-remote-script.
 384
 385 gitlink:git-request-pull[1]::
 386         git-request-pull.
 387         Previously this command was known as git-request-pull-script.
 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         Previously this command was known as git-send-email-script.
 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 Identifier Terminology
 408 ----------------------
 409 <object>::
 410         Indicates the sha1 identifier for any type of object
 411
 412 <blob>::
 413         Indicates a blob object sha1 identifier
 414
 415 <tree>::
 416         Indicates a tree object sha1 identifier
 417
 418 <commit>::
 419         Indicates a commit object sha1 identifier
 420
 421 <tree-ish>::
 422         Indicates a tree, commit or tag object sha1 identifier.  A
 423         command that takes a <tree-ish> argument ultimately wants to
 424         operate on a <tree> object but automatically dereferences
 425         <commit> and <tag> objects that point at a <tree>.
 426
 427 <type>::
 428         Indicates that an object type is required.
 429         Currently one of: blob/tree/commit/tag
 430
 431 <file>::
 432         Indicates a filename - always relative to the root of
 433         the tree structure GIT_INDEX_FILE describes.
 434
 435 Symbolic Identifiers
 436 --------------------
 437 Any git command accepting any <object> can also use the following
 438 symbolic notation:
 439
 440 HEAD::
 441         indicates the head of the repository (ie the contents of
 442         `$GIT_DIR/HEAD`)
 443 <tag>::
 444         a valid tag 'name'+
 445         (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
 446 <head>::
 447         a valid head 'name'+
 448         (ie the contents of `$GIT_DIR/refs/heads/<head>`)
 449 <snap>::
 450         a valid snapshot 'name'+
 451         (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
 452
 453
 454 File/Directory Structure
 455 ------------------------
 456
 457 Please see link:repository-layout.html[repository layout] document.
 458
 459 Higher level SCMs may provide and manage additional information in the
 460 GIT_DIR.
 461
 462
 463 Terminology
 464 -----------
 465 Please see link:glossary.html[glossary] document.
 466
 467
 468 Environment Variables
 469 ---------------------
 470 Various git commands use the following environment variables:
 471
 472 The git Repository
 473 ~~~~~~~~~~~~~~~~~~
 474 These environment variables apply to 'all' core git commands. Nb: it
 475 is worth noting that they may be used/overridden by SCMS sitting above
 476 git so take care if using Cogito etc
 477
 478 'GIT_INDEX_FILE'::
 479         This environment allows the specification of an alternate
 480         cache/index file. If not specified, the default of
 481         `$GIT_DIR/index` is used.
 482
 483 'GIT_OBJECT_DIRECTORY'::
 484         If the object storage directory is specified via this
 485         environment variable then the sha1 directories are created
 486         underneath - otherwise the default `$GIT_DIR/objects`
 487         directory is used.
 488
 489 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
 490         Due to the immutable nature of git objects, old objects can be
 491         archived into shared, read-only directories. This variable
 492         specifies a ":" separated list of git object directories which
 493         can be used to search for git objects. New objects will not be
 494         written to these directories.
 495
 496 'GIT_DIR'::
 497         If the 'GIT_DIR' environment variable is set then it specifies
 498         a path to use instead of `./.git` for the base of the
 499         repository.
 500
 501 git Commits
 502 ~~~~~~~~~~~
 503 'GIT_AUTHOR_NAME'::
 504 'GIT_AUTHOR_EMAIL'::
 505 'GIT_AUTHOR_DATE'::
 506 'GIT_COMMITTER_NAME'::
 507 'GIT_COMMITTER_EMAIL'::
 508         see gitlink:git-commit-tree[1]
 509
 510 git Diffs
 511 ~~~~~~~~~
 512 'GIT_DIFF_OPTS'::
 513 'GIT_EXTERNAL_DIFF'::
 514         see the "generating patches" section in :
 515         gitlink:git-diff-index[1];
 516         gitlink:git-diff-files[1];
 517         gitlink:git-diff-tree[1]
 518
 519 Discussion[[Discussion]]
 520 ------------------------
 521 include::../README[]
 522
 523 Author
 524 ------
 525 Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>.
 526
 527 Documentation
 528 --------------
 529 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
 530
 531 GIT
 532 ---
 533 Part of the gitlink:git[7] suite
 534