Provided by: git-core_1.1.3-1ubuntu1_i386 bug

NAME

       git - the stupid content tracker

SYNOPSIS

       git [--version] [--exec-path[=GIT_EXEC_PATH]] [--help] COMMAND [ARGS]

DESCRIPTION

       git  is  both  a  program  and  a directory content tracker system. The
       program git is just a wrapper to reach the  core  git  programs  (or  a
       potty  if you like, as it’s not exactly porcelain but still brings your
       stuff to the plumbing).

OPTIONS

       --version
              prints the git suite version that the git program came from.

       --help prints the synopsis and a list of available commands. If  a  git
              command is named this option will bring up the man-page for that
              command.

       --exec-path
              path to wherever your core git programs are installed. This  can
              also  be  controlled  by  setting  the GIT_EXEC_PATH environment
              variable. If no path is given git will print the current setting
              and then exit.

NOT LEARNING CORE GIT COMMANDS

       This  manual  is  intended  to give complete background information and
       internal workings of git, which may be too much for  most  people.  The
       [xref  to  anchor]  section  below  contains much useful definition and
       clarification - read that first.

       If you  are  interested  in  using  git  to  manage  (version  control)
       projects, use Everyday GIT: everyday.html as a guide to the minimum set
       of commands you need to know for day-to-day  work.  Most  likely,  that
       will get you started, and you can go a long way without knowing the low
       level details too much.

       The tutorial: tutorial.html document covers how things internally work.

       If  you  are  migrating  from  CVS,  cvs  migration: cvs-migration.html
       document may be helpful after you finish the tutorial.

       After you get the general feel from  the  tutorial  and  this  overview
       page,  you  may  want  to  take  a  look at the howto: howto-index.html
       documents.

CORE GIT COMMANDS

       If you are writing your own Porcelain, you need  to  be  familiar  with
       most   of   the   low  level  commands  ---  I  suggest  starting  from
       git-update-index(1) and git-read-tree(1).

COMMANDS OVERVIEW

       The git commands can helpfully be split into those that manipulate  the
       repository,  the  index  and  the files in the working tree, those that
       interrogate  and  compare  them,  and  those  that  moves  objects  and
       references between repositories.

       In addition, git itself comes with a spartan set of porcelain commands.
       They are usable but are not meant to compete with real Porcelains.

       There are also some ancillary programs that can  be  viewed  as  useful
       aids  for  using the core commands but which are unlikely to be used by
       SCMs layered over git.

   Manipulation commands
       git-apply(1)
              Reads a "diff -up1" or git generated patch file and  applies  it
              to the working tree.

       git-checkout-index(1)
              Copy files from the index to the working tree.

       git-commit-tree(1)
              Creates a new commit object.

       git-hash-object(1)
              Computes the object ID from a file.

       git-index-pack(1)
              Build pack idx file for an existing packed archive.

       git-init-db(1)
              Creates  an  empty  git  object  database,  or  reinitialize  an
              existing one.

       git-merge-index(1)
              Runs a merge for files needing merging.

       git-mktag(1)
              Creates a tag object.

       git-pack-objects(1)
              Creates a packed archive of objects.

       git-prune-packed(1)
              Remove extra objects that are already in pack files.

       git-read-tree(1)
              Reads tree information into the index.

       git-repo-config(1)
              Get and set options in .git/config.

       git-unpack-objects(1)
              Unpacks objects out of a packed archive.

       git-update-index(1)
              Registers files in the working tree to the index.

       git-write-tree(1)
              Creates a tree from the index.

   Interrogation commands
       git-cat-file(1)
              Provide content or type/size information for repository objects.

       git-describe(1)
              Show the most recent tag that is reachable from a commit.

       git-diff-index(1)
              Compares  content  and  mode  of  blobs  between  the  index and
              repository.

       git-diff-files(1)
              Compares files in the working tree and the index.

       git-diff-stages(1)
              Compares two "merge stages" in the index.

       git-diff-tree(1)
              Compares the content and  mode  of  blobs  found  via  two  tree
              objects.

       git-fsck-objects(1)
              Verifies  the  connectivity  and  validity of the objects in the
              database.

       git-ls-files(1)
              Information about files in the index and the working tree.

       git-ls-tree(1)
              Displays a tree object in human readable form.

       git-merge-base(1)
              Finds as good common ancestors as possible for a merge.

       git-name-rev(1)
              Find symbolic names for given revs.

       git-pack-redundant(1)
              Find redundant pack files.

       git-rev-list(1)
              Lists commit objects in reverse chronological order.

       git-show-index(1)
              Displays contents of a pack idx file.

       git-tar-tree(1)
              Creates a tar archive of the files in the named tree object.

       git-unpack-file(1)
              Creates a temporary file with a blob’s contents.

       git-var(1)
              Displays a git logical variable.

       git-verify-pack(1)
              Validates packed git archive files.

              In general, the interrogate commands do not touch the  files  in
              the working tree.

   Synching repositories
       git-clone-pack(1)
              Clones  a repository into the current repository (engine for ssh
              and local transport).

       git-fetch-pack(1)
              Updates from a remote  repository  (engine  for  ssh  and  local
              transport).

       git-http-fetch(1)
              Downloads  a  remote  git  repository via HTTP by walking commit
              chain.

       git-local-fetch(1)
              Duplicates another git repository on a local system  by  walking
              commit chain.

       git-peek-remote(1)
              Lists  references  on  a  remote  repository  using  upload-pack
              protocol (engine for ssh and local transport).

       git-receive-pack(1)
              Invoked by git-send-pack to receive what is pushed to it.

       git-send-pack(1)
              Pushes to a remote repository, intelligently.

       git-http-push(1)
              Push missing objects using HTTP/DAV.

       git-shell(1)
              Restricted shell for GIT-only SSH access.

       git-ssh-fetch(1)
              Pulls from a remote repository over ssh  connection  by  walking
              commit chain.

       git-ssh-upload(1)
              Helper "server-side" program used by git-ssh-fetch.

       git-update-server-info(1)
              Updates  auxiliary  information on a dumb server to help clients
              discover references and packs on it.

       git-upload-pack(1)
              Invoked by git-clone-pack and git-fetch-pack to  push  what  are
              asked for.

