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