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
  64 gitlink:git-commit-tree[1]::
  65         Creates a new commit object
  66
  67 gitlink:git-hash-object[1]::
  68         Computes the object ID from a file.
  69
  70 gitlink:git-index-pack.html[1]::
  71         Build pack index file for an existing packed archive.
  72
  73 gitlink:git-init-db[1]::
  74         Creates an empty git object database
  75
  76 gitlink:git-merge-index[1]::
  77         Runs a merge for files needing merging
  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
  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
 110 gitlink:git-diff-files[1]::
 111         Compares files in the working tree and the cache
 112
 113 gitlink:git-diff-stages[1]::
 114         Compares two "merge stages" in the index file.
 115
 116 gitlink:git-diff-tree[1]::
 117         Compares the content and mode of blobs found via two tree objects
 118
 119 gitlink:git-fsck-objects[1]::
 120         Verifies the connectivity and validity of the objects in the database
 121
 122 gitlink:git-ls-files[1]::
 123         Information about files in the cache/working directory
 124
 125 gitlink:git-ls-tree[1]::
 126         Displays a tree object in human readable form
 127
 128 gitlink:git-merge-base[1]::
 129         Finds as good a common ancestor as possible for a merge
 130
 131 gitlink:git-name-rev[1]::
 132         Find symbolic names for given revs
 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
 169 gitlink:git-local-fetch[1]::
 170         Duplicates another git repository on a local system
 171
 172 gitlink:git-peek-remote[1]::
 173         Lists references on a remote repository using upload-pack protocol.
 174
 175 gitlink:git-receive-pack[1]::
 176         Invoked by 'git-send-pack' to receive what is pushed to it.
 177
 178 gitlink:git-send-pack[1]::
 179         Pushes to a remote repository, intelligently.
 180
 181 gitlink:git-shell[1]::
 182         Restricted shell for GIT-only SSH access.
 183
 184 gitlink:git-ssh-fetch[1]::
 185         Pulls from a remote repository over ssh connection
 186
 187 gitlink:git-ssh-upload[1]::
 188         Helper "server-side" program used by git-ssh-fetch
 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
 205 gitlink:git-am[1]::
 206         Apply patches from a mailbox, but cooler.
 207
 208 gitlink:git-applymbox[1]::
 209         Apply patches from a mailbox.
 210
 211 gitlink:git-bisect[1]::
 212         Find the change that introduced a bug.
 213
 214 gitlink:git-branch[1]::
 215         Create and Show branches.
 216
 217 gitlink:git-checkout[1]::
 218         Checkout and switch to a branch.
 219
 220 gitlink:git-cherry-pick[1]::
 221         Cherry-pick the effect of an existing commit.
 222
 223 gitlink:git-clone[1]::
 224         Clones a repository into a new directory.
 225
 226 gitlink:git-commit[1]::
 227         Record changes to the repository.
 228
 229 gitlink:git-diff[1]::
 230         Show changes between commits, commit and working tree, etc.
 231
 232 gitlink:git-fetch[1]::
 233         Download from a remote repository via various protocols.
 234
 235 gitlink:git-format-patch[1]::
 236         Prepare patches for e-mail submission.
 237
 238 gitlink:git-grep[1]::
 239         Print lines matching a pattern
 240
 241 gitlink:git-log[1]::
 242         Shows commit logs.
 243
 244 gitlink:git-ls-remote[1]::
 245         Shows references in a remote or local repository.
 246
 247 gitlink:git-merge[1]::
 248         Grand unified merge driver.
 249
 250 gitlink:git-mv[1]::
 251         Move or rename a file, a directory, or a symlink.
 252
 253 gitlink:git-octopus[1]::
 254         Merge more than two commits.
 255
 256 gitlink:git-pull[1]::
 257         Fetch from and merge with a remote repository.
 258
 259 gitlink:git-push[1]::
 260         Update remote refs along with associated objects.
 261
 262 gitlink:git-rebase[1]::
 263         Rebase local commits to new upstream head.
 264
 265 gitlink:git-rename[1]::
 266         Rename files and directories.
 267
 268 gitlink:git-repack[1]::
 269         Pack unpacked objects in a repository.
 270
 271 gitlink:git-reset[1]::
 272         Reset current HEAD to the specified state.
 273
 274 gitlink:git-resolve[1]::
 275         Merge two commits.
 276
 277 gitlink:git-revert[1]::
 278         Revert an existing commit.
 279
 280 gitlink:git-shortlog[1]::
 281         Summarizes 'git log' output.
 282
 283 gitlink:git-show-branch[1]::
 284         Show branches and their commits.
 285
 286 gitlink:git-status[1]::
 287         Shows the working tree status.
 288
 289 gitlink:git-verify-tag[1]::
 290         Check the GPG signature of tag.
 291
 292 gitlink:git-whatchanged[1]::
 293         Shows commit logs and differences they introduce.
 294
 295
 296 Ancillary Commands
 297 ------------------
 298 Manipulators:
 299
 300 gitlink:git-applypatch[1]::
 301         Apply one patch extracted from an e-mail.
 302
 303 gitlink:git-archimport[1]::
 304         Import an arch repository into git.
 305
 306 gitlink:git-convert-objects[1]::
 307         Converts old-style git repository
 308
 309 gitlink:git-cvsimport[1]::
 310         Salvage your data out of another SCM people love to hate.
 311
 312 gitlink:git-merge-one-file[1]::
 313         The standard helper program to use with "git-merge-index"
 314
 315 gitlink:git-prune[1]::
 316         Prunes all unreachable objects from the object database
 317
 318 gitlink:git-relink[1]::
 319         Hardlink common objects in local repositories.
 320
 321 gitlink:git-svnimport[1]::
 322         Import a SVN repository into git.
 323
 324 gitlink:git-sh-setup[1]::
 325         Common git shell script setup code.
 326
 327 gitlink:git-symbolic-ref[1]::
 328         Read and modify symbolic refs
 329
 330 gitlink:git-tag[1]::
 331         An example script to create a tag object signed with GPG
 332
 333 gitlink:git-update-ref[1]::
 334         Update the object name stored in a ref safely.
 335
 336
 337 Interrogators:
 338
 339 gitlink:git-check-ref-format[1]::
 340         Make sure ref name is well formed.
 341
 342 gitlink:git-cherry[1]::
 343         Find commits not merged upstream.
 344
 345 gitlink:git-count-objects[1]::
 346         Count unpacked number of objects and their disk consumption.
 347
 348 gitlink:git-daemon[1]::
 349         A really simple server for git repositories.
 350
 351 gitlink:git-get-tar-commit-id[1]::
 352         Extract commit ID from an archive created using git-tar-tree.
 353
 354 gitlink:git-mailinfo[1]::
 355         Extracts patch from a single e-mail message.
 356
 357 gitlink:git-mailsplit[1]::
 358         git-mailsplit.
 359
 360 gitlink:git-patch-id[1]::
 361         Compute unique ID for a patch.
 362
 363 gitlink:git-parse-remote[1]::
 364         Routines to help parsing $GIT_DIR/remotes/
 365
 366 gitlink:git-request-pull[1]::
 367         git-request-pull.
 368
 369 gitlink:git-rev-parse[1]::
 370         Pick out and massage parameters.
 371
 372 gitlink:git-send-email[1]::
 373         Send patch e-mails out of "format-patch --mbox" output.
 374
 375 gitlink:git-symbolic-refs[1]::
 376         Read and modify symbolic refs.
 377
 378 gitlink:git-stripspace[1]::
 379         Filter out empty lines.
 380
 381
 382 Commands not yet documented
 383 ---------------------------
 384
 385 gitlink:gitk[1]::
 386         gitk.
 387
 388
 389 Configuration Mechanism
 390 -----------------------
 391
 392 Starting from 0.99.9 (actually mid 0.99.8.GIT), .git/config file
 393 is used to hold per-repository configuration options.  It is a
 394 simple text file modelled after `.ini` format familiar to some
 395 people.  Here is an example:
 396
 397 ------------
 398 #
 399 # This is the config file, and
 400 # a '#' or ';' character indicates
 401 # a comment
 402 #
 403
 404 ; core variables
 405 [core]
 406         ; Don't trust file modes
 407         filemode = false
 408
 409 ; user identity
 410 [user]
 411         name = "Junio C Hamano"
 412         email = "junkio@twinsun.com"
 413
 414 ------------
 415
 416 Various commands read from the configuration file and adjust
 417 their operation accordingly.
 418
 419
 420 Identifier Terminology
 421 ----------------------
 422 <object>::
 423         Indicates the sha1 identifier for any type of object
 424
 425 <blob>::
 426         Indicates a blob object sha1 identifier
 427
 428 <tree>::
 429         Indicates a tree object sha1 identifier
 430
 431 <commit>::
 432         Indicates a commit object sha1 identifier
 433
 434 <tree-ish>::
 435         Indicates a tree, commit or tag object sha1 identifier.  A
 436         command that takes a <tree-ish> argument ultimately wants to
 437         operate on a <tree> object but automatically dereferences
 438         <commit> and <tag> objects that point at a <tree>.
 439
 440 <type>::
 441         Indicates that an object type is required.
 442         Currently one of: blob/tree/commit/tag
 443
 444 <file>::
 445         Indicates a filename - always relative to the root of
 446         the tree structure GIT_INDEX_FILE describes.
 447
 448 Symbolic Identifiers
 449 --------------------
 450 Any git command accepting any <object> can also use the following
 451 symbolic notation:
 452
 453 HEAD::
 454         indicates the head of the repository (ie the contents of
 455         `$GIT_DIR/HEAD`)
 456 <tag>::
 457         a valid tag 'name'+
 458         (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
 459 <head>::
 460         a valid head 'name'+
 461         (ie the contents of `$GIT_DIR/refs/heads/<head>`)
 462 <snap>::
 463         a valid snapshot 'name'+
 464         (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
 465
 466
 467 File/Directory Structure
 468 ------------------------
 469
 470 Please see link:repository-layout.html[repository layout] document.
 471
 472 Higher level SCMs may provide and manage additional information in the
 473 GIT_DIR.
 474
 475
 476 Terminology
 477 -----------
 478 Please see link:glossary.html[glossary] document.
 479
 480
 481 Environment Variables
 482 ---------------------
 483 Various git commands use the following environment variables:
 484
 485 The git Repository
 486 ~~~~~~~~~~~~~~~~~~
 487 These environment variables apply to 'all' core git commands. Nb: it
 488 is worth noting that they may be used/overridden by SCMS sitting above
 489 git so take care if using Cogito etc
 490
 491 'GIT_INDEX_FILE'::
 492         This environment allows the specification of an alternate
 493         cache/index file. If not specified, the default of
 494         `$GIT_DIR/index` is used.
 495
 496 'GIT_OBJECT_DIRECTORY'::
 497         If the object storage directory is specified via this
 498         environment variable then the sha1 directories are created
 499         underneath - otherwise the default `$GIT_DIR/objects`
 500         directory is used.
 501
 502 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
 503         Due to the immutable nature of git objects, old objects can be
 504         archived into shared, read-only directories. This variable
 505         specifies a ":" separated list of git object directories which
 506         can be used to search for git objects. New objects will not be
 507         written to these directories.
 508
 509 'GIT_DIR'::
 510         If the 'GIT_DIR' environment variable is set then it specifies
 511         a path to use instead of `./.git` for the base of the
 512         repository.
 513
 514 git Commits
 515 ~~~~~~~~~~~
 516 'GIT_AUTHOR_NAME'::
 517 'GIT_AUTHOR_EMAIL'::
 518 'GIT_AUTHOR_DATE'::
 519 'GIT_COMMITTER_NAME'::
 520 'GIT_COMMITTER_EMAIL'::
 521         see gitlink:git-commit-tree[1]
 522
 523 git Diffs
 524 ~~~~~~~~~
 525 'GIT_DIFF_OPTS'::
 526 'GIT_EXTERNAL_DIFF'::
 527         see the "generating patches" section in :
 528         gitlink:git-diff-index[1];
 529         gitlink:git-diff-files[1];
 530         gitlink:git-diff-tree[1]
 531
 532 Discussion[[Discussion]]
 533 ------------------------
 534 include::../README[]
 535
 536 Author
 537 ------
 538 Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>.
 539
 540 Documentation
 541 --------------
 542 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
 543
 544 GIT
 545 ---
 546 Part of the gitlink:git[7] suite
 547