Documentation/git.txt

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