PORCELAIN-ISH COMMANDS

       git-add(1)
              Add paths to the index.

       git-am(1)
              Apply patches from a mailbox, but cooler.

       git-applymbox(1)
              Apply patches from a mailbox, original version by Linus.

       git-bisect(1)
              Find the change that introduced a bug by binary search.

       git-branch(1)
              Create and Show branches.

       git-checkout(1)
              Checkout and switch to a branch.

       git-cherry-pick(1)
              Cherry-pick the effect of an existing commit.

       git-clone(1)
              Clones a repository into a new directory.

       git-commit(1)
              Record changes to the repository.

       git-diff(1)
              Show changes between commits, commit and working tree, etc.

       git-fetch(1)
              Download from a remote repository via various protocols.

       git-format-patch(1)
              Prepare patches for e-mail submission.

       git-grep(1)
              Print lines matching a pattern.

       git-log(1)
              Shows commit logs.

       git-ls-remote(1)
              Shows references in a remote or local repository.

       git-merge(1)
              Grand unified merge driver.

       git-mv(1)
              Move or rename a file, a directory, or a symlink.

       git-pull(1)
              Fetch from and merge with a remote repository.

       git-push(1)
              Update remote refs along with associated objects.

       git-rebase(1)
              Rebase local commits to the updated upstream head.

       git-repack(1)
              Pack unpacked objects in a repository.

       git-reset(1)
              Reset current HEAD to the specified state.

       git-resolve(1)
              Merge two commits.

       git-revert(1)
              Revert an existing commit.

       git-shortlog(1)
              Summarizes git log output.

       git-show-branch(1)
              Show branches and their commits.

       git-status(1)
              Shows the working tree status.

       git-verify-tag(1)
              Check the GPG signature of tag.

       git-whatchanged(1)
              Shows commit logs and differences they introduce.

