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