From c3bd05b426a0e3dec8224244c3c9c0431d1ff130 Mon Sep 17 00:00:00 2001 From: Sebastian Thiel Date: Thu, 1 Jul 2010 16:35:11 +0200 Subject: Added doc-index, which helps to keep documentation of prior but still somewhat supported versions alive --- doc/doc_index/0.1/_sources/index.txt | 23 ++++ doc/doc_index/0.1/_sources/intro.txt | 83 ++++++++++++ doc/doc_index/0.1/_sources/reference.txt | 95 ++++++++++++++ doc/doc_index/0.1/_sources/tutorial.txt | 211 +++++++++++++++++++++++++++++++ 4 files changed, 412 insertions(+) create mode 100644 doc/doc_index/0.1/_sources/index.txt create mode 100644 doc/doc_index/0.1/_sources/intro.txt create mode 100644 doc/doc_index/0.1/_sources/reference.txt create mode 100644 doc/doc_index/0.1/_sources/tutorial.txt (limited to 'doc/doc_index/0.1/_sources') diff --git a/doc/doc_index/0.1/_sources/index.txt b/doc/doc_index/0.1/_sources/index.txt new file mode 100644 index 00000000..19191272 --- /dev/null +++ b/doc/doc_index/0.1/_sources/index.txt @@ -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 +======================= + +Contents: + +.. toctree:: + :maxdepth: 3 + + intro + tutorial + reference + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/doc_index/0.1/_sources/intro.txt b/doc/doc_index/0.1/_sources/intro.txt new file mode 100644 index 00000000..c99e5a4c --- /dev/null +++ b/doc/doc_index/0.1/_sources/intro.txt @@ -0,0 +1,83 @@ +.. _intro_toplevel: + +================== +Overview / Install +================== + +GitPython is a python library used to interact with Git repositories. + +GitPython is a port of the grit_ library in Ruby created by +Tom Preston-Werner and Chris Wanstrath. + +.. _grit: http://grit.rubyforge.org + +Requirements +============ + +* Git_ tested with 1.5.3.7 +* `Python Nose`_ - used for running the tests +* `Mock by Michael Foord`_ used for tests. Requires 0.5 or higher + +.. _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/ + +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 `_ and install it +to your system. More information about ``easy_install`` and pypi can be found +here: + +* `setuptools`_ +* `install setuptools `_ +* `pypi `_ + +.. _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 + +Getting Started +=============== + +* :ref:`tutorial_toplevel` - 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 +=========== + +GitPython's git repo is available on Gitorious, which can be browsed at: + +http://gitorious.org/git-python + +and cloned from: + +git://gitorious.org/git-python/mainline.git + +License Information +=================== + +GitPython is licensed under the New BSD License. See the LICENSE file for +more information. + diff --git a/doc/doc_index/0.1/_sources/reference.txt b/doc/doc_index/0.1/_sources/reference.txt new file mode 100644 index 00000000..078cbdf6 --- /dev/null +++ b/doc/doc_index/0.1/_sources/reference.txt @@ -0,0 +1,95 @@ +.. _api_reference_toplevel: + +API Reference +============= + +Actor +----- + +.. automodule:: git.actor + :members: + :undoc-members: + +Blob +---- + +.. automodule:: git.blob + :members: + :undoc-members: + +Git +--- + +.. automodule:: git.cmd + :members: + :undoc-members: + +Commit +------ + +.. automodule:: git.commit + :members: + :undoc-members: + +Diff +---- + +.. automodule:: git.diff + :members: + :undoc-members: + +Errors +------ + +.. automodule:: git.errors + :members: + :undoc-members: + +Head +---- + +.. automodule:: git.head + :members: + :undoc-members: + +Lazy +---- + +.. automodule:: git.lazy + :members: + :undoc-members: + +Repo +---- + +.. automodule:: git.repo + :members: + :undoc-members: + +Stats +----- + +.. automodule:: git.stats + :members: + :undoc-members: + +Tag +--- + +.. automodule:: git.tag + :members: + :undoc-members: + +Tree +---- + +.. automodule:: git.tree + :members: + :undoc-members: + +Utils +----- + +.. automodule:: git.utils + :members: + :undoc-members: diff --git a/doc/doc_index/0.1/_sources/tutorial.txt b/doc/doc_index/0.1/_sources/tutorial.txt new file mode 100644 index 00000000..838fd68e --- /dev/null +++ b/doc/doc_index/0.1/_sources/tutorial.txt @@ -0,0 +1,211 @@ +.. _tutorial_toplevel: + +================== +GitPython 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() + [, + , + , + ] + +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', max_count=100) + +If you need paging, you can specify a number of commits to skip. + + >>> repo.commits('master', max_count=10, skip=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 + [] + + >>> head.tree + + + >>> head.author + "> + + >>> head.authored_date + (2008, 5, 7, 5, 0, 56, 2, 128, 0) + + >>> head.committer + "> + + >>> 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/library/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 + + + >>> tree.id + 'a006b5b1a8115185a228b7514cdcd46fed90dc92' + +Once you have a tree, you can get the contents. + + >>> contents = tree.values() + [, + , + , + ] + +The tree is implements a dictionary protocol so it can be used and acts just +like a dictionary with some additional properties. + + >>> tree.items() + [('lib', ), + ('LICENSE', ), + ('doc', ), + ('MANIFEST.in', ), + ('.gitignore', ), + ('test', ), + ('VERSION', ), + ('AUTHORS', ), + ('README', ), + ('ez_setup.py', ), + ('setup.py', ), + ('CHANGES', )] + +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["lib"] + + + >>> contents.name + 'test' + + >>> contents.mode + '040000' + +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" + + +You can also get a tree directly from the repository if you know its name. + + >>> repo.tree() + + + >>> repo.tree("c1c7214dde86f76bc3e18806ac1f47c38b2b7a30") + + +The Blob object +*************** + +A blob represents a file. Trees often contain blobs. + + >>> blob = tree['urls.py'] + + +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") + + +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 ``__getattr__`` 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. -- cgit v1.2.3