ANCILLARY COMMANDS

       Manipulators:

       git-applypatch(1)
              Apply one patch extracted from an e-mail.

       git-archimport(1)
              Import an arch repository into git.

       git-convert-objects(1)
              Converts old-style git repository.

       git-cvsimport(1)
              Salvage your data out of another SCM people love to hate.

       git-cvsexportcommit(1)
              Export a single commit to a CVS checkout.

       git-lost-found(1)
              Recover lost refs that luckily have not yet been pruned.

       git-merge-one-file(1)
              The standard helper program to use with git-merge-index.

       git-prune(1)
              Prunes all unreachable objects from the object database.

       git-relink(1)
              Hardlink common objects in local repositories.

       git-svnimport(1)
              Import a SVN repository into git.

       git-sh-setup(1)
              Common git shell script setup code.

       git-symbolic-ref(1)
              Read and modify symbolic refs.

       git-tag(1)
              An example script to create a tag object signed with GPG.

       git-update-ref(1)
              Update the object name stored in a ref safely.

              Interrogators:

       git-check-ref-format(1)
              Make sure ref name is well formed.

       git-cherry(1)
              Find commits not merged upstream.

       git-count-objects(1)
              Count unpacked number of objects and their disk consumption.

       git-daemon(1)
              A really simple server for git repositories.

       git-get-tar-commit-id(1)
              Extract commit ID from an archive created using git-tar-tree.

       git-mailinfo(1)
              Extracts  patch  and authorship information from a single e-mail
              message, optionally  transliterating  the  commit  message  into
              utf-8.

       git-mailsplit(1)
              A  stupid  program  to  split  UNIX  mbox  format  mailbox  into
              individual pieces of e-mail.

       git-patch-id(1)
              Compute unique ID for a patch.

       git-parse-remote(1)
              Routines to help parsing $GIT_DIR/remotes/ files.

       git-request-pull(1)
              git-request-pull.

       git-rev-parse(1)
              Pick out and massage parameters.

       git-send-email(1)
              Send patch e-mails out of "format-patch --mbox" output.

       git-symbolic-ref(1)
              Read and modify symbolic refs.

       git-stripspace(1)
              Filter out empty lines.

COMMANDS NOT YET DOCUMENTED

       gitk(1)
              The gitk repository browser.

CONFIGURATION MECHANISM

       Starting from 0.99.9 (actually mid  0.99.8.GIT),  .git/config  file  is
       used  to hold per-repository configuration options. It is a simple text
       file modelled after .ini format familiar to some  people.  Here  is  an
       example:

              # # A ’#’ or ’;’ character indicates a comment.  #

              ; core variables [core]
                      ; Don’t trust file modes
                      filemode = false

              ; user identity [user]
                      name = "Junio C Hamano"
                      email = "junkio@twinsun.com"

              Various  commands  read  from  the configuration file and adjust
              their operation accordingly.

IDENTIFIER TERMINOLOGY

       <object>
              Indicates the object name for any type of object.

       <blob> Indicates a blob object name.

       <tree> Indicates a tree object name.

       <commit>
              Indicates a commit object name.

       <tree-ish>
              Indicates a tree, commit or tag  object  name.  A  command  that
              takes  a  <tree-ish>  argument  ultimately wants to operate on a
              <tree> object but automatically dereferences <commit> and  <tag>
              objects that point at a <tree>.

       <type> Indicates  that  an  object  type is required. Currently one of:
              blob, tree, commit, or tag.

       <file> Indicates a filename - almost always relative to the root of the
              tree structure GIT_INDEX_FILE describes.

SYMBOLIC IDENTIFIERS

       Any  git  command  accepting  any  <object>  can also use the following
       symbolic notation:

       HEAD   indicates the head of the current branch (i.e. the  contents  of
              $GIT_DIR/HEAD).

       <tag>  a     valid     tag     name     (i.e.     the    contents    of
              $GIT_DIR/refs/tags/<tag>).

       <head> a    valid    head    name     (i.e.     the     contents     of
              $GIT_DIR/refs/heads/<head>).

       <snap> a    valid    snapshot    name    (i.e.    the    contents    of
              $GIT_DIR/refs/snap/<snap>).

FILE/DIRECTORY STRUCTURE

       Please see repository layout: repository-layout.html document.

       Higher level SCMs may provide and manage additional information in  the
       $GIT_DIR.

TERMINOLOGY

       Please see glossary: glossary.html document.

ENVIRONMENT VARIABLES

       Various git commands use the following environment variables:

   The git Repository
       These  environment  variables apply to all core git commands. Nb: it is
       worth noting that they may be used/overridden by SCMS sitting above git
       so take care if using Cogito etc.

       GIT_INDEX_FILE
              This  environment allows the specification of an alternate index
              file. If not specified, the default of $GIT_DIR/index is used.

       GIT_OBJECT_DIRECTORY
              If  the  object  storage  directory  is   specified   via   this
              environment  variable  then  the  sha1  directories  are created
              underneath - otherwise the default $GIT_DIR/objects directory is
              used.

       GIT_ALTERNATE_OBJECT_DIRECTORIES
              Due  to  the immutable nature of git objects, old objects can be
              archived  into  shared,  read-only  directories.  This  variable
              specifies  a  ":" separated list of git object directories which
              can be used to search for git objects. New objects will  not  be
              written to these directories.

       GIT_DIR
              If  the  GIT_DIR environment variable is set then it specifies a
              path to use instead of the default .git  for  the  base  of  the
              repository.

   git Commits
       GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME,
       GIT_COMMITTER_EMAIL
              see git-commit-tree(1)

   git Diffs
       GIT_DIFF_OPTS, GIT_EXTERNAL_DIFF
              see  the  "generating  patches"  section in : git-diff-index(1);
              git-diff-files(1); git-diff-tree(1)

