Removed tutorial from README and added it into new doc section.

1 files changed, 191 insertions, 0 deletions

diff --git a/doc/tutorial.txt b/doc/tutorial.txt
new file mode 100644
index 00000000..92ed3cdc
--- /dev/null
+++ b/doc/tutorial.txt
@@ -0,0 +1,191 @@
+========
+TUTORIAL
+========
+
+GitPython provides object model access to your git repository. Once you have
+created a repository object, you can traverse it to find parent commit(s),
+trees, blobs, etc.
+
+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")
+  
+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")
+
+Getting a list of commits
+*************************
+
+From the ``Repo`` object, you can get a list of ``Commit``
+objects.
+
+	>>> repo.commits()
+	[<GitPython.Commit "207c0c4418115df0d30820ab1a9acd2ea4bf4431">, 
+	 <GitPython.Commit "a91c45eee0b41bf3cdaad3418ca3850664c4a4b4">, 
+	 <GitPython.Commit "e17c7e11aed9e94d2159e549a99b966912ce1091">, 
+	 <GitPython.Commit "bd795df2d0e07d10e0298670005c0e9d9a5ed867">]
+
+Called without arguments, ``Repo.commits`` returns a list of up to ten commits
+reachable by the master branch (starting at the latest commit). You can ask
+for commits beginning at a different branch, commit, tag, etc.
+
+	>>> repo.commits('mybranch')
+	>>> repo.commits('40d3057d09a7a4d61059bca9dca5ae698de58cbe')
+	>>> repo.commits('v0.1')
+
+You can specify the maximum number of commits to return.
+
+	>>> repo.commits('master', 100)
+  
+If you need paging, you can specify a number of commits to skip.
+
+	>>> repo.commits('master', 10, 20)
+
+The above will return commits 21-30 from the commit list.
+        
+The Commit object
+*****************
+
+Commit objects contain information about a specific commit.
+
+	>>> head = repo.commits()[0]
+
+	>>> head.id
+	'207c0c4418115df0d30820ab1a9acd2ea4bf4431'
+
+	>>> head.parents
+	[<GitPython.Commit "a91c45eee0b41bf3cdaad3418ca3850664c4a4b4">]
+	
+	>>> head.tree
+	<GitPython.Tree "563413aedbeda425d8d9dcbb744247d0c3e8a0ac">
+	
+	>>> head.author
+	<GitPython.Actor "Michael Trier <mtrier@gmail.com>">
+	
+	>>> head.authored_date
+	(2008, 5, 7, 5, 0, 56, 2, 128, 0)
+	
+	>>> head.committer
+	<GitPython.Actor "Michael Trier <mtrier@gmail.com>">
+	
+	>>> head.committed_date
+	(2008, 5, 7, 5, 0, 56, 2, 128, 0)
+	
+	>>> head.message
+	'cleaned up a lot of test information. Fixed escaping so it works with 
+	subprocess.'
+
+Note: date time is represented in a `struct_time`_ format.  Conversion to
+human readable form can be accomplished with the various time module methods.
+
+	>>> import time
+	>>> time.asctime(head.committed_date)
+	'Wed May 7 05:56:02 2008'
+
+	>>> time.strftime("%a, %d %b %Y %H:%M", head.committed_date)
+	'Wed, 7 May 2008 05:56'
+
+.. _struct_time: http://docs.python.org/lib/module-time.html
+
+You can traverse a commit's ancestry by chaining calls to ``parents``.
+
+	>>> repo.commits()[0].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.commits()[0].tree
+	<GitPython.Tree "a006b5b1a8115185a228b7514cdcd46fed90dc92">
+
+	>>> tree.id
+	'a006b5b1a8115185a228b7514cdcd46fed90dc92'
+  
+Once you have a tree, you can get the contents.
+
+	>>> contents = tree.contents
+	[<GitPython.Blob "6a91a439ea968bf2f5ce8bb1cd8ddf5bf2cad6c7">, 
+	 <GitPython.Blob "e69de29bb2d1d6434b8b29ae775ad8c2e48c5391">, 
+	 <GitPython.Tree "eaa0090ec96b054e425603480519e7cf587adfc3">, 
+	 <GitPython.Blob "980e72ae16b5378009ba5dfd6772b59fe7ccd2df">]
+
+This tree contains three ``Blob`` objects and one ``Tree`` object. The trees 
+are subdirectories and the blobs are files. Trees below the root have 
+additional attributes.
+
+	>>> contents = tree.contents[-2]
+	<GitPython.Tree "e5445b9db4a9f08d5b4de4e29e61dffda2f386ba">
+	
+	>>> contents.name
+	'test'
+	
+	>>> contents.mode
+	'040000'
+	
+There is a convenience method that allows you to get a named sub-object
+from a tree.
+
+	>>> tree/"lib"
+	<GitPython.Tree "c1c7214dde86f76bc3e18806ac1f47c38b2b7a30">
+  
+You can also get a tree directly from the repository if you know its name.
+
+	>>> repo.tree()
+	<GitPython.Tree "master">
+	
+	>>> repo.tree("c1c7214dde86f76bc3e18806ac1f47c38b2b7a30")
+	<GitPython.Tree "c1c7214dde86f76bc3e18806ac1f47c38b2b7a30">
+
+The Blob object
+***************
+
+A blob represents a file. Trees often contain blobs.
+
+	>>> blob = tree.contents[-1]
+	<GitPython.Blob "b19574431a073333ea09346eafd64e7b1908ef49">
+
+A blob has certain attributes.
+
+	>>> blob.name
+	'urls.py'
+	
+	>>> blob.mode
+	'100644'
+
+	>>> blob.mime_type
+	'text/x-python'
+	
+	>>> blob.size
+	415
+  
+You can get the data of a blob as a string.
+
+	>>> blob.data
+	"from django.conf.urls.defaults import *\nfrom django.conf..."
+
+You can also get a blob directly from the repo if you know its name.
+
+	>>> repo.blob("b19574431a073333ea09346eafd64e7b1908ef49")
+	<GitPython.Blob "b19574431a073333ea09346eafd64e7b1908ef49">
+
+What Else?
+**********
+
+There is more stuff in there, like the ability to tar or gzip repos, stats, 
+log, blame, and probably a few other things.  Additionally calls to the git 
+instance are handled through a ``method_missing`` construct, which makes 
+available any git commands directly, with a nice conversion of Python dicts 
+to command line parameters.
+
+Check the unit tests, they're pretty exhaustive.