========

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.