Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit07eaa4c

Browse files
committed
improved repo documentation
1 parent4251bd5 commit07eaa4c

File tree

2 files changed

+53
-31
lines changed

2 files changed

+53
-31
lines changed

‎lib/git/repo.py‎

Lines changed: 51 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,11 @@
1818
fromtreeimportTree
1919

2020
classRepo(object):
21+
"""
22+
Represents a git repository and allows you to query references,
23+
gather commit information, generate diffs, create and clone repositories query
24+
the log.
25+
"""
2126
DAEMON_EXPORT_FILE='git-daemon-export-ok'
2227

2328
def__init__(self,path=None):
@@ -32,6 +37,9 @@ def __init__(self, path=None):
3237
repo = Repo("/Users/mtrier/Development/git-python")
3338
repo = Repo("/Users/mtrier/Development/git-python.git")
3439
40+
Raises
41+
InvalidGitRepositoryError or NoSuchPathError
42+
3543
Returns
3644
``git.Repo``
3745
"""
@@ -110,13 +118,15 @@ def commits(self, start='master', path='', max_count=10, skip=0):
110118
is the branch/commit name (default 'master')
111119
112120
``path``
113-
is an optional path
121+
is an optional path to limit the returned commits to
122+
Commits that do not contain that path will not be returned.
114123
115124
``max_count``
116125
is the maximum number of commits to return (default 10)
117126
118127
``skip``
119-
is the number of commits to skip (default 0)
128+
is the number of commits to skip (default 0) which will effectively
129+
move your commit-window by the given number.
120130
121131
Returns
122132
``git.Commit[]``
@@ -126,7 +136,7 @@ def commits(self, start='master', path='', max_count=10, skip=0):
126136

127137
returnCommit.find_all(self,start,path,**options)
128138

129-
defcommits_between(self,frm,to,path=''):
139+
defcommits_between(self,frm,to):
130140
"""
131141
The Commits objects that are reachable via ``to`` but not via ``frm``
132142
Commits are returned in chronological order.
@@ -137,9 +147,6 @@ def commits_between(self, frm, to, path = ''):
137147
``to``
138148
is the branch/commit name of the older item
139149
140-
``path``
141-
is an optional path
142-
143150
Returns
144151
``git.Commit[]``
145152
"""
@@ -154,7 +161,8 @@ def commits_since(self, start='master', path='', since='1970-01-01'):
154161
is the branch/commit name (default 'master')
155162
156163
``path``
157-
is an optinal path
164+
is an optinal path to limit the returned commits to.
165+
158166
159167
``since``
160168
is a string represeting a date/time
@@ -174,10 +182,11 @@ def commit_count(self, start='master', path=''):
174182
is the branch/commit name (default 'master')
175183
176184
``path``
177-
is an optinal path
185+
is an optional path
186+
Commits that do not contain the path will not contribute to the count.
178187
179188
Returns
180-
int
189+
``int``
181190
"""
182191
returnCommit.count(self,start,path)
183192

