1+ ==========
2+ GitPython
3+ ==========
4+
5+ GitPython is a python library used to interact with Git repositories.
6+
7+ GitPython is a port of the grit_ library in Ruby created by
8+ Tom Preston-Werner and Chris Wanstrath.
9+
10+ .. _grit: http://grit.rubyforge.org
11+
12+ The ``method_missing`` stuff was `taken from this blog post`_
13+
14+ .. _taken from this blog post: http://blog.iffy.us/?p=43
15+
16+ REQUIREMENTS
17+ ============
18+
19+ * Git_ tested with 1.5.3.7
20+ * `Python Nose`_ - used for running the tests
21+
22+ .. _Git: http://git.or.cz/
23+ .. _Python Nose: http://code.google.com/p/python-nose/
24+
25+ INSTALL
26+ =======
27+
28+ python setup.py install
29+
30+ SOURCE
31+ ======
32+
33+ GitPython's git repo is available on Gitorious, which can be browsed at:
34+
35+ http://gitorious.org/projects/git-python
36+
37+ and cloned from:
38+
39+ git://gitorious.org/projects/git-python.git
40+
41+ USAGE
42+ =====
43+
44+ GitPython provides object model access to your git repository. Once you have
45+ created a repository object, you can traverse it to find parent commit(s),
46+ trees, blobs, etc.
47+
48+ Initialize a Repo object
49+ ************************
50+
51+ The first step is to create a `Repo` object to represent your repository.
52+
53+ >>> from git_python import *
54+ >>> repo = Repo.new("/Users/mtrier/Development/git-python")
55+
56+ In the above example, the directory `/Users/mtrier/Development/git-python` is my working
57+ repo and contains the `.git` directory. You can also initialize GitPython with a
58+ bare repo.
59+
60+ >>> repo = Repo.init_bare("/var/git/git-python.git")
61+
62+ Getting a list of commits
63+ *************************
64+
65+ From the `Repo` object, you can get a list of `Commit`
66+ objects.
67+
68+ >>> repo.commits()
69+ [<GitPython.Commit "207c0c4418115df0d30820ab1a9acd2ea4bf4431">,
70+ <GitPython.Commit "a91c45eee0b41bf3cdaad3418ca3850664c4a4b4">,
71+ <GitPython.Commit "e17c7e11aed9e94d2159e549a99b966912ce1091">,
72+ <GitPython.Commit "bd795df2d0e07d10e0298670005c0e9d9a5ed867">]
73+
74+ Called without arguments, `Repo.commits` returns a list of up to ten commits
75+ reachable by the master branch (starting at the latest commit). You can ask
76+ for commits beginning at a different branch, commit, tag, etc.
77+
78+ >>> repo.commits('mybranch')
79+ >>> repo.commits('40d3057d09a7a4d61059bca9dca5ae698de58cbe')
80+ >>> repo.commits('v0.1')
81+
82+ You can specify the maximum number of commits to return.
83+
84+ >>> repo.commits('master', 100)
85+
86+ If you need paging, you can specify a number of commits to skip.
87+
88+ >>> repo.commits('master', 10, 20)
89+
90+ The above will return commits 21-30 from the commit list.
91+
92+ The Commit object
93+ *****************
94+
95+ Commit objects contain information about a specific commit.
96+
97+ >>> head = repo.commits()[0]
98+
99+ >>> head.id
100+ '207c0c4418115df0d30820ab1a9acd2ea4bf4431'
101+
102+ >>> head.parents
103+ [<GitPython.Commit "a91c45eee0b41bf3cdaad3418ca3850664c4a4b4">]
104+
105+ >>> head.tree
106+ <GitPython.Tree "563413aedbeda425d8d9dcbb744247d0c3e8a0ac">
107+
108+ >>> head.author
109+ <GitPython.Actor "Michael Trier <
[email protected] >">
110+
111+ >>> head.authored_date
112+ (2008, 5, 7, 5, 0, 56, 2, 128, 0)
113+
114+ >>> head.committer
115+ <GitPython.Actor "Michael Trier <
[email protected] >">
116+
117+ >>> head.committed_date
118+ (2008, 5, 7, 5, 0, 56, 2, 128, 0)
119+
120+ >>> head.message
121+ 'cleaned up a lot of test information. Fixed escaping so it works with subprocess.'
122+
123+
124+ You can traverse a commit's ancestry by chaining calls to ``parents``.
125+
126+ >>> repo.commits()[0].parents[0].parents[0].parents[0]
127+
128+ The above corresponds to ``master^^^`` or ``master~3`` in git parlance.
129+
130+ The Tree object
131+ ***************
132+
133+ A tree recorda pointers to the contents of a directory. Let's say you want
134+ the root tree of the latest commit on the master branch.
135+
136+ >>> tree = repo.commits()[0].tree
137+ <GitPython.Tree "a006b5b1a8115185a228b7514cdcd46fed90dc92">
138+
139+ >>> tree.id
140+ 'a006b5b1a8115185a228b7514cdcd46fed90dc92'
141+
142+ Once you have a tree, you can get the contents.
143+
144+ >>> contents = tree.contents
145+ [<GitPython.Blob "6a91a439ea968bf2f5ce8bb1cd8ddf5bf2cad6c7">,
146+ <GitPython.Blob "e69de29bb2d1d6434b8b29ae775ad8c2e48c5391">,
147+ <GitPython.Tree "eaa0090ec96b054e425603480519e7cf587adfc3">,
148+ <GitPython.Blob "980e72ae16b5378009ba5dfd6772b59fe7ccd2df">]
149+
150+ This tree contains three ``Blob`` objects and one ``Tree`` object. The trees are
151+ subdirectories and the blobs are files. Trees below the root have additional
152+ attributes.
153+
154+ >>> contents = tree.contents[-2]
155+ <GitPython.Tree "e5445b9db4a9f08d5b4de4e29e61dffda2f386ba">
156+
157+ >>> contents.name
158+ 'test'
159+
160+ >>> contents.mode
161+ '040000'
162+
163+ There is a convenience method that allows you to get a named sub-object
164+ from a tree.
165+
166+ >>> tree/"lib"
167+ <GitPython.Tree "c1c7214dde86f76bc3e18806ac1f47c38b2b7a30">
168+
169+ You can also get a tree directly from the repo if you know its name.
170+
171+ >>> repo.tree()
172+ <GitPython.Tree "master">
173+
174+ >>> repo.tree("c1c7214dde86f76bc3e18806ac1f47c38b2b7a30")
175+ <GitPython.Tree "c1c7214dde86f76bc3e18806ac1f47c38b2b7a30">
176+
177+ The Blob object
178+ ***************
179+
180+ A blob represents a file. Trees often contain blobs.
181+
182+ >>> blob = tree.contents[-1]
183+ <GitPython.Blob "b19574431a073333ea09346eafd64e7b1908ef49">
184+
185+ A blob has certain attributes.
186+
187+ >>> blob.name
188+ 'urls.py'
189+
190+ >>> blob.mode
191+ '100644'
192+
193+ >>> blob.mime_type
194+ 'text/x-python'
195+
196+ >>> len(blob)
197+ 415
198+
199+ You can get the data of a blob as a string.
200+
201+ >>> blob.data
202+ "from django.conf.urls.defaults import *\nfrom django.conf..."
203+
204+ You can also get a blob directly from the repo if you know its name.
205+
206+ >>> repo.blob("b19574431a073333ea09346eafd64e7b1908ef49")
207+ <GitPython.Blob "b19574431a073333ea09346eafd64e7b1908ef49">
208+
209+ LICENSE
210+ =======
211+
212+ New BSD License. See the LICENSE file.
0 commit comments