Merge branch 'docs'

7 files changed, 915 insertions, 0 deletions

diff --git a/doc/source/conf.py b/doc/source/conf.py
new file mode 100644
index 00000000..21304eaa
--- /dev/null
+++ b/doc/source/conf.py
@@ -0,0 +1,195 @@
+# -*- coding: utf-8 -*-
+#
+# GitPython documentation build configuration file, created by
+# sphinx-quickstart on Sat Jan 24 11:51:01 2009.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If your extensions are in another directory, add it here. If the directory
+# is relative to the documentation root, use os.path.abspath to make it
+# absolute, like shown here.
+#sys.path.append(os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('../../lib'))
+
+# General configuration
+# ---------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'GitPython'
+copyright = u'Copyright (C) 2008, 2009 Michael Trier and contributors, 2010 Sebastian Thiel'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.3.0'
+# The full version, including alpha/beta/rc tags.
+release = '0.3.0 Beta 1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = ['build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+html_theme_options = {
+    "stickysidebar": "true"
+}
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['.static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+#html_copy_source = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'gitpythondoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+  ('index', 'GitPython.tex', ur'GitPython Documentation',
+   ur'Michael Trier', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
diff --git a/doc/source/index.rst b/doc/source/index.rst
new file mode 100644
index 00000000..6bb8d1fe
--- /dev/null
+++ b/doc/source/index.rst
@@ -0,0 +1,23 @@
+.. GitPython documentation master file, created by sphinx-quickstart on Sat Jan 24 11:51:01 2009.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+GitPython Documentation
+=======================
+
+.. toctree::
+   :maxdepth: 2
+
+   intro
+   whatsnew
+   tutorial
+   reference
+   roadmap
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/doc/source/intro.rst b/doc/source/intro.rst
new file mode 100644
index 00000000..c96766fb
--- /dev/null
+++ b/doc/source/intro.rst
@@ -0,0 +1,112 @@
+.. _intro_toplevel:
+
+==================
+Overview / Install
+==================
+
+GitPython is a python library used to interact with git repositories, high-level like git-porcelain, or low-level like git-plumbing.
+
+It provides abstractions of git objects for easy access of repository data, and additionally allows you to access the git repository more directly using either a pure python implementation, or the faster, but more resource intensive git command implementation.
+
+The object database implementation is optimized for handling large quantities of objects and large datasets, which is achieved by using low-level structures and data streaming.
+
+Requirements
+============
+
+* `Git`_ 1.7.0 or newer
+    It should also work with older versions, but it may be that some operations
+    involving remotes will not work as expected.
+* `GitDB`_ - a pure python git database implementation
+
+ * `async`_ - asynchronous task scheduling
+ 
+* `Python Nose`_ - used for running the tests
+* `Mock by Michael Foord`_ used for tests. Requires version 0.5
+
+.. _Git: http://git-scm.com/
+.. _Python Nose: http://code.google.com/p/python-nose/
+.. _Mock by Michael Foord: http://www.voidspace.org.uk/python/mock.html
+.. _GitDB: http://pypi.python.org/pypi/gitdb
+.. _async: http://pypi.python.org/pypi/async
+
+Installing GitPython
+====================
+
+Installing GitPython is easily done using
+`setuptools`_. Assuming it is
+installed, just run the following from the command-line:
+
+.. sourcecode:: none
+
+    # easy_install GitPython
+
+This command will download the latest version of GitPython from the
+`Python Package Index <http://pypi.python.org/pypi/GitPython>`_ and install it
+to your system. More information about ``easy_install`` and pypi can be found
+here:
+
+* `setuptools`_
+* `install setuptools <http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions>`_
+* `pypi <http://pypi.python.org/pypi/SQLAlchemy>`_
+
+.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
+
+Alternatively, you can install from the distribution using the ``setup.py``
+script:
+
+.. sourcecode:: none
+
+    # python setup.py install
+    
+.. note:: In this case, you have to manually install `GitDB`_ and `async`_ as well. It would be recommended to use the :ref:`git source repository <source-code-label>` in that case.
+
+Getting Started
+===============
+
+* :ref:`tutorial-label` - This tutorial provides a walk-through of some of
+  the basic functionality and concepts used in GitPython. It, however, is not
+  exhaustive so you are encouraged to spend some time in the
+  :ref:`api_reference_toplevel`.
+
+API Reference
+=============
+
+An organized section of the GitPthon API is at :ref:`api_reference_toplevel`.
+
+.. _source-code-label:
+
+Source Code
+===========
+
+GitPython's git repo is available on Gitorious and GitHub, which can be browsed at:
+
+ * http://gitorious.org/projects/git-python/
+ * http://github.com/Byron/GitPython
+
+and cloned using::
+
+	$ git clone git://gitorious.org/git-python/mainline.git git-python
+	$ git clone git://github.com/Byron/GitPython.git git-python
+	
+Initialize all submodules to obtain the required dependencies with::
+    
+    $ cd git-python
+    $ git submodule update --init --recursive
+    
+Finally verify the installation by running the `nose powered <http://code.google.com/p/python-nose/>`_ unit tests::
+    
+    $ nosetests
+    
+Mailing List
+============
+http://groups.google.com/group/git-python
+
+Issue Tracker
+=============
+http://byronimo.lighthouseapp.com/projects/51787-gitpython/milestones
+	
+License Information
+===================
+GitPython is licensed under the New BSD License.  See the LICENSE file for
+more information.
+
diff --git a/doc/source/reference.rst b/doc/source/reference.rst
new file mode 100644
index 00000000..5952fe2d
--- /dev/null
+++ b/doc/source/reference.rst
@@ -0,0 +1,146 @@
+.. _api_reference_toplevel:
+
+API Reference
+=============
+
+Objects.Base
+------------
+
+.. automodule:: git.objects.base
+   :members:
+   :undoc-members:  
+ 
+Objects.Blob
+------------
+
+.. automodule:: git.objects.blob
+   :members:
+   :undoc-members:
+   
+Objects.Commit
+--------------
+
+.. automodule:: git.objects.commit
+   :members:
+   :undoc-members:
+   
+Objects.Tag
+-----------
+
+.. automodule:: git.objects.tag
+   :members:
+   :undoc-members:
+
+Objects.Tree
+------------
+
+.. automodule:: git.objects.tree
+   :members:
+   :undoc-members:
+
+Objects.Functions
+-----------------
+
+.. automodule:: git.objects.fun
+   :members:
+   :undoc-members:
+
+Objects.Submodule
+-----------------
+
+.. automodule:: git.objects.submodule
+   :members:
+   :undoc-members:
+   
+Objects.Util
+-------------
+
+.. automodule:: git.objects.util
+   :members:
+   :undoc-members:
+
+Index.Base
+----------
+
+.. automodule:: git.index.base
+   :members:
+   :undoc-members:
+
+Index.Functions
+---------------
+
+.. automodule:: git.index.fun
+   :members:
+   :undoc-members:
+   
+Index.Types
+-----------
+
+.. automodule:: git.index.typ
+   :members:
+   :undoc-members:
+   
+Index.Util
+-------------
+
+.. automodule:: git.index.util
+   :members:
+   :undoc-members:
+   
+GitCmd
+------
+
+.. automodule:: git.cmd
+   :members:
+   :undoc-members:
+
+
+Config
+------
+
+.. automodule:: git.config
+   :members:
+   :undoc-members:
+   
+Diff
+----
+
+.. automodule:: git.diff
+   :members:
+   :undoc-members:
+
+Errors
+------
+
+.. automodule:: git.errors
+   :members:
+   :undoc-members:
+
+ 
+Refs
+----
+
+.. automodule:: git.refs
+   :members:
+   :undoc-members:
+
+Remote
+------
+
+.. automodule:: git.remote
+   :members:
+   :undoc-members:
+
+Repo
+----
+
+.. automodule:: git.repo
+   :members:
+   :undoc-members:
+
+Util
+----
+
+.. automodule:: git.util
+   :members:
+   :undoc-members:
diff --git a/doc/source/roadmap.rst b/doc/source/roadmap.rst
new file mode 100644
index 00000000..a6bdc3a0
--- /dev/null
+++ b/doc/source/roadmap.rst
@@ -0,0 +1,6 @@
+
+#######
+Roadmap
+#######
+The full list of milestones including associated tasks can be found on lighthouse: http://byronimo.lighthouseapp.com/projects/51787-gitpython/milestones
+
diff --git a/doc/source/tutorial.rst b/doc/source/tutorial.rst
new file mode 100644
index 00000000..033bbad4
--- /dev/null
+++ b/doc/source/tutorial.rst
@@ -0,0 +1,374 @@
+.. _tutorial_toplevel:
+
+.. highlight:: python
+
+.. _tutorial-label:
+
+==================
+GitPython Tutorial
+==================
+
+GitPython provides object model access to your git repository. This tutorial is  composed of multiple sections, each of which explains a real-life usecase.
+
+Initialize a Repo object
+************************
+
+The first step is to create a ``Repo`` object to represent your repository::
+
+    from git import *
+    repo = Repo("/Users/mtrier/Development/git-python")
+    assert repo.bare == False
+
+In the above example, the directory ``/Users/mtrier/Development/git-python`` is my working repository and contains the ``.git`` directory. You can also initialize GitPython with a *bare* repository::
+
+    repo = Repo.create("/var/git/git-python.git")
+    assert repo.bare == True
+    
+A repo object provides high-level access to your data, it allows you to create and delete heads, tags and remotes and access the configuration of the  repository::
+    
+    repo.config_reader()        # get a config reader for read-only access
+    repo.config_writer()        # get a config writer to change configuration 
+
+Query the active branch, query untracked files or whether the repository data  has been modified::
+    
+    repo.is_dirty()
+    False
+    repo.untracked_files()
+    ['my_untracked_file']
+    
+Clone from existing repositories or initialize new empty ones::
+
+    cloned_repo = repo.clone("to/this/path")
+    new_repo = repo.init("path/for/new/repo")
+    
+Archive the repository contents to a tar file::
+
+    repo.archive(open("repo.tar",'w'))
+    
+    
+Object Databases
+****************
+``Repo`` instances are powered by its object database instance which will be used when extracting any data, or when writing new objects.
+
+The type of the database determines certain performance characteristics, such as the quantity of objects that can be read per second, the resource usage when reading large data files, as well as the average memory footprint of your application.
+
+GitDB
+=====
+The GitDB is a pure-python implementation of the git object database. It is the default database to use in GitPython 0.3. Its uses less memory when handling huge files, but will be 2 to 5 times slower when extracting large quantities small of objects from densely packed repositories::
+    
+    repo = Repo("path/to/repo", odbt=GitDB)
+
+GitCmdObjectDB
+==============
+The git command database uses persistent git-cat-file instances to read repository information. These operate very fast under all conditions, but will consume additional memory for the process itself. When extracting large files, memory usage will be much higher than the one of the ``GitDB``::
+    
+    repo = Repo("path/to/repo", odbt=GitCmdObjectDB)
+    
+Examining References
+********************
+
+References are the tips of your commit graph from which you can easily examine  the history of your project::
+
+    heads = repo.heads
+    master = heads.master       # lists can be accessed by name for convenience
+    master.commit               # the commit pointed to by head called master
+    master.rename("new_name")   # rename heads
+    
+Tags are (usually immutable) references to a commit and/or a tag object::
+
+    tags = repo.tags
+    tagref = tags[0]
+    tagref.tag                  # tags may have tag objects carrying additional information
+    tagref.commit               # but they always point to commits
+    repo.delete_tag(tagref)     # delete or
+    repo.create_tag("my_tag")   # create tags using the repo for convenience
+    
+A symbolic reference is a special case of a reference as it points to another reference instead of a commit::
+
+    head = repo.head            # the head points to the active branch/ref
+    master = head.reference     # retrieve the reference the head points to
+    master.commit               # from here you use it as any other reference
+
+Modifying References
+********************
+You can easily create and delete reference types or modify where they point to::
+
+    repo.delete_head('master')           # delete an existing head
+    master = repo.create_head('master')  # create a new one
+    master.commit = 'HEAD~10'            # set branch to another commit without changing index or working tree 
+
+Create or delete tags the same way except you may not change them afterwards::
+
+    new_tag = repo.create_tag('my_tag', 'my message')
+    repo.delete_tag(new_tag)
+    
+Change the symbolic reference to switch branches cheaply ( without adjusting the index or the working copy )::
+
+    new_branch = repo.create_head('new_branch')
+    repo.head.reference = new_branch
+
+Understanding Objects
+*********************
+An Object is anything storable in git's object database. Objects contain information about their type, their uncompressed size as well as the actual data. Each object is uniquely identified by a binary SHA1 hash, being 20 bytes in size.
+
+Git only knows 4 distinct object types being Blobs, Trees, Commits and Tags.
+
+In Git-Python, all objects can be accessed through their common base, compared  and hashed. They are usually not instantiated directly, but through references or specialized repository functions::
+
+    hc = repo.head.commit
+    hct = hc.tree
+    hc != hct
+    hc != repo.tags[0]
+    hc == repo.head.reference.commit
+    
+Common fields are::
+
+    hct.type
+    'tree'
+    hct.size
+    166
+    hct.hexsha
+    'a95eeb2a7082212c197cabbf2539185ec74ed0e8'
+    hct.binsha
+    'binary 20 byte sha1'
+    
+Index Objects are objects that can be put into git's index. These objects are trees, blobs and submodules which additionally know about their path in the filesystem as well as their mode::
+    
+    hct.path            # root tree has no path
+    ''
+    hct.trees[0].path   # the first subdirectory has one though
+    'dir'
+    htc.mode            # trees have the mode of a linux directory
+    040000
+    '%o' % htc.blobs[0].mode    # blobs have a specific mode though comparable to a standard linux fs
+    100644
+    
+Access blob data (or any object data) directly or using streams::
+    
+    htc.blobs[0].data_stream.read()      # stream object to read data from
+    htc.blobs[0].stream_data(open("blob_data", "w")) # write data to given stream
+    
+    
+The Commit object
+*****************
+
+Commit objects contain information about a specific commit. Obtain commits using  references as done in `Examining References`_ or as follows.
+
+Obtain commits at the specified revision::
+
+    repo.commit('master')
+    repo.commit('v0.1')
+    repo.commit('HEAD~10')
+
+Iterate 100 commits::
+
+    repo.iter_commits('master', max_count=100)
+
+If you need paging, you can specify a number of commits to skip::
+
+    repo.iter_commits('master', max_count=10, skip=20)
+
+The above will return commits 21-30 from the commit list.::
+
+    headcommit = repo.head.commit 
+
+    headcommit.hexsha
+    '207c0c4418115df0d30820ab1a9acd2ea4bf4431'
+
+    headcommit.parents
+    (<git.Commit "a91c45eee0b41bf3cdaad3418ca3850664c4a4b4">,)
+
+    headcommit.tree
+    <git.Tree "563413aedbeda425d8d9dcbb744247d0c3e8a0ac">
+
+    headcommit.author
+    <git.Actor "Michael Trier <mtrier@gmail.com>">
+
+    headcommit.authored_date        # seconds since epoch
+    1256291446
+
+    headcommit.committer
+    <git.Actor "Michael Trier <mtrier@gmail.com>">
+
+    headcommit.committed_date
+    1256291446
+
+    headcommit.message
+    'cleaned up a lot of test information. Fixed escaping so it works with
+    subprocess.'
+
+Note: date time is represented in a ``seconds since epoch`` format. Conversion to human readable form can be accomplished with the various `time module <http://docs.python.org/library/time.html>`_ methods::
+
+    import time
+    time.asctime(time.gmtime(headcommit.committed_date))
+    'Wed May 7 05:56:02 2008'
+
+    time.strftime("%a, %d %b %Y %H:%M", time.gmtime(headcommit.committed_date))
+    'Wed, 7 May 2008 05:56'
+
+You can traverse a commit's ancestry by chaining calls to ``parents``::
+
+    headcommit.parents[0].parents[0].parents[0]
+
+The above corresponds to ``master^^^`` or ``master~3`` in git parlance.
+
+The Tree object
+***************
+
+A tree records pointers to the contents of a directory. Let's say you want the root tree of the latest commit on the master branch::
+
+    tree = repo.heads.master.commit.tree
+    <git.Tree "a006b5b1a8115185a228b7514cdcd46fed90dc92">
+
+    tree.hexsha
+    'a006b5b1a8115185a228b7514cdcd46fed90dc92'
+
+Once you have a tree, you can get the contents::
+
+    tree.trees          # trees are subdirectories
+    [<git.Tree "f7eb5df2e465ab621b1db3f5714850d6732cfed2">]
+    
+    tree.blobs          # blobs are files
+    [<git.Blob "a871e79d59cf8488cac4af0c8f990b7a989e2b53">,
+    <git.Blob "3594e94c04db171e2767224db355f514b13715c5">,
+    <git.Blob "e79b05161e4836e5fbf197aeb52515753e8d6ab6">,
+    <git.Blob "94954abda49de8615a048f8d2e64b5de848e27a1">]
+
+Its useful to know that a tree behaves like a list with the ability to  query entries by name::
+
+    tree[0] == tree['dir']			# access by index and by sub-path
+    <git.Tree "f7eb5df2e465ab621b1db3f5714850d6732cfed2">
+    for entry in tree: do_something_with(entry)
+
+    blob = tree[0][0]
+    blob.name
+    'file'
+    blob.path
+    'dir/file'
+    blob.abspath
+    '/Users/mtrier/Development/git-python/dir/file'
+    >>>tree['dir/file'].binsha == blob.binsha
+
+There is a convenience method that allows you to get a named sub-object from a tree with a syntax similar to how paths are written in an unix system::
+
+    tree/"lib"
+    <git.Tree "c1c7214dde86f76bc3e18806ac1f47c38b2b7a30">
+    tree/"dir/file" == blob
+
+You can also get a tree directly from the repository if you know its name::
+
+    repo.tree()
+    <git.Tree "master">
+
+    repo.tree("c1c7214dde86f76bc3e18806ac1f47c38b2b7a30")
+    <git.Tree "c1c7214dde86f76bc3e18806ac1f47c38b2b7a30">
+    repo.tree('0.1.6')
+    <git.Tree "6825a94104164d9f0f5632607bebd2a32a3579e5">
+    
+As trees only allow direct access to their direct entries, use the traverse  method to obtain an iterator to traverse entries recursively::
+
+    tree.traverse()
+    <generator object at 0x7f6598bd65a8>
+    for entry in tree.traverse(): do_something_with(entry)
+
+    
+The Index Object
+****************
+The git index is the stage containing changes to be written with the next commit or where merges finally have to take place. You may freely access and manipulate  this information using the IndexFile Object::
+
+    index = repo.index
+    
+Access objects and add/remove entries. Commit the changes::
+
+    for stage, blob in index.iter_blobs(): do_something(...)
+    # Access blob objects
+    for (path, stage), entry in index.entries.iteritems: pass
+    # Access the entries directly
+    index.add(['my_new_file'])      # add a new file to the index
+    index.remove(['dir/existing_file'])
+    new_commit = index.commit("my commit message")
+    
+Create new indices from other trees or as result of a merge. Write that result to a new index file::
+
+    tmp_index = Index.from_tree(repo, 'HEAD~1') # load a tree into a temporary index
+    merge_index = Index.from_tree(repo, 'base', 'HEAD', 'some_branch') # merge two trees three-way
+    merge_index.write("merged_index")
+    
+Handling Remotes
+****************
+
+Remotes are used as alias for a foreign repository to ease pushing to and fetching from them::
+
+    test_remote = repo.create_remote('test', 'git@server:repo.git')
+    repo.delete_remote(test_remote) # create and delete remotes
+    origin = repo.remotes.origin    # get default remote by name
+    origin.refs                     # local remote references
+    o = origin.rename('new_origin') # rename remotes
+    o.fetch()                       # fetch, pull and push from and to the remote
+    o.pull()
+    o.push()
+
+You can easily access configuration information for a remote by accessing options  as if they where attributes::
+    
+    o.url
+    'git@server:dummy_repo.git'
+    
+Change configuration for a specific remote only::
+    
+    o.config_writer.set("pushurl", "other_url")
+    
+Obtaining Diff Information
+**************************
+
+Diffs can generally be obtained by subclasses of ``Diffable`` as they provide  the ``diff`` method. This operation yields a DiffIndex allowing you to easily access diff information about paths.
+
+Diffs can be made between the Index and Trees, Index and the working tree, trees and trees as well as trees and the working copy. If commits are involved, their tree will be used implicitly::
+
+    hcommit = repo.head.commit
+    idiff = hcommit.diff()          # diff tree against index
+    tdiff = hcommit.diff('HEAD~1')  # diff tree against previous tree
+    wdiff = hcommit.diff(None)      # diff tree against working tree
+    
+    index = repo.index
+    index.diff()                    # diff index against itself yielding empty diff
+    index.diff(None)                # diff index against working copy
+    index.diff('HEAD')              # diff index against current HEAD tree
+
+The item returned is a DiffIndex which is essentially a list of Diff objects. It  provides additional filtering to ease finding what you might be looking for::
+
+    for diff_added in wdiff.iter_change_type('A'): do_something_with(diff_added)
+
+Switching Branches
+******************
+To switch between branches, you effectively need to point your HEAD to the new branch head and reset your index and working copy to match. A simple manual way to do it is the following one::
+
+    repo.head.reference = repo.heads.other_branch
+    repo.head.reset(index=True, working_tree=True)
+    
+The previous approach would brutally overwrite the user's changes in the working copy and index though and is less sophisticated than a git-checkout for instance which generally prevents you from destroying your work. Use the safer approach as follows::
+
+	repo.heads.master.checkout()			# checkout the branch using git-checkout
+	repo.heads.other_branch.checkout()
+
+Using git directly
+******************
+In case you are missing functionality as it has not been wrapped, you may conveniently use the git command directly. It is owned by each repository instance::
+
+    git = repo.git
+    git.checkout('head', b="my_new_branch")         # default command
+    git.for_each_ref()                              # '-' becomes '_' when calling it
+    
+The return value will by default be a string of the standard output channel produced by the command.
+
+Keyword arguments translate to short and long keyword arguments on the commandline.
+The special notion ``git.command(flag=True)`` will create a flag without value like ``command --flag``.
+
+If ``None`` is found in the arguments, it will be dropped silently. Lists and tuples  passed as arguments will be unpacked recursively to individual arguments. Objects are converted to strings using the str(...) function.
+
+And even more ...
+*****************
+
+There is more functionality in there, like the ability to archive repositories, get stats and logs, blame, and probably a few other things that were not mentioned here.  
+
+Check the unit tests for an in-depth introduction on how each function is supposed to be used.
+
diff --git a/doc/source/whatsnew.rst b/doc/source/whatsnew.rst
new file mode 100644
index 00000000..7a5ef53d
--- /dev/null
+++ b/doc/source/whatsnew.rst
@@ -0,0 +1,59 @@
+
+################
+Whats New in 0.3
+################
+GitPython 0.3 is the first step in creating a hybrid which uses a pure python implementations for all simple git features which can be implemented without significant performance penalties. Everything else is still performed using the git command, which is nicely integrated and easy to use.
+
+Its biggest strength, being the support for all git features through the git command itself, is a weakness as well considering the possibly vast amount of times the git command is being started up. Depending on the actual command being performed, the git repository will be initialized on many of these invocations, causing additional overhead for possibly tiny operations.
+
+Keeping as many major operations in the python world will result in improved caching benefits as certain data structures just have to be initialized once and can be reused multiple times. This mode of operation may improve performance when altering the git database on a low level, and is clearly beneficial on operating systems where command invocations are very slow.
+
+****************
+Object Databases
+****************
+An object database provides a simple interface to query object information or to write new object data. Objects are generally identified by their 20 byte binary sha1 value during query.
+
+GitPython uses the ``gitdb`` project to provide a pure-python implementation of the git database, which includes reading and writing loose objects, reading pack files and handling alternate repositories.
+
+The great thing about this is that ``Repo`` objects can use any object database, hence it easily supports different implementations with different performance characteristics. If you are thinking in extremes, you can implement your own database representation, which may be more efficient for what you want to do specifically, like handling big files more efficiently.
+
+************************
+Reduced Memory Footprint
+************************
+Objects, such as commits, tags, trees and blobs now use 20 byte sha1 signatures internally, reducing their memory demands by 20 bytes per object, allowing you to keep more objects in memory at the same time. 
+
+The internal caches of tree objects were improved to use less memory as well.
+
+##################
+Upgrading from 0.2
+##################
+GitPython 0.2 essentially behaves like GitPython 0.3 with a Repository using the ``GitCmdObjectDB`` instead of the ``GitDB`` as object database backend. Additionally it can be used more conveniently through implicit conversions and provides a feature set strikingly similar to 0.3.
+
+**************************
+Why you should not upgrade
+**************************
+GitPython 0.3 in most cases will not run faster than GitPython 0.2, the opposite might be the case at it uses the pure python implementation by default.
+There have been a few renames which will need additional adjustments in your code.
+
+Generally, if you only read git repositories, version 0.2 is sufficient and very well performing.
+
+**********************
+Why you should upgrade
+**********************
+GitPython 0.2 has reached its end of line, and it is unlikely to receive more than contributed patches. 0.3 is the main development branch which will lead into the future.
+
+GitPython 0.3 provides memory usage optimization and is very flexible in the way it uses to access the object database. With minimal effort, 0.3 will be running as fast as 0.2. It marks the first step of more versions to come, and will improve over time. 
+
+GitPython 0.3 is especially suitable for everyone who needs not only read, but also write access to a git repository. It is optimized to keep the memory consumption as low as possible, especially when handling large data sets. GitPython 0.3 operates on streams, not on possibly huge chunks of data.
+
+
+**************
+Guided Upgrade
+**************
+This guide should help to make the upgrade as painless as possible, hence it points out where to start, and what to look out for.
+
+* Have a look at the CHANGES log file and read all important changes about 0.3 for an overview.
+* Start applying the renames, generally the ``utils`` modules are now called ``util``, ``errors`` is called ``exc``.
+* Search for occurrences of the ``sha`` property of object instances. A similar value can be obtained through the new ``hexsha`` property. The native sha1 value is the ``binsha`` though.
+* Search for code which instantiates objects directly. Their initializer now requires a 20 byte binary Sha1, rev-specs cannot be used anymore. For a similar effect, either convert your hexadecimal shas to binary shas beforehand ( ``binascii.unhexlify`` for instance ), or use higher level functions such as ``Object.new``, ``Repo.commit`` or ``Repo.tree``. The latter ones takes rev-specs and hexadecimal sha1 hashes.
+