Documentation/git.txt

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