DISCUSSION

       "git" can mean anything, depending on your mood.

       ·  random three-letter  combination  that  is  pronounceable,  and  not
          actually  used  by  any  common  UNIX command. The fact that it is a
          mispronunciation of "get" may or may not be relevant.

       ·  stupid. contemptible and despicable. simple. Take your pick from the
          dictionary of slang.

       ·  "global information tracker": you’re in a good mood, and it actually
          works for you. Angels sing, and a light suddenly fills the room.

       ·  "goddamn idiotic truckload of sh*t": when it breaks

       This is a stupid (but extremely fast)  directory  content  manager.  It
       doesn’t do a whole lot, but what it does do is track directory contents
       efficiently.

       There are two object  abstractions:  the  "object  database",  and  the
       "current directory cache" aka "index".

   The Object Database
       The  object database is literally just a content-addressable collection
       of  objects.  All  objects  are  named  by  their  content,  which   is
       approximated  by  the SHA1 hash of the object itself. Objects may refer
       to other objects (by referencing their SHA1 hash), and so you can build
       up a hierarchy of objects.

       All  objects  have  a  statically determined "type" aka "tag", which is
       determined at object creation time, and which identifies the format  of
       the  object  (i.e.  how  it  is  used,  and  how  it can refer to other
       objects). There are currently  four  different  object  types:  "blob",
       "tree", "commit" and "tag".

       A "blob" object cannot refer to any other object, and is, like the type
       implies, a pure storage object containing some user data. It is used to
       actually  store  the  file  data, i.e. a blob object is associated with
       some particular version of some file.

       A "tree" object is an object that ties one or more "blob" objects  into
       a  directory  structure.  In addition, a tree object can refer to other
       tree objects, thus creating a directory hierarchy.

       A "commit" object ties such directory hierarchies together into  a  DAG
       of  revisions  - each "commit" is associated with exactly one tree (the
       directory hierarchy at the time of the commit). In addition, a "commit"
       refers to one or more "parent" commit objects that describe the history
       of how we arrived at that directory hierarchy.

       As a special case, a commit object with no parents is called the "root"
       object,  and  is  the  point of an initial project commit. Each project
       must have at least one root, and while you can  tie  several  different
       root  objects  together  into  one  project by creating a commit object
       which has two or more separate roots as its  ultimate  parents,  that’s
       probably  just  going  to confuse people. So aim for the notion of "one
       root object per project", even if git itself does not enforce that.

       A "tag" object symbolically identifies and can be used  to  sign  other
       objects.  It  contains  the  identifier  and  type of another object, a
       symbolic name (of course!) and, optionally, a signature.

       Regardless  of  object  type,   all   objects   share   the   following
       characteristics:  they  are  all  deflated with zlib, and have a header
       that not only specifies their type, but also provides size  information
       about the data in the object. It’s worth noting that the SHA1 hash that
       is used to name the object is the hash of the original data  plus  this
       header,  so  sha1sum  file  does  not  match  the object name for file.
       (Historical note: in the dawn of the age of git the hash was  the  sha1
       of the compressed object.)

       As  a result, the general consistency of an object can always be tested
       independently of the contents or the type of the  object:  all  objects
       can  be  validated by verifying that (a) their hashes match the content
       of the file and (b) the object successfully inflates  to  a  stream  of
       bytes  that  forms a sequence of <ascii type without space> + <space> +
       <ascii decimal size> + <byte\0> + <binary object data>.

       The  structured  objects  can  further   have   their   structure   and
       connectivity to other objects verified. This is generally done with the
       git-fsck-objects program, which generates a full  dependency  graph  of
       all  objects,  and  verifies their internal consistency (in addition to
       just verifying their superficial consistency through the hash).

       The object types in some more detail:

   Blob Object
       A "blob" object is nothing but a binary blob of data, and doesn’t refer
       to  anything  else.  There is no signature or any other verification of
       the data, so while the object is consistent (it is indexed by its  sha1
       hash,  so  the  data itself is certainly correct), it has absolutely no
       other attributes. No name associations, no permissions. It is purely  a
       blob of data (i.e. normally "file contents").

       In  particular,  since the blob is entirely defined by its data, if two
       files in a directory tree (or in multiple  different  versions  of  the
       repository)  have  the  same  contents,  they  will share the same blob
       object. The object is  totally  independent  of  its  location  in  the
       directory  tree,  and  renaming  a file does not change the object that
       file is associated with in any way.

       A blob is typically created when git-update-index(1) is  run,  and  its
       data can be accessed by git-cat-file(1).

   Tree Object
       The  next  hierarchical object type is the "tree" object. A tree object
       is a list of mode/name/blob data, sorted by  name.  Alternatively,  the
       mode data may specify a directory mode, in which case instead of naming
       a blob, that name is associated with another TREE object.

       Like the "blob" object, a tree object is uniquely determined by the set
       contents, and so two separate but identical trees will always share the
       exact same object. This is true at all levels, i.e.  it’s  true  for  a
       "leaf"  tree  (which  does not refer to any other trees, only blobs) as
       well as for a whole subdirectory.

       For that reason a "tree" object is just a pure data abstraction: it has
       no  history,  no  signatures,  no verification of validity, except that
       since the contents are again protected by the hash itself, we can trust
       that the tree is immutable and its contents never change.

       So  you  can trust the contents of a tree to be valid, the same way you
       can trust the contents of a  blob,  but  you  don’t  know  where  those
       contents came from.

       Side  note  on  trees:  since  a  "tree"  object  is  a  sorted list of
       "filename+content", you can create a diff  between  two  trees  without
       actually  having to unpack two trees. Just ignore all common parts, and
       your diff will look right. In other words,  you  can  effectively  (and
       efficiently)  tell  the difference between any two random trees by O(n)
       where "n" is the size of the difference, rather than the  size  of  the
       tree.

       Side  note  2 on trees: since the name of a "blob" depends entirely and
       exclusively on its contents (i.e. there are  no  names  or  permissions
       involved),  you  can  see  trivial  renames  or  permission  changes by
       noticing that the blob stayed the  same.  However,  renames  with  data
       changes need a smarter "diff" implementation.

       A  tree  is created with git-write-tree(1) and its data can be accessed
       by git-ls-tree(1). Two trees can be compared with git-diff-tree(1).

   Commit Object
       The "commit" object is an object that introduces the notion of  history
       into  the  picture.  In  contrast to the other objects, it doesn’t just
       describe the physical state of a tree, it describes how we  got  there,
       and why.

       A "commit" is defined by the tree-object that it results in, the parent
       commits (zero, one or more) that led up to that point, and a comment on
       what  happened. Again, a commit is not trusted per se: the contents are
       well-defined and "safe" due to the cryptographically strong  signatures
       at  all  levels,  but  there  is  no reason to believe that the tree is
       "good" or that the merge information makes sense. The  parents  do  not
       have to actually have any relationship with the result, for example.

       Note  on  commits:  unlike  real  SCM’s,  commits do not contain rename
       information or file mode change information. All of that is implicit in
       the  trees  involved  (the  result  tree,  and  the result trees of the
       parents), and describing that makes  no  sense  in  this  idiotic  file
       manager.

       A  commit  is  created  with  git-commit-tree(1)  and  its  data can be
       accessed by git-cat-file(1).

   Trust
       An aside on the notion of "trust". Trust is really outside the scope of
       "git",  but it’s worth noting a few things. First off, since everything
       is hashed with SHA1, you can trust that an object is intact and has not
       been messed with by external sources. So the name of an object uniquely
       identifies a known state - just not a state that you may want to trust.

       Furthermore,  since  the  SHA1 signature of a commit refers to the SHA1
       signatures of the tree it is associated with and the signatures of  the
       parent,  a  single  named  commit  specifies  uniquely  a  whole set of
       history, with full contents. You can’t later fake any step of  the  way
       once you have the name of a commit.

       So  to introduce some real trust in the system, the only thing you need
       to do is to digitally sign just one special note,  which  includes  the
       name  of  a  top-level commit. Your digital signature shows others that
       you trust that commit, and the immutability of the history  of  commits
       tells others that they can trust the whole history.

       In other words, you can easily validate a whole archive by just sending
       out a single email that tells the people the name (SHA1  hash)  of  the
       top commit, and digitally sign that email using something like GPG/PGP.

       To assist in this, git also provides the tag object...

   Tag Object
       Git provides the  "tag"  object  to  simplify  creating,  managing  and
       exchanging symbolic and signed tokens. The "tag" object at its simplest
       simply symbolically identifies another object by containing  the  sha1,
       type and symbolic name.

       However  it  can  optionally  contain  additional signature information
       (which git doesn’t care about as long as there’s less than 8k  of  it).
       This can then be verified externally to git.

       Note  that  despite the tag features, "git" itself only handles content
       integrity;  the  trust   framework   (and   signature   provision   and
       verification) has to come from outside.

       A  tag  is  created  with  git-mktag(1),  its  data  can be accessed by
       git-cat-file(1),   and   the   signature    can    be    verified    by
       git-verify-tag(1).