@@ -189,25 +198,25 @@ def commit(self, id, path = ''):
189198
is the SHA1 identifier of the commit
190199
191200
``path``
192-
is anoptinal path
201+
is anoptional path, if set the returned commit must contain the path.
193202
194203
Returns
195-
git.Commit
204+
``git.Commit``
196205
"""
197206
options= {'max_count':1}
198207

199208
commits=Commit.find_all(self,id,path,**options)
200209

201210
ifnotcommits:
202-
raiseValueError,'Invalid identifier %s'%id
211+
raiseValueError,"Invalid identifier %s, or given path '%s' too restrictive"% (id,path )
203212
returncommits[0]
204213

205214
defcommit_deltas_from(self,other_repo,ref='master',other_ref='master'):
206215
"""
207216
Returns a list of commits that is in ``other_repo`` but not in self
208217
209218
Returns
210-
``git.Commit[]``
219+
git.Commit[]
211220
"""
212221
repo_refs=self.git.rev_list(ref,'--').strip().splitlines()
213222
other_repo_refs=other_repo.git.rev_list(other_ref,'--').strip().splitlines()
@@ -246,7 +255,11 @@ def blob(self, id):
246255

247256
deflog(self,commit='master',path=None,**kwargs):
248257
"""
249-
The commit log for a treeish
258+
The Commit for a treeish, and all commits leading to it.
259+
260+
``kwargs``
261+
keyword arguments specifying flags to be used in git-log command,
262+
i.e.: max_count=1 to limit the amount of commits returned
250263
251264
Returns
252265
``git.Commit[]``
@@ -270,6 +283,9 @@ def diff(self, a, b, *paths):
270283
271284
``paths``
272285
is an optional list of file paths on which to restrict the diff
286+
287+
Returns
288+
``str``
273289
"""
274290
returnself.git.diff(a,b,'--',*paths)
275291

@@ -296,7 +312,7 @@ def init_bare(self, path, mkdir=True, **kwargs):
296312
already exists. Creates the directory with a mode=0755.
297313
298314
``kwargs``
299-
is any additional options to the git init command
315+
keyword arguments serving as additional options to the git init command
300316
301317
Examples::
302318
@@ -321,8 +337,8 @@ def fork_bare(self, path, **kwargs):
321337
``path``
322338
is the full path of the new repo (traditionally ends with /<name>.git)
323339
324-
``options``
325-
is any additional options to the git clone command
340+
``kwargs``
341+
keyword arguments to be given to the git clone command
326342
327343
Returns
328344
``git.Repo`` (the newly forked repo)
@@ -340,7 +356,7 @@ def archive_tar(self, treeish='master', prefix=None):
340356
is the treeish name/id (default 'master')
341357
342358
``prefix``
343-
is the optional prefix
359+
is the optional prefix to prepend to each filename in the archive
344360
345361
Examples::
346362
@@ -351,10 +367,10 @@ def archive_tar(self, treeish='master', prefix=None):
351367
<String containing tar archive for commit a87ff14>
352368
353369
>>> repo.archive_tar('master', 'myproject/')
354-
<String containing tar archive and prefixed with 'myproject/'>
370+
<String containing tarbytesarchive, whose files are prefixed with 'myproject/'>
355371
356372
Returns
357-
str (containing tar archive)
373+
str (containingbytes oftar archive)
358374
"""
359375
options= {}
360376
ifprefix:
@@ -369,7 +385,7 @@ def archive_tar_gz(self, treeish='master', prefix=None):
369385
is the treeish name/id (default 'master')
370386
371387
``prefix``
372-
is the optional prefix
388+
is the optional prefix to prepend to each filename in the archive
373389
374390
Examples::
375391
@@ -383,7 +399,7 @@ def archive_tar_gz(self, treeish='master', prefix=None):
383399
<String containing tar.gz archive and prefixed with 'myproject/'>
384400
385401
Returns
386-
str (containing tar.gz archive)
402+
str (containingthe bytes oftar.gz archive)
387403
"""
388404
kwargs= {}
389405
ifprefix:
@@ -408,16 +424,16 @@ def _set_daemon_export(self, value):
408424
os.unlink(filename)
409425

410426
daemon_export=property(_get_daemon_export,_set_daemon_export,
411-
doc="git-daemonexport of this repository")
427+
doc="If True,git-daemonmay export this repository")
412428
del_get_daemon_export
413429
del_set_daemon_export
414430

415431
def_get_alternates(self):
416432
"""
417-
The list of alternates for this repo
433+
The list of alternates for this repo from which objects can be retrieved
418434
419435
Returns
420-
list[str] (pathnames of alternates)
436+
list of strings beingpathnames of alternates
421437
"""
422438
alternates_path=os.path.join(self.path,'objects','info','alternates')
423439

@@ -436,8 +452,12 @@ def _set_alternates(self, alts):
436452
Sets the alternates
437453
438454
``alts``
439-
is the Array of String paths representing the alternates
455+
is the array of string paths representing the alternates at which
456+
git should look for objects, i.e. /home/user/repo/.git/objects
440457
458+
Raises
459+
NoSuchPathError
460+
441461
Returns
442462
None
443463
"""
@@ -454,17 +474,19 @@ def _set_alternates(self, alts):
454474
finally:
455475
f.close()
456476

457-
alternates=property(_get_alternates,_set_alternates)
477+
alternates=property(_get_alternates,_set_alternates,doc="Retrieve a list of alternates paths or set a list paths to be used as alternates")
458478

459479
@property
460480
defis_dirty(self):
461481
"""
462-
Return the status of theworking directory.
482+
Return the status of theindex.
463483
464484
Returns
465-
``True``, if theworking directory has any uncommitted changes,
485+
``True``, if theindex has any uncommitted changes,
466486
otherwise ``False``
467487
488+
NOTE
489+
Working tree changes that have not been staged will not be detected !
468490
"""
469491
ifself.bare:
470492
# Bare repositories with no associated working directory are

‎test/git/test_repo.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -193,10 +193,10 @@ def test_diff(self, git):
193193
assert_true(git.called)
194194

195195
deftest_archive_tar(self):
196-
self.repo.archive_tar
196+
assertself.repo.archive_tar()
197197

198198
deftest_archive_tar_gz(self):
199-
self.repo.archive_tar_gz
199+
assertself.repo.archive_tar_gz()
200200

201201
@patch('git.utils.touch')
202202
deftest_enable_daemon_serve(self,touch):

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp