Documentation/git.txt

   1 git(7)
   2 ======
   3 v0.99.4, 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-whatchanged.html[git-whatchanged]::
 199         Shows commit logs and differences they introduce.
 200
 201 link:git-log-script.html[git-log-script]::
 202         Shows commit logs.
 203
 204 link:git-shortlog.html[git-shortlog]::
 205         Summarizes 'git log' output.
 206
 207 link:git-status-script.html[git-status-script]::
 208         Shows the working tree status.
 209
 210 link:git-fetch-script.html[git-fetch-script]::
 211         Download from a remote repository via various protocols.
 212
 213 link:git-pull-script.html[git-pull-script]::
 214         Fetch from and merge with a remote repository.
 215
 216 link:git-resolve-script.html[git-resolve-script]::
 217         Merge two commits.
 218
 219 link:git-octopus-script.html[git-octopus-script]::
 220         Merge more than two commits.
 221
 222 link:git-push-script.html[git-push-script]::
 223         Update remote refs along with associated objects.
 224
 225 link:git-commit-script.html[git-commit-script]::
 226         Record changes to the repository.
 227
 228 link:git-show-branch.html[git-show-branch]::
 229         Show branches and their commits.
 230
 231 link:git-repack-script.html[git-repack-script]::
 232         Pack unpacked objects in a repository.
 233
 234 link:git-rename-script.html[git-rename]::
 235         Rename files and directories.
 236
 237 link:git-ls-remote-script.html[git-ls-remote-script]::
 238         Shows references in a remote or local repository.
 239
 240
 241 Ancillary Commands
 242 ------------------
 243 Manipulators:
 244
 245 link:git-apply-patch-script.html[git-apply-patch-script]::
 246         Sample script to apply the diffs from git-diff-*
 247
 248 link:git-convert-cache.html[git-convert-cache]::
 249         Converts old-style GIT repository
 250
 251 link:git-merge-one-file-script.html[git-merge-one-file-script]::
 252         The standard helper program to use with "git-merge-cache"
 253
 254 link:git-prune-script.html[git-prune-script]::
 255         Prunes all unreachable objects from the object database
 256
 257 link:git-tag-script.html[git-tag-script]::
 258         An example script to create a tag object signed with GPG
 259
 260 link:git-cvsimport-script.html[git-cvsimport-script]::
 261         Salvage your data out of another SCM people love to hate.
 262
 263
 264 Interrogators:
 265
 266 link:git-diff-helper.html[git-diff-helper]::
 267         Generates patch format output for git-diff-*
 268
 269 link:git-ssh-push.html[git-ssh-push]::
 270         Helper "server-side" program used by git-ssh-pull
 271
 272 link:git-send-email-script.html[git-send-email]::
 273         Send patch e-mails out of "format-patch --mbox" output.
 274
 275
 276 Commands not yet documented
 277 ---------------------------
 278
 279 link:git-applymbox.html[git-applymbox]::
 280         git-applymbox.
 281
 282 link:git-applypatch.html[git-applypatch]::
 283         git-applypatch.
 284
 285 link:git-mailinfo.html[git-mailinfo]::
 286         git-mailinfo.
 287
 288 link:git-mailsplit.html[git-mailsplit]::
 289         git-mailsplit.
 290
 291 link:git-add-script.html[git-add-script]::
 292         git-add-script.
 293
 294 link:git-bisect-script.html[git-bisect-script]::
 295         git-bisect-script.
 296
 297 link:git-branch-script.html[git-branch-script]::
 298         git-branch-script.
 299
 300 link:git-build-rev-cache.html[git-build-rev-cache]::
 301         git-build-rev-cache.
 302
 303 link:git-checkout-script.html[git-checkout-script]::
 304         git-checkout-script.
 305
 306 link:git-cherry.html[git-cherry]::
 307         git-cherry.
 308
 309 link:git-clone-dumb-http.html[git-clone-dumb-http]::
 310         git-clone-dumb-http.
 311
 312 link:git-count-objects-script.html[git-count-objects-script]::
 313         git-count-objects-script.
 314
 315 link:git-daemon.html[git-daemon]::
 316         git-daemon.
 317
 318 link:git-diff-script.html[git-diff-script]::
 319         git-diff-script.
 320
 321 link:git-format-patch-script.html[git-format-patch-script]::
 322         git-format-patch-script.
 323
 324 link:git-get-tar-commit-id.html[git-get-tar-commit-id]::
 325         git-get-tar-commit-id.
 326
 327 link:git-patch-id.html[git-patch-id]::
 328         git-patch-id.
 329
 330 link:git-rebase-script.html[git-rebase-script]::
 331         git-rebase-script.
 332
 333 link:git-relink-script.html[git-relink-script]::
 334         git-relink-script.
 335
 336 link:git-request-pull-script.html[git-request-pull-script]::
 337         git-request-pull-script.
 338
 339 link:git-reset-script.html[git-reset-script]::
 340         git-reset-script.
 341
 342 link:git-rev-parse.html[git-rev-parse]::
 343         git-rev-parse.
 344
 345 link:git-revert-script.html[git-revert-script]::
 346         git-revert-script.
 347
 348 link:git-sh-setup-script.html[git-sh-setup-script]::
 349         git-sh-setup-script.
 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:git-verify-tag-script.html[git-verify-tag-script]::
 358         git-verify-tag-script.
 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