THE INDEX" AKA CURRENT DIRECTORY CACHE"

       The  index  is  a  simple  binary  file,  which  contains  an efficient
       representation of a virtual directory content at some random  time.  It
       does  so  by  a  simple  array  that  associates a set of names, dates,
       permissions and content (aka "blob") objects  together.  The  cache  is
       always  kept  ordered  by  name,  and names are unique (with a few very
       specific rules) at any point in time, but the cache  has  no  long-term
       meaning, and can be partially updated at any time.

       In  particular, the index certainly does not need to be consistent with
       the current directory contents (in fact, most operations will depend on
       different  ways  to make the index not be consistent with the directory
       hierarchy), but it has three very important attributes:

       (a) it can re-generate the full state it caches (not just the directory
       structure:  it  contains  pointers to the "blob" objects so that it can
       regenerate the data too)

       As a special case, there is a clear  and  unambiguous  one-way  mapping
       from  a  current  directory  cache  to  a  "tree  object", which can be
       efficiently created from  just  the  current  directory  cache  without
       actually  looking  at  any  other data. So a directory cache at any one
       time uniquely specifies  one  and  only  one  "tree"  object  (but  has
       additional  data to make it easy to match up that tree object with what
       has happened in the directory)

       (b) it has efficient methods for finding inconsistencies  between  that
       cached state ("tree object waiting to be instantiated") and the current
       state.

       (c) it can additionally efficiently represent information  about  merge
       conflicts  between different tree objects, allowing each pathname to be
       associated with sufficient information about the  trees  involved  that
       you can create a three-way merge between them.

       Those  are  the three ONLY things that the directory cache does. It’s a
       cache, and the normal operation is to re-generate it completely from  a
       known  tree object, or update/compare it with a live tree that is being
       developed. If you blow the directory cache away entirely, you generally
       haven’t  lost  any information as long as you have the name of the tree
       that it described.

       At the same time, the index is at the same time also the  staging  area
       for  creating  new  trees,  and  creating  a new tree always involves a
       controlled modification of the index file.  In  particular,  the  index
       file  can  have the representation of an intermediate tree that has not
       yet been instantiated. So the index can be thought of as  a  write-back
       cache,  which  can  contain  dirty  information  that  has not yet been
       written back to the backing store.

