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