5 GitPython is a python library used to interact with Git repositories.
7 GitPython is a port of the grit_ library in Ruby created by
8 Tom Preston-Werner and Chris Wanstrath.
10 .. _grit: http://grit.rubyforge.org
12 The ``method_missing`` stuff was `taken from this blog post`_.
14 .. _taken from this blog post: http://blog.iffy.us/?p=43
19 * Git_ tested with 1.5.3.7
20 * `Python Nose`_ - used for running the tests
21 * `Mock by Michael Foord`_ used for tests
23 .. _Git: http://git.or.cz/
24 .. _Python Nose: http://code.google.com/p/python-nose/
25 .. _Mock by Michael Foord: http://www.voidspace.org.uk/python/mock.html
30 python setup.py install
35 GitPython's git repo is available on Gitorious, which can be browsed at:
37 http://gitorious.org/projects/git-python/
41 git://gitorious.org/git-python/mainline.git
46 GitPython provides object model access to your git repository. Once you have
47 created a repository object, you can traverse it to find parent commit(s),
50 Initialize a Repo object
51 ************************
53 The first step is to create a ``Repo`` object to represent your repository.
55 >>> from git_python import *
56 >>> repo = Repo("/Users/mtrier/Development/git-python")
58 In the above example, the directory ``/Users/mtrier/Development/git-python``
59 is my working repository and contains the ``.git`` directory. You can also
60 initialize GitPython with a bare repository.
62 >>> repo = Repo.init_bare("/var/git/git-python.git")
64 Getting a list of commits
65 *************************
67 From the ``Repo`` object, you can get a list of ``Commit``
71 [<GitPython.Commit "207c0c4418115df0d30820ab1a9acd2ea4bf4431">,
72 <GitPython.Commit "a91c45eee0b41bf3cdaad3418ca3850664c4a4b4">,
73 <GitPython.Commit "e17c7e11aed9e94d2159e549a99b966912ce1091">,
74 <GitPython.Commit "bd795df2d0e07d10e0298670005c0e9d9a5ed867">]
76 Called without arguments, ``Repo.commits`` returns a list of up to ten commits
77 reachable by the master branch (starting at the latest commit). You can ask
78 for commits beginning at a different branch, commit, tag, etc.
80 >>> repo.commits('mybranch')
81 >>> repo.commits('40d3057d09a7a4d61059bca9dca5ae698de58cbe')
82 >>> repo.commits('v0.1')
84 You can specify the maximum number of commits to return.
86 >>> repo.commits('master', 100)
88 If you need paging, you can specify a number of commits to skip.
90 >>> repo.commits('master', 10, 20)
92 The above will return commits 21-30 from the commit list.
97 Commit objects contain information about a specific commit.
99 >>> head = repo.commits()[0]
102 '207c0c4418115df0d30820ab1a9acd2ea4bf4431'
105 [<GitPython.Commit "a91c45eee0b41bf3cdaad3418ca3850664c4a4b4">]
108 <GitPython.Tree "563413aedbeda425d8d9dcbb744247d0c3e8a0ac">
111 <GitPython.Actor "Michael Trier <mtrier@gmail.com>">
113 >>> head.authored_date
114 (2008, 5, 7, 5, 0, 56, 2, 128, 0)
117 <GitPython.Actor "Michael Trier <mtrier@gmail.com>">
119 >>> head.committed_date
120 (2008, 5, 7, 5, 0, 56, 2, 128, 0)
123 'cleaned up a lot of test information. Fixed escaping so it works with subprocess.'
126 You can traverse a commit's ancestry by chaining calls to ``parents``.
128 >>> repo.commits()[0].parents[0].parents[0].parents[0]
130 The above corresponds to ``master^^^`` or ``master~3`` in git parlance.
135 A tree records pointers to the contents of a directory. Let's say you want
136 the root tree of the latest commit on the master branch.
138 >>> tree = repo.commits()[0].tree
139 <GitPython.Tree "a006b5b1a8115185a228b7514cdcd46fed90dc92">
142 'a006b5b1a8115185a228b7514cdcd46fed90dc92'
144 Once you have a tree, you can get the contents.
146 >>> contents = tree.contents
147 [<GitPython.Blob "6a91a439ea968bf2f5ce8bb1cd8ddf5bf2cad6c7">,
148 <GitPython.Blob "e69de29bb2d1d6434b8b29ae775ad8c2e48c5391">,
149 <GitPython.Tree "eaa0090ec96b054e425603480519e7cf587adfc3">,
150 <GitPython.Blob "980e72ae16b5378009ba5dfd6772b59fe7ccd2df">]
152 This tree contains three ``Blob`` objects and one ``Tree`` object. The trees are
153 subdirectories and the blobs are files. Trees below the root have additional
156 >>> contents = tree.contents[-2]
157 <GitPython.Tree "e5445b9db4a9f08d5b4de4e29e61dffda2f386ba">
165 There is a convenience method that allows you to get a named sub-object
169 <GitPython.Tree "c1c7214dde86f76bc3e18806ac1f47c38b2b7a30">
171 You can also get a tree directly from the repository if you know its name.
174 <GitPython.Tree "master">
176 >>> repo.tree("c1c7214dde86f76bc3e18806ac1f47c38b2b7a30")
177 <GitPython.Tree "c1c7214dde86f76bc3e18806ac1f47c38b2b7a30">
182 A blob represents a file. Trees often contain blobs.
184 >>> blob = tree.contents[-1]
185 <GitPython.Blob "b19574431a073333ea09346eafd64e7b1908ef49">
187 A blob has certain attributes.
201 You can get the data of a blob as a string.
204 "from django.conf.urls.defaults import *\nfrom django.conf..."
206 You can also get a blob directly from the repo if you know its name.
208 >>> repo.blob("b19574431a073333ea09346eafd64e7b1908ef49")
209 <GitPython.Blob "b19574431a073333ea09346eafd64e7b1908ef49">
214 There is more stuff in there, like the ability to tar or gzip repos, stats, 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.
216 Check the unit tests, they're pretty exhaustive.
221 New BSD License. See the LICENSE file.