THE WORKFLOW

       Generally, all "git" operations work on the index file. Some operations
       work purely on the index file (showing the current state of the index),
       but most operations move data to and from the index file.  Either  from
       the  database  or  from the working directory. Thus there are four main
       combinations:

   1) working directory -> index
       You update the index with information from the working  directory  with
       the   git-update-index(1)  command.  You  generally  update  the  index
       information by just specifying the filename you want  to  update,  like
       so:

       git-update-index filename

       but  to  avoid  common mistakes with filename globbing etc, the command
       will not normally add totally new entries or remove old  entries,  i.e.
       it will normally just update existing cache entries.

       To  tell  git  that  yes,  you  really do realize that certain files no
       longer exist, or that new files should be added,  you  should  use  the
       --remove and --add flags respectively.

       NOTE!  A  --remove  flag  does  not mean that subsequent filenames will
       necessarily be removed: if the files  still  exist  in  your  directory
       structure,  the  index  will  be  updated  with  their  new status, not
       removed. The only thing --remove means is  that  update-cache  will  be
       considering  a removed file to be a valid thing, and if the file really
       does not exist any more, it will update the index accordingly.

       As a special case, you can also do  git-update-index  --refresh,  which
       will  refresh the "stat" information of each index to match the current
       stat information. It will not update the object status itself,  and  it
       will  only  update  the fields that are used to quickly test whether an
       object still matches its old backing store object.

   2) index -> object database
       You write your current index file to a "tree" object with the program

       git-write-tree

       that doesn’t come with any options - it will just write out the current
       index  into  the  set  of tree objects that describe that state, and it
       will return the name of the resulting top-level tree. You can use  that
       tree  to  re-generate  the  index  at  any  time  by going in the other
       direction:

   3) object database -> index
       You read a "tree" file from  the  object  database,  and  use  that  to
       populate  (and  overwrite  -  don’t  do this if your index contains any
       unsaved state that you might  want  to  restore  later!)  your  current
       index. Normal operation is just

       git-read-tree <sha1 of tree>

       and  your  index file will now be equivalent to the tree that you saved
       earlier. However, that is only your index file: your working  directory
       contents have not been modified.

   4) index -> working directory
       You  update  your  working  directory  from the index by "checking out"
       files. This is not a very common operation, since normally  you’d  just
       keep  your  files  updated,  and  rather  than  write  to  your working
       directory, you’d tell the index files about the changes in your working
       directory (i.e. git-update-index).

       However,  if you decide to jump to a new version, or check out somebody
       else’s version, or just restore a previous tree,  you’d  populate  your
       index  file  with  read-tree, and then you need to check out the result
       with

       git-checkout-index filename

       or, if you want to check out all of the index, use -a.

       NOTE! git-checkout-index normally refuses to overwrite old files, so if
       you  have an old version of the tree already checked out, you will need
       to use the "-f" flag (before the "-a" flag or the  filename)  to  force
       the checkout.

       Finally, there are a few odds and ends which are not purely moving from
       one representation to the other:

   5) Tying it all together
       To commit a tree you have  instantiated  with  "git-write-tree",  you’d
       create  a  "commit"  object  that  refers  to that tree and the history
       behind it - most notably the  "parent"  commits  that  preceded  it  in
       history.

       Normally  a  "commit"  has  one  parent: the previous state of the tree
       before a certain change was made. However, sometimes it can have two or
       more  parent  commits,  in  which case we call it a "merge", due to the
       fact that such a commit brings together ("merges") two or more previous
       states represented by other commits.

       In  other words, while a "tree" represents a particular directory state
       of a working directory, a "commit" represents that state in "time", and
       explains how we got there.

       You  create  a  commit  object by giving it the tree that describes the
       state at the time of the commit, and a list of parents:

       git-commit-tree <tree> -p <parent> [-p <parent2> ..]

       and then giving the reason for the  commit  on  stdin  (either  through
       redirection from a pipe or file, or by just typing it at the tty).

       git-commit-tree will return the name of the object that represents that
       commit, and you should save it away  for  later  use.  Normally,  you’d
       commit  a new HEAD state, and while git doesn’t care where you save the
       note about that state, in practice we tend to just write the result  to
       the  file  pointed  at by .git/HEAD, so that we can always see what the
       last committed state was.

       Here is an ASCII art by  Jon  Loeliger  that  illustrates  how  various
       pieces fit together.

                                   commit-tree
                                    commit obj
                                     +----+
                                     |    |
                                     |    |
                                     V    V
                                  +-----------+
                                  | Object DB |
                                  |  Backing  |
                                  |   Store   |
                                  +-----------+
                                     ^
                         write-tree  |     |
                           tree obj  |     |
                                     |     |  read-tree
                                     |     |  tree obj
                                           V
                                  +-----------+
                                  |   Index   |
                                  |  "cache"  |
                                  +-----------+
                       update-index  ^
                           blob obj  |     |
                                     |     |
                  checkout-index -u  |     |  checkout-index
                           stat      |     |  blob obj
                                           V
                                  +-----------+
                                  |  Working  |
                                  | Directory |
                                  +-----------+

   6) Examining the data
       You  can  examine  the  data represented in the object database and the
       index with  various  helper  tools.  For  every  object,  you  can  use
       git-cat-file(1) to examine details about the object:

       git-cat-file -t <objectname>

       shows  the  type  of  the  object, and once you have the type (which is
       usually implicit in where you find the object), you can use

       git-cat-file blob|tree|commit|tag <objectname>

       to show its contents. NOTE! Trees have binary content, and as a  result
       there is a special helper for showing that content, called git-ls-tree,
       which turns the binary content into a more easily readable form.

       It’s especially instructive to look at "commit"  objects,  since  those
       tend  to  be  small  and fairly self-explanatory. In particular, if you
       follow the convention of having the top commit name in  .git/HEAD,  you
       can do

       git-cat-file commit HEAD

       to see what the top commit was.

   7) Merging multiple trees
       Git  helps  you  do a three-way merge, which you can expand to n-way by
       repeating  the  merge  procedure  arbitrary  times  until  you  finally
       "commit"  the  state.  The  normal  situation is that you’d only do one
       three-way merge (two parents), and commit it, but if you like  to,  you
       can do multiple parents in one go.

       To do a three-way merge, you need the two sets of "commit" objects that
       you want to merge, use those to find the closest common parent (a third
       "commit"  object),  and then use those commit objects to find the state
       of the directory ("tree" object) at these points.

       To get the "base" for the merge, you first look up the common parent of
       two commits with

       git-merge-base <commit1> <commit2>

       which will return you the commit they are both based on. You should now
       look up the "tree" objects of those commits, which you  can  easily  do
       with (for example)

       git-cat-file commit <commitname> | head -1

       since  the tree object information is always the first line in a commit
       object.

       Once you know  the  three  trees  you  are  going  to  merge  (the  one
       "original"  tree,  aka the common case, and the two "result" trees, aka
       the branches you want to merge), you do a "merge" read into the  index.
       This  will complain if it has to throw away your old index contents, so
       you should make sure that you’ve committed those - in  fact  you  would
       normally  always do a merge against your last commit (which should thus
       match what you have in your current index anyway).

       To do the merge, do

       git-read-tree -m -u <origtree> <yourtree> <targettree>

       which will do all trivial merge operations  for  you  directly  in  the
       index  file, and you can just write the result out with git-write-tree.

       Historical note. We did not have -u  facility  when  this  section  was
       first  written,  so we used to warn that the merge is done in the index
       file, not in your working tree, and your working tree  will  not  match
       your  index after this step. This is no longer true. The above command,
       thanks to -u option, updates your working tree with the  merge  results
       for paths that have been trivially merged.

   8) Merging multiple trees, continued
       Sadly,  many  merges  aren’t trivial. If there are files that have been
       added.moved or removed, or if both  branches  have  modified  the  same
       file, you will be left with an index tree that contains "merge entries"
       in it. Such an index tree can NOT be written out to a tree object,  and
       you  will  have  to  resolve  any  such merge clashes using other tools
       before you can write out the result.

       You can examine such index state with git-ls-files --unmerged  command.
       An example:

              $  git-read-tree -m $orig HEAD $target $ git-ls-files --unmerged
              100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1        hello.c
              100644  06fa6a24256dc7e560efa5687fa84b51f0263c3a 2       hello.c
              100644 cc44c73eb783565da5831b4d820c962954019b69 3       hello.c

              Each line of the git-ls-files --unmerged output begins with  the
              blob  mode  bits, blob SHA1, stage number, and the filename. The
              stage number is git’s way to say which tree it came from:  stage
              1  corresponds  to  $orig  tree,  stage  2 HEAD tree, and stage3
              $target tree.

              Earlier  we  said  that   trivial   merges   are   done   inside
              git-read-tree  -m.  For example, if the file did not change from
              $orig to HEAD nor $target, or if the file changed from $orig  to
              HEAD  and  $orig  to  $target  the same way, obviously the final
              outcome is what is in HEAD. What the above example shows is that
              file hello.c was changed from $orig to HEAD and $orig to $target
              in a different way. You  could  resolve  this  by  running  your
              favorite  3-way  merge program, e.g. diff3 or merge, on the blob
              objects from these three stages yourself, like this:

              $ git-cat-file blob 263414f... >hello.c~1  $  git-cat-file  blob
              06fa6a2...  >hello.c~2 $ git-cat-file blob cc44c73... >hello.c~3
              $ merge hello.c~2 hello.c~1 hello.c~3

              This would leave the merge result in hello.c~2 file, along  with
              conflict  markers  if  there  are conflicts. After verifying the
              merge result makes sense, you can tell git what the final  merge
              result for this file is by:

              mv -f hello.c~2 hello.c
              git-update-index hello.c

              When  a  path is in unmerged state, running git-update-index for
              that path tells git to mark the path resolved.

              The above is the description of a git merge at the lowest level,
              to help you understand what conceptually happens under the hood.
              In  practice,  nobody,  not  even   git   itself,   uses   three
              git-cat-file  for  this.  There  is git-merge-index program that
              extracts the stages to  temporary  files  and  calls  a  "merge"
              script on it:

              git-merge-index git-merge-one-file hello.c

              and that is what higher level git resolve is implemented with.

AUTHORS

       ·  git’s founding father is Linus Torvalds <torvalds@osdl.org>.

       ·  The current git nurse is Junio C Hamano <junkio@cox.net>.

       ·  The git potty was written by Andres Ericsson <ae@op5.se>.

       ·  General upbringing is handled by the git-list <git@vger.kernel.org>.

DOCUMENTATION

       The  documentation  for  git  suite  was  started  by   David   Greaves
       <david@dgreaves.com>, and later enhanced greatly by the contributors on
       the git-list <git@vger.kernel.org>.

GIT

       Part of the git(7) suite

                                                                        GIT(7)