diff options
| -rw-r--r-- | doc/tutorial.txt | 191 |
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. |