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-convert-cache.html[git-convert-cache]::
 264         Converts old-style GIT repository
 265
 266 link:git-merge-one-file-script.html[git-merge-one-file-script]::
 267         The standard helper program to use with "git-merge-cache"
 268
 269 link:git-prune-script.html[git-prune-script]::
 270         Prunes all unreachable objects from the object database
 271
 272 link:git-tag-script.html[git-tag-script]::
 273         An example script to create a tag object signed with GPG
 274
 275 link:git-cvsimport-script.html[git-cvsimport-script]::
 276         Salvage your data out of another SCM people love to hate.
 277
 278
 279 Interrogators:
 280
 281 link:git-patch-id.html[git-patch-id]::
 282         Compute unique ID for a patch.
 283
 284 link:git-count-objects-script.html[git-count-objects-script]::
 285         Count unpacked number of objects and their disk consumption.
 286
 287 link:git-cherry.html[git-cherry]::
 288         Find commits not merged upstream.
 289
 290 link:git-diff-helper.html[git-diff-helper]::
 291         Generates patch format output for git-diff-*
 292
 293 link:git-ssh-push.html[git-ssh-push]::
 294         Helper "server-side" program used by git-ssh-pull
 295
 296 link:git-send-email-script.html[git-send-email]::
 297         Send patch e-mails out of "format-patch --mbox" output.
 298
 299 link:git-sh-setup-script.html[git-sh-setup-script]::
 300         Common git shell script setup code.
 301
 302
 303 Commands not yet documented
 304 ---------------------------
 305
 306 link:git-applymbox.html[git-applymbox]::
 307         git-applymbox.
 308
 309 link:git-applypatch.html[git-applypatch]::
 310         git-applypatch.
 311
 312 link:git-mailinfo.html[git-mailinfo]::
 313         git-mailinfo.
 314
 315 link:git-mailsplit.html[git-mailsplit]::
 316         git-mailsplit.
 317
 318 link:git-bisect-script.html[git-bisect-script]::
 319         git-bisect-script.
 320
 321 link:git-build-rev-cache.html[git-build-rev-cache]::
 322         git-build-rev-cache.
 323
 324 link:git-checkout-script.html[git-checkout-script]::
 325         git-checkout-script.
 326
 327 link:git-clone-dumb-http.html[git-clone-dumb-http]::
 328         git-clone-dumb-http.
 329
 330 link:git-daemon.html[git-daemon]::
 331         git-daemon.
 332
 333 link:git-diff-script.html[git-diff-script]::
 334         git-diff-script.
 335
 336 link:git-format-patch-script.html[git-format-patch-script]::
 337         git-format-patch-script.
 338
 339 link:git-get-tar-commit-id.html[git-get-tar-commit-id]::
 340         git-get-tar-commit-id.
 341
 342 link:git-request-pull-script.html[git-request-pull-script]::
 343         git-request-pull-script.
 344
 345 link:git-reset-script.html[git-reset-script]::
 346         git-reset-script.
 347
 348 link:git-rev-parse.html[git-rev-parse]::
 349         git-rev-parse.
 350
 351 link:git-show-rev-cache.html[git-show-rev-cache]::
 352         git-show-rev-cache.
 353
 354 link:git-stripspace.html[git-stripspace]::
 355         git-stripspace.
 356
 357 link:gitk.html[gitk]::
 358         gitk.
 359
 360
 361 Identifier Terminology
 362 ----------------------
 363 <object>::
 364         Indicates the sha1 identifier for any type of object
 365
 366 <blob>::
 367         Indicates a blob object sha1 identifier
 368
 369 <tree>::
 370         Indicates a tree object sha1 identifier
 371
 372 <commit>::
 373         Indicates a commit object sha1 identifier
 374
 375 <tree-ish>::
 376         Indicates a tree, commit or tag object sha1 identifier.  A
 377         command that takes a <tree-ish> argument ultimately wants to
 378         operate on a <tree> object but automatically dereferences
 379         <commit> and <tag> objects that point at a <tree>.
 380
 381 <type>::
 382         Indicates that an object type is required.
 383         Currently one of: blob/tree/commit/tag
 384
 385 <file>::
 386         Indicates a filename - always relative to the root of
 387         the tree structure GIT_INDEX_FILE describes.
 388
 389 Symbolic Identifiers
 390 --------------------
 391 Any git command accepting any <object> can also use the following
 392 symbolic notation:
 393
 394 HEAD::
 395         indicates the head of the repository (ie the contents of
 396         `$GIT_DIR/HEAD`)
 397 <tag>::
 398         a valid tag 'name'+
 399         (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
 400 <head>::
 401         a valid head 'name'+
 402         (ie the contents of `$GIT_DIR/refs/heads/<head>`)
 403 <snap>::
 404         a valid snapshot 'name'+
 405         (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
 406
 407
 408 File/Directory Structure
 409 ------------------------
 410 The git-core manipulates the following areas in the directory:
 411
 412  .git/         The base (overridden with $GIT_DIR)
 413    objects/    The object base (overridden with $GIT_OBJECT_DIRECTORY)
 414      ??/       'First 2 chars of object' directories.
 415      pack/     Packed archives.
 416
 417    refs/       Directories containing symbolic names for objects
 418                (each file contains the hex SHA1 + newline)
 419      heads/    Commits which are heads of various sorts
 420      tags/     Tags, by the tag name (or some local renaming of it)
 421      */        Any other subdirectory of refs/ can be used to store
 422                files similar to what are under refs/heads/.
 423    HEAD        Symlink to refs/heads/<current-branch-name>
 424
 425 Higher level SCMs may provide and manage additional information in the
 426 GIT_DIR.
 427
 428 Terminology
 429 -----------
 430 Please see link:glossary.html[glossary] document.
 431
 432
 433 Environment Variables
 434 ---------------------
 435 Various git commands use the following environment variables:
 436
 437 The git Repository
 438 ~~~~~~~~~~~~~~~~~~
 439 These environment variables apply to 'all' core git commands. Nb: it
 440 is worth noting that they may be used/overridden by SCMS sitting above
 441 git so take care if using Cogito etc
 442
 443 'GIT_INDEX_FILE'::
 444         This environment allows the specification of an alternate
 445         cache/index file. If not specified, the default of
 446         `$GIT_DIR/index` is used.
 447
 448 'GIT_OBJECT_DIRECTORY'::
 449         If the object storage directory is specified via this
 450         environment variable then the sha1 directories are created
 451         underneath - otherwise the default `$GIT_DIR/objects`
 452         directory is used.
 453
 454 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
 455         Due to the immutable nature of git objects, old objects can be
 456         archived into shared, read-only directories. This variable
 457         specifies a ":" separated list of git object directories which
 458         can be used to search for git objects. New objects will not be
 459         written to these directories.
 460
 461 'GIT_DIR'::
 462         If the 'GIT_DIR' environment variable is set then it specifies
 463         a path to use instead of `./.git` for the base of the
 464         repository.
 465
 466 git Commits
 467 ~~~~~~~~~~~
 468 'GIT_AUTHOR_NAME'::
 469 'GIT_AUTHOR_EMAIL'::
 470 'GIT_AUTHOR_DATE'::
 471 'GIT_COMMITTER_NAME'::
 472 'GIT_COMMITTER_EMAIL'::
 473         see link:git-commit-tree.html[git-commit-tree]
 474
 475 git Diffs
 476 ~~~~~~~~~
 477 'GIT_DIFF_OPTS'::
 478 'GIT_EXTERNAL_DIFF'::
 479         see the "generating patches" section in :
 480         link:git-diff-cache.html[git-diff-cache];
 481         link:git-diff-files.html[git-diff-files];
 482         link:git-diff-tree.html[git-diff-tree]
 483
 484 Discussion
 485 ----------
 486 include::../README[]
 487
 488 Author
 489 ------
 490 Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>.
 491
 492 Documentation
 493 --------------
 494 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
 495
 496 GIT
 497 ---
 498 Part of the link:git.html[git] suite
 499