Commit eba67171bf6ea653dfb6a6ae288f3c1d10829870

forgot to remove the stuff from README.

Signed-off-by: Michael Trier <mtrier@gmail.com>

Commit diff

README

 
4040
4141git://gitorious.org/git-python/mainline.git
4242
43USAGE
44=====
45
46GitPython provides object model access to your git repository. Once you have
47created a repository object, you can traverse it to find parent commit(s),
48trees, blobs, etc.
49
50Initialize a Repo object
51************************
52
53The first step is to create a ``Repo`` object to represent your repository.
54
55 >>> from git import *
56 >>> repo = Repo("/Users/mtrier/Development/git-python")
57
58In the above example, the directory ``/Users/mtrier/Development/git-python``
59is my working repository and contains the ``.git`` directory. You can also
60initialize GitPython with a bare repository.
61
62 >>> repo = Repo.create("/var/git/git-python.git")
63
64Getting a list of commits
65*************************
66
67From the ``Repo`` object, you can get a list of ``Commit``
68objects.
69
70 >>> repo.commits()
71 [<GitPython.Commit "207c0c4418115df0d30820ab1a9acd2ea4bf4431">,
72 <GitPython.Commit "a91c45eee0b41bf3cdaad3418ca3850664c4a4b4">,
73 <GitPython.Commit "e17c7e11aed9e94d2159e549a99b966912ce1091">,
74 <GitPython.Commit "bd795df2d0e07d10e0298670005c0e9d9a5ed867">]
75
76Called without arguments, ``Repo.commits`` returns a list of up to ten commits
77reachable by the master branch (starting at the latest commit). You can ask
78for commits beginning at a different branch, commit, tag, etc.
79
80 >>> repo.commits('mybranch')
81 >>> repo.commits('40d3057d09a7a4d61059bca9dca5ae698de58cbe')
82 >>> repo.commits('v0.1')
83
84You can specify the maximum number of commits to return.
85
86 >>> repo.commits('master', 100)
87
88If you need paging, you can specify a number of commits to skip.
89
90 >>> repo.commits('master', 10, 20)
91
92The above will return commits 21-30 from the commit list.
93
94The Commit object
95*****************
96
97Commit objects contain information about a specific commit.
98
99 >>> head = repo.commits()[0]
100
101 >>> head.id
102 '207c0c4418115df0d30820ab1a9acd2ea4bf4431'
103
104 >>> head.parents
105 [<GitPython.Commit "a91c45eee0b41bf3cdaad3418ca3850664c4a4b4">]
106
107 >>> head.tree
108 <GitPython.Tree "563413aedbeda425d8d9dcbb744247d0c3e8a0ac">
109
110 >>> head.author
111 <GitPython.Actor "Michael Trier <mtrier@gmail.com>">
112
113 >>> head.authored_date
114 (2008, 5, 7, 5, 0, 56, 2, 128, 0)
115
116 >>> head.committer
117 <GitPython.Actor "Michael Trier <mtrier@gmail.com>">
118
119 >>> head.committed_date
120 (2008, 5, 7, 5, 0, 56, 2, 128, 0)
121
122 >>> head.message
123 'cleaned up a lot of test information. Fixed escaping so it works with
124 subprocess.'
125
126Note: date time is represented in a `struct_time`_ format. Conversion to
127human readable form can be accomplished with the various time module methods.
128
129 >>> import time
130 >>> time.asctime(head.committed_date)
131 'Wed May 7 05:56:02 2008'
132
133 >>> time.strftime("%a, %d %b %Y %H:%M", head.committed_date)
134 'Wed, 7 May 2008 05:56'
135
136.. _struct_time: http://docs.python.org/lib/module-time.html
137
138You can traverse a commit's ancestry by chaining calls to ``parents``.
139
140 >>> repo.commits()[0].parents[0].parents[0].parents[0]
141
142The above corresponds to ``master^^^`` or ``master~3`` in git parlance.
143
144The Tree object
145***************
146
147A tree records pointers to the contents of a directory. Let's say you want
148the root tree of the latest commit on the master branch.
149
150 >>> tree = repo.commits()[0].tree
151 <GitPython.Tree "a006b5b1a8115185a228b7514cdcd46fed90dc92">
152
153 >>> tree.id
154 'a006b5b1a8115185a228b7514cdcd46fed90dc92'
155
156Once you have a tree, you can get the contents.
157
158 >>> contents = tree.contents
159 [<GitPython.Blob "6a91a439ea968bf2f5ce8bb1cd8ddf5bf2cad6c7">,
160 <GitPython.Blob "e69de29bb2d1d6434b8b29ae775ad8c2e48c5391">,
161 <GitPython.Tree "eaa0090ec96b054e425603480519e7cf587adfc3">,
162 <GitPython.Blob "980e72ae16b5378009ba5dfd6772b59fe7ccd2df">]
163
164This tree contains three ``Blob`` objects and one ``Tree`` object. The trees
165are subdirectories and the blobs are files. Trees below the root have
166additional attributes.
167
168 >>> contents = tree.contents[-2]
169 <GitPython.Tree "e5445b9db4a9f08d5b4de4e29e61dffda2f386ba">
170
171 >>> contents.name
172 'test'
173
174 >>> contents.mode
175 '040000'
176
177There is a convenience method that allows you to get a named sub-object
178from a tree.
179
180 >>> tree/"lib"
181 <GitPython.Tree "c1c7214dde86f76bc3e18806ac1f47c38b2b7a30">
182
183You can also get a tree directly from the repository if you know its name.
184
185 >>> repo.tree()
186 <GitPython.Tree "master">
187
188 >>> repo.tree("c1c7214dde86f76bc3e18806ac1f47c38b2b7a30")
189 <GitPython.Tree "c1c7214dde86f76bc3e18806ac1f47c38b2b7a30">
190
191The Blob object
192***************
193
194A blob represents a file. Trees often contain blobs.
195
196 >>> blob = tree.contents[-1]
197 <GitPython.Blob "b19574431a073333ea09346eafd64e7b1908ef49">
198
199A blob has certain attributes.
200
201 >>> blob.name
202 'urls.py'
203
204 >>> blob.mode
205 '100644'
206
207 >>> blob.mime_type
208 'text/x-python'
209
210 >>> blob.size
211 415
212
213You can get the data of a blob as a string.
214
215 >>> blob.data
216 "from django.conf.urls.defaults import *\nfrom django.conf..."
217
218You can also get a blob directly from the repo if you know its name.
219
220 >>> repo.blob("b19574431a073333ea09346eafd64e7b1908ef49")
221 <GitPython.Blob "b19574431a073333ea09346eafd64e7b1908ef49">
222
223What Else?
224**********
225
226There is more stuff in there, like the ability to tar or gzip repos, stats,
227log, blame, and probably a few other things. Additionally calls to the git
228instance are handled through a ``method_missing`` construct, which makes
229available any git commands directly, with a nice conversion of Python dicts
230to command line parameters.
231
232Check the unit tests, they're pretty exhaustive.
233
23443LICENSE
23544=======
23645
toggle raw diff