Documentation/git.txt

   1 git(7)
   2 ======
   3
   4 NAME
   5 ----
   6 git - the stupid content tracker
   7
   8
   9 SYNOPSIS
  10 --------
  11 'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--help] COMMAND [ARGS]
  12
  13 DESCRIPTION
  14 -----------
  15 'git' is both a program and a directory content tracker system.
  16 The program 'git' is just a wrapper to reach the core git programs
  17 (or a potty if you like, as it's not exactly porcelain but still
  18 brings your stuff to the plumbing).
  19
  20 OPTIONS
  21 -------
  22 --version::
  23         prints the git suite version that the 'git' program came from.
  24
  25 --help::
  26         prints the synopsis and a list of available commands.
  27         If a git command is named this option will bring up the
  28         man-page for that command.
  29
  30 --exec-path::
  31         path to wherever your core git programs are installed.
  32         This can also be controlled by setting the GIT_EXEC_PATH
  33         environment variable. If no path is given 'git' will print
  34         the current setting and then exit.
  35
  36 CORE GIT COMMANDS
  37 -----------------
  38 Before reading this cover to cover, you may want to take a look
  39 at the link:tutorial.html[tutorial] document.  If you are
  40 migrating from CVS, link:cvs-migration.html[cvs migration]
  41 document may be helpful after you finish the tutorial.
  42
  43 The <<Discussion>> section below contains much useful definition
  44 and clarification info - read that first.  After that, if you
  45 are interested in using git to manage (version control)
  46 projects, use link:everyday.html[Everyday GIT] as a guide to the
  47 minimum set of commands you need to know for day-to-day work.
  48
  49 After you get the general feel from the tutorial and this
  50 overview page, you may want to take a look at the
  51 link:howto-index.html[howto] documents.
  52
  53 If you are writing your own Porcelain, you need to be familiar
  54 with most of the low level commands --- I suggest starting from
  55 gitlink:git-update-index[1] and gitlink:git-read-tree[1].
  56
  57
  58 David Greaves <david@dgreaves.com>
  59 08/05/05
  60
  61 Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 and
  62 further on 2005-12-07 to reflect recent changes.
  63
  64 Commands Overview
  65 -----------------
  66 The git commands can helpfully be split into those that manipulate
  67 the repository, the index and the files in the working tree, those that
  68 interrogate and compare them, and those that moves objects and
  69 references between repositories.
  70
  71 In addition, git itself comes with a spartan set of porcelain
  72 commands.  They are usable but are not meant to compete with real
  73 Porcelains.
  74
  75 There are also some ancillary programs that can be viewed as useful
  76 aids for using the core commands but which are unlikely to be used by
  77 SCMs layered over git.
  78
  79 Manipulation commands
  80 ~~~~~~~~~~~~~~~~~~~~~
  81 gitlink:git-apply[1]::
  82         Reads a "diff -up1" or git generated patch file and
  83         applies it to the working tree.
  84
  85 gitlink:git-checkout-index[1]::
  86         Copy files from the index to the working tree.
  87
  88 gitlink:git-commit-tree[1]::
  89         Creates a new commit object.
  90
  91 gitlink:git-hash-object[1]::
  92         Computes the object ID from a file.
  93
  94 gitlink:git-index-pack[1]::
  95         Build pack idx file for an existing packed archive.
  96
  97 gitlink:git-init-db[1]::
  98         Creates an empty git object database, or reinitialize an
  99         existing one.
 100
 101 gitlink:git-merge-index[1]::
 102         Runs a merge for files needing merging.
 103
 104 gitlink:git-mktag[1]::
 105         Creates a tag object.
 106
 107 gitlink:git-pack-objects[1]::
 108         Creates a packed archive of objects.
 109
 110 gitlink:git-prune-packed[1]::
 111         Remove extra objects that are already in pack files.
 112
 113 gitlink:git-read-tree[1]::
 114         Reads tree information into the index.
 115
 116 gitlink:git-repo-config[1]::
 117         Get and set options in .git/config.
 118
 119 gitlink:git-unpack-objects[1]::
 120         Unpacks objects out of a packed archive.
 121
 122 gitlink:git-update-index[1]::
 123         Registers files in the working tree to the index.
 124
 125 gitlink:git-write-tree[1]::
 126         Creates a tree from the index.
 127
 128
 129 Interrogation commands
 130 ~~~~~~~~~~~~~~~~~~~~~~
 131
 132 gitlink:git-cat-file[1]::
 133         Provide content or type/size information for repository objects.
 134
 135 gitlink:git-diff-index[1]::
 136         Compares content and mode of blobs between the index and repository.
 137
 138 gitlink:git-diff-files[1]::
 139         Compares files in the working tree and the index.
 140
 141 gitlink:git-diff-stages[1]::
 142         Compares two "merge stages" in the index.
 143
 144 gitlink:git-diff-tree[1]::
 145         Compares the content and mode of blobs found via two tree objects.
 146
 147 gitlink:git-fsck-objects[1]::
 148         Verifies the connectivity and validity of the objects in the database.
 149
 150 gitlink:git-ls-files[1]::
 151         Information about files in the index and the working tree.
 152
 153 gitlink:git-ls-tree[1]::
 154         Displays a tree object in human readable form.
 155
 156 gitlink:git-merge-base[1]::
 157         Finds as good common ancestors as possible for a merge.
 158
 159 gitlink:git-name-rev[1]::
 160         Find symbolic names for given revs.
 161
 162 gitlink:git-pack-redundant[1]::
 163         Find redundant pack files.
 164
 165 gitlink:git-rev-list[1]::
 166         Lists commit objects in reverse chronological order.
 167
 168 gitlink:git-show-index[1]::
 169         Displays contents of a pack idx file.
 170
 171 gitlink:git-tar-tree[1]::
 172         Creates a tar archive of the files in the named tree object.
 173
 174 gitlink:git-unpack-file[1]::
 175         Creates a temporary file with a blob's contents.
 176
 177 gitlink:git-var[1]::
 178         Displays a git logical variable.
 179
 180 gitlink:git-verify-pack[1]::
 181         Validates packed git archive files.
 182
 183 In general, the interrogate commands do not touch the files in
 184 the working tree.
 185
 186
 187 Synching repositories
 188 ~~~~~~~~~~~~~~~~~~~~~
 189
 190 gitlink:git-clone-pack[1]::
 191         Clones a repository into the current repository (engine
 192         for ssh and local transport).
 193
 194 gitlink:git-fetch-pack[1]::
 195         Updates from a remote repository (engine for ssh and
 196         local transport).
 197
 198 gitlink:git-http-fetch[1]::
 199         Downloads a remote git repository via HTTP by walking
 200         commit chain.
 201
 202 gitlink:git-local-fetch[1]::
 203         Duplicates another git repository on a local system by
 204         walking commit chain.
 205
 206 gitlink:git-peek-remote[1]::
 207         Lists references on a remote repository using
 208         upload-pack protocol (engine for ssh and local
 209         transport).
 210
 211 gitlink:git-receive-pack[1]::
 212         Invoked by 'git-send-pack' to receive what is pushed to it.
 213
 214 gitlink:git-send-pack[1]::
 215         Pushes to a remote repository, intelligently.
 216
 217 gitlink:git-http-push[1]::
 218         Push missing objects using HTTP/DAV.
 219
 220 gitlink:git-shell[1]::
 221         Restricted shell for GIT-only SSH access.
 222
 223 gitlink:git-ssh-fetch[1]::
 224         Pulls from a remote repository over ssh connection by
 225         walking commit chain.
 226
 227 gitlink:git-ssh-upload[1]::
 228         Helper "server-side" program used by git-ssh-fetch.
 229
 230 gitlink:git-update-server-info[1]::
 231         Updates auxiliary information on a dumb server to help
 232         clients discover references and packs on it.
 233
 234 gitlink:git-upload-pack[1]::
 235         Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
 236         what are asked for.
 237
 238
 239 Porcelain-ish Commands
 240 ----------------------
 241
 242 gitlink:git-add[1]::
 243         Add paths to the index.
 244
 245 gitlink:git-am[1]::
 246         Apply patches from a mailbox, but cooler.
 247
 248 gitlink:git-applymbox[1]::
 249         Apply patches from a mailbox, original version by Linus.
 250
 251 gitlink:git-bisect[1]::
 252         Find the change that introduced a bug by binary search.
 253
 254 gitlink:git-branch[1]::
 255         Create and Show branches.
 256
 257 gitlink:git-checkout[1]::
 258         Checkout and switch to a branch.
 259
 260 gitlink:git-cherry-pick[1]::
 261         Cherry-pick the effect of an existing commit.
 262
 263 gitlink:git-clone[1]::
 264         Clones a repository into a new directory.
 265
 266 gitlink:git-commit[1]::
 267         Record changes to the repository.
 268
 269 gitlink:git-diff[1]::
 270         Show changes between commits, commit and working tree, etc.
 271
 272 gitlink:git-fetch[1]::
 273         Download from a remote repository via various protocols.
 274
 275 gitlink:git-format-patch[1]::
 276         Prepare patches for e-mail submission.
 277
 278 gitlink:git-grep[1]::
 279         Print lines matching a pattern.
 280
 281 gitlink:git-log[1]::
 282         Shows commit logs.
 283
 284 gitlink:git-ls-remote[1]::
 285         Shows references in a remote or local repository.
 286
 287 gitlink:git-merge[1]::
 288         Grand unified merge driver.
 289
 290 gitlink:git-mv[1]::
 291         Move or rename a file, a directory, or a symlink.
 292
 293 gitlink:git-octopus[1]::
 294         Merge more than two commits.
 295
 296 gitlink:git-pull[1]::
 297         Fetch from and merge with a remote repository.
 298
 299 gitlink:git-push[1]::
 300         Update remote refs along with associated objects.
 301
 302 gitlink:git-rebase[1]::
 303         Rebase local commits to the updated upstream head.
 304
 305 gitlink:git-repack[1]::
 306         Pack unpacked objects in a repository.
 307
 308 gitlink:git-reset[1]::
 309         Reset current HEAD to the specified state.
 310
 311 gitlink:git-resolve[1]::
 312         Merge two commits.
 313
 314 gitlink:git-revert[1]::
 315         Revert an existing commit.
 316
 317 gitlink:git-shortlog[1]::
 318         Summarizes 'git log' output.
 319
 320 gitlink:git-show-branch[1]::
 321         Show branches and their commits.
 322
 323 gitlink:git-status[1]::
 324         Shows the working tree status.
 325
 326 gitlink:git-verify-tag[1]::
 327         Check the GPG signature of tag.
 328
 329 gitlink:git-whatchanged[1]::
 330         Shows commit logs and differences they introduce.
 331
 332
 333 Ancillary Commands
 334 ------------------
 335 Manipulators:
 336
 337 gitlink:git-applypatch[1]::
 338         Apply one patch extracted from an e-mail.
 339
 340 gitlink:git-archimport[1]::
 341         Import an arch repository into git.
 342
 343 gitlink:git-convert-objects[1]::
 344         Converts old-style git repository.
 345
 346 gitlink:git-cvsimport[1]::
 347         Salvage your data out of another SCM people love to hate.
 348
 349 gitlink:git-cvsexportcommit[1]::
 350         Export a single commit to a CVS checkout.
 351
 352 gitlink:git-lost-found[1]::
 353         Recover lost refs that luckily have not yet been pruned.
 354
 355 gitlink:git-merge-one-file[1]::
 356         The standard helper program to use with `git-merge-index`.
 357
 358 gitlink:git-prune[1]::
 359         Prunes all unreachable objects from the object database.
 360
 361 gitlink:git-relink[1]::
 362         Hardlink common objects in local repositories.
 363
 364 gitlink:git-svnimport[1]::
 365         Import a SVN repository into git.
 366
 367 gitlink:git-sh-setup[1]::
 368         Common git shell script setup code.
 369
 370 gitlink:git-symbolic-ref[1]::
 371         Read and modify symbolic refs.
 372
 373 gitlink:git-tag[1]::
 374         An example script to create a tag object signed with GPG.
 375
 376 gitlink:git-update-ref[1]::
 377         Update the object name stored in a ref safely.
 378
 379
 380 Interrogators:
 381
 382 gitlink:git-check-ref-format[1]::
 383         Make sure ref name is well formed.
 384
 385 gitlink:git-cherry[1]::
 386         Find commits not merged upstream.
 387
 388 gitlink:git-count-objects[1]::
 389         Count unpacked number of objects and their disk consumption.
 390
 391 gitlink:git-daemon[1]::
 392         A really simple server for git repositories.
 393
 394 gitlink:git-get-tar-commit-id[1]::
 395         Extract commit ID from an archive created using git-tar-tree.
 396
 397 gitlink:git-mailinfo[1]::
 398         Extracts patch and authorship information from a single
 399         e-mail message, optionally transliterating the commit
 400         message into utf-8.
 401
 402 gitlink:git-mailsplit[1]::
 403         A stupid program to split UNIX mbox format mailbox into
 404         individual pieces of e-mail.
 405
 406 gitlink:git-patch-id[1]::
 407         Compute unique ID for a patch.
 408
 409 gitlink:git-parse-remote[1]::
 410         Routines to help parsing `$GIT_DIR/remotes/` files.
 411
 412 gitlink:git-request-pull[1]::
 413         git-request-pull.
 414
 415 gitlink:git-rev-parse[1]::
 416         Pick out and massage parameters.
 417
 418 gitlink:git-send-email[1]::
 419         Send patch e-mails out of "format-patch --mbox" output.
 420
 421 gitlink:git-symbolic-refs[1]::
 422         Read and modify symbolic refs.
 423
 424 gitlink:git-stripspace[1]::
 425         Filter out empty lines.
 426
 427
 428 Commands not yet documented
 429 ---------------------------
 430
 431 gitlink:gitk[1]::
 432         The gitk repository browser.
 433
 434
 435 Configuration Mechanism
 436 -----------------------
 437
 438 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
 439 is used to hold per-repository configuration options.  It is a
 440 simple text file modelled after `.ini` format familiar to some
 441 people.  Here is an example:
 442
 443 ------------
 444 #
 445 # A '#' or ';' character indicates a comment.
 446 #
 447
 448 ; core variables
 449 [core]
 450         ; Don't trust file modes
 451         filemode = false
 452
 453 ; user identity
 454 [user]
 455         name = "Junio C Hamano"
 456         email = "junkio@twinsun.com"
 457
 458 ------------
 459
 460 Various commands read from the configuration file and adjust
 461 their operation accordingly.
 462
 463
 464 Identifier Terminology
 465 ----------------------
 466 <object>::
 467         Indicates the object name for any type of object.
 468
 469 <blob>::
 470         Indicates a blob object name.
 471
 472 <tree>::
 473         Indicates a tree object name.
 474
 475 <commit>::
 476         Indicates a commit object name.
 477
 478 <tree-ish>::
 479         Indicates a tree, commit or tag object name.  A
 480         command that takes a <tree-ish> argument ultimately wants to
 481         operate on a <tree> object but automatically dereferences
 482         <commit> and <tag> objects that point at a <tree>.
 483
 484 <type>::
 485         Indicates that an object type is required.
 486         Currently one of: `blob`, `tree`, `commit`, or `tag`.
 487
 488 <file>::
 489         Indicates a filename - almost always relative to the
 490         root of the tree structure `GIT_INDEX_FILE` describes.
 491
 492 Symbolic Identifiers
 493 --------------------
 494 Any git command accepting any <object> can also use the following
 495 symbolic notation:
 496
 497 HEAD::
 498         indicates the head of the current branch (i.e. the
 499         contents of `$GIT_DIR/HEAD`).
 500
 501 <tag>::
 502         a valid tag 'name'
 503         (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
 504
 505 <head>::
 506         a valid head 'name'
 507         (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
 508
 509 <snap>::
 510         a valid snapshot 'name'
 511         (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
 512
 513
 514 File/Directory Structure
 515 ------------------------
 516
 517 Please see link:repository-layout.html[repository layout] document.
 518
 519 Higher level SCMs may provide and manage additional information in the
 520 `$GIT_DIR`.
 521
 522
 523 Terminology
 524 -----------
 525 Please see link:glossary.html[glossary] document.
 526
 527
 528 Environment Variables
 529 ---------------------
 530 Various git commands use the following environment variables:
 531
 532 The git Repository
 533 ~~~~~~~~~~~~~~~~~~
 534 These environment variables apply to 'all' core git commands. Nb: it
 535 is worth noting that they may be used/overridden by SCMS sitting above
 536 git so take care if using Cogito etc.
 537
 538 'GIT_INDEX_FILE'::
 539         This environment allows the specification of an alternate
 540         index file. If not specified, the default of `$GIT_DIR/index`
 541         is used.
 542
 543 'GIT_OBJECT_DIRECTORY'::
 544         If the object storage directory is specified via this
 545         environment variable then the sha1 directories are created
 546         underneath - otherwise the default `$GIT_DIR/objects`
 547         directory is used.
 548
 549 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
 550         Due to the immutable nature of git objects, old objects can be
 551         archived into shared, read-only directories. This variable
 552         specifies a ":" separated list of git object directories which
 553         can be used to search for git objects. New objects will not be
 554         written to these directories.
 555
 556 'GIT_DIR'::
 557         If the 'GIT_DIR' environment variable is set then it
 558         specifies a path to use instead of the default `.git`
 559         for the base of the repository.
 560
 561 git Commits
 562 ~~~~~~~~~~~
 563 'GIT_AUTHOR_NAME'::
 564 'GIT_AUTHOR_EMAIL'::
 565 'GIT_AUTHOR_DATE'::
 566 'GIT_COMMITTER_NAME'::
 567 'GIT_COMMITTER_EMAIL'::
 568         see gitlink:git-commit-tree[1]
 569
 570 git Diffs
 571 ~~~~~~~~~
 572 'GIT_DIFF_OPTS'::
 573 'GIT_EXTERNAL_DIFF'::
 574         see the "generating patches" section in :
 575         gitlink:git-diff-index[1];
 576         gitlink:git-diff-files[1];
 577         gitlink:git-diff-tree[1]
 578
 579 Discussion[[Discussion]]
 580 ------------------------
 581 include::../README[]
 582
 583 Authors
 584 -------
 585         git's founding father is Linus Torvalds <torvalds@osdl.org>.
 586         The current git nurse is Junio C Hamano <junkio@cox.net>.
 587         The git potty was written by Andres Ericsson <ae@op5.se>.
 588         General upbringing is handled by the git-list <git@vger.kernel.org>.
 589
 590 Documentation
 591 --------------
 592 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
 593
 594 GIT
 595 ---
 596 Part of the gitlink:git[7] suite
 597