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 index 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 index 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 index
  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 index
  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 index and repository
 109
 110 gitlink:git-diff-files[1]::
 111         Compares files in the working tree and the index
 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 index/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-lost+found[1]::
 313         Recover lost refs that luckily have not yet been pruned.
 314
 315 gitlink:git-merge-one-file[1]::
 316         The standard helper program to use with "git-merge-index"
 317
 318 gitlink:git-prune[1]::
 319         Prunes all unreachable objects from the object database
 320
 321 gitlink:git-relink[1]::
 322         Hardlink common objects in local repositories.
 323
 324 gitlink:git-svnimport[1]::
 325         Import a SVN repository into git.
 326
 327 gitlink:git-sh-setup[1]::
 328         Common git shell script setup code.
 329
 330 gitlink:git-symbolic-ref[1]::
 331         Read and modify symbolic refs
 332
 333 gitlink:git-tag[1]::
 334         An example script to create a tag object signed with GPG
 335
 336 gitlink:git-update-ref[1]::
 337         Update the object name stored in a ref safely.
 338
 339
 340 Interrogators:
 341
 342 gitlink:git-check-ref-format[1]::
 343         Make sure ref name is well formed.
 344
 345 gitlink:git-cherry[1]::
 346         Find commits not merged upstream.
 347
 348 gitlink:git-count-objects[1]::
 349         Count unpacked number of objects and their disk consumption.
 350
 351 gitlink:git-daemon[1]::
 352         A really simple server for git repositories.
 353
 354 gitlink:git-get-tar-commit-id[1]::
 355         Extract commit ID from an archive created using git-tar-tree.
 356
 357 gitlink:git-mailinfo[1]::
 358         Extracts patch from a single e-mail message.
 359
 360 gitlink:git-mailsplit[1]::
 361         git-mailsplit.
 362
 363 gitlink:git-patch-id[1]::
 364         Compute unique ID for a patch.
 365
 366 gitlink:git-parse-remote[1]::
 367         Routines to help parsing $GIT_DIR/remotes/
 368
 369 gitlink:git-request-pull[1]::
 370         git-request-pull.
 371
 372 gitlink:git-rev-parse[1]::
 373         Pick out and massage parameters.
 374
 375 gitlink:git-send-email[1]::
 376         Send patch e-mails out of "format-patch --mbox" output.
 377
 378 gitlink:git-symbolic-refs[1]::
 379         Read and modify symbolic refs.
 380
 381 gitlink:git-stripspace[1]::
 382         Filter out empty lines.
 383
 384
 385 Commands not yet documented
 386 ---------------------------
 387
 388 gitlink:gitk[1]::
 389         gitk.
 390
 391
 392 Configuration Mechanism
 393 -----------------------
 394
 395 Starting from 0.99.9 (actually mid 0.99.8.GIT), .git/config file
 396 is used to hold per-repository configuration options.  It is a
 397 simple text file modelled after `.ini` format familiar to some
 398 people.  Here is an example:
 399
 400 ------------
 401 #
 402 # This is the config file, and
 403 # a '#' or ';' character indicates
 404 # a comment
 405 #
 406
 407 ; core variables
 408 [core]
 409         ; Don't trust file modes
 410         filemode = false
 411
 412 ; user identity
 413 [user]
 414         name = "Junio C Hamano"
 415         email = "junkio@twinsun.com"
 416
 417 ------------
 418
 419 Various commands read from the configuration file and adjust
 420 their operation accordingly.
 421
 422
 423 Identifier Terminology
 424 ----------------------
 425 <object>::
 426         Indicates the sha1 identifier for any type of object
 427
 428 <blob>::
 429         Indicates a blob object sha1 identifier
 430
 431 <tree>::
 432         Indicates a tree object sha1 identifier
 433
 434 <commit>::
 435         Indicates a commit object sha1 identifier
 436
 437 <tree-ish>::
 438         Indicates a tree, commit or tag object sha1 identifier.  A
 439         command that takes a <tree-ish> argument ultimately wants to
 440         operate on a <tree> object but automatically dereferences
 441         <commit> and <tag> objects that point at a <tree>.
 442
 443 <type>::
 444         Indicates that an object type is required.
 445         Currently one of: blob/tree/commit/tag
 446
 447 <file>::
 448         Indicates a filename - always relative to the root of
 449         the tree structure GIT_INDEX_FILE describes.
 450
 451 Symbolic Identifiers
 452 --------------------
 453 Any git command accepting any <object> can also use the following
 454 symbolic notation:
 455
 456 HEAD::
 457         indicates the head of the repository (ie the contents of
 458         `$GIT_DIR/HEAD`)
 459 <tag>::
 460         a valid tag 'name'+
 461         (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
 462 <head>::
 463         a valid head 'name'+
 464         (ie the contents of `$GIT_DIR/refs/heads/<head>`)
 465 <snap>::
 466         a valid snapshot 'name'+
 467         (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
 468
 469
 470 File/Directory Structure
 471 ------------------------
 472
 473 Please see link:repository-layout.html[repository layout] document.
 474
 475 Higher level SCMs may provide and manage additional information in the
 476 GIT_DIR.
 477
 478
 479 Terminology
 480 -----------
 481 Please see link:glossary.html[glossary] document.
 482
 483
 484 Environment Variables
 485 ---------------------
 486 Various git commands use the following environment variables:
 487
 488 The git Repository
 489 ~~~~~~~~~~~~~~~~~~
 490 These environment variables apply to 'all' core git commands. Nb: it
 491 is worth noting that they may be used/overridden by SCMS sitting above
 492 git so take care if using Cogito etc
 493
 494 'GIT_INDEX_FILE'::
 495         This environment allows the specification of an alternate
 496         index file. If not specified, the default of `$GIT_DIR/index`
 497         is used.
 498
 499 'GIT_OBJECT_DIRECTORY'::
 500         If the object storage directory is specified via this
 501         environment variable then the sha1 directories are created
 502         underneath - otherwise the default `$GIT_DIR/objects`
 503         directory is used.
 504
 505 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
 506         Due to the immutable nature of git objects, old objects can be
 507         archived into shared, read-only directories. This variable
 508         specifies a ":" separated list of git object directories which
 509         can be used to search for git objects. New objects will not be
 510         written to these directories.
 511
 512 'GIT_DIR'::
 513         If the 'GIT_DIR' environment variable is set then it specifies
 514         a path to use instead of `./.git` for the base of the
 515         repository.
 516
 517 git Commits
 518 ~~~~~~~~~~~
 519 'GIT_AUTHOR_NAME'::
 520 'GIT_AUTHOR_EMAIL'::
 521 'GIT_AUTHOR_DATE'::
 522 'GIT_COMMITTER_NAME'::
 523 'GIT_COMMITTER_EMAIL'::
 524         see gitlink:git-commit-tree[1]
 525
 526 git Diffs
 527 ~~~~~~~~~
 528 'GIT_DIFF_OPTS'::
 529 'GIT_EXTERNAL_DIFF'::
 530         see the "generating patches" section in :
 531         gitlink:git-diff-index[1];
 532         gitlink:git-diff-files[1];
 533         gitlink:git-diff-tree[1]
 534
 535 Discussion[[Discussion]]
 536 ------------------------
 537 include::../README[]
 538
 539 Author
 540 ------
 541 Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>.
 542
 543 Documentation
 544 --------------
 545 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
 546
 547 GIT
 548 ---
 549 Part of the gitlink:git[7] suite
 550