Commit 07eaa4c
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -18,6 +18,11 @@ | |||
| 18 | 18 | from tree import Tree | |
| 19 | 19 | ||
| 20 | 20 | class Repo(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 | + """ | ||
| 21 | 26 | DAEMON_EXPORT_FILE = 'git-daemon-export-ok' | |
| 22 | 27 | ||
| 23 | 28 | def __init__(self, path=None): | |
@@ -32,6 +37,9 @@ def __init__(self, path=None): | |||
| 32 | 37 | repo = Repo("/Users/mtrier/Development/git-python") | |
| 33 | 38 | repo = Repo("/Users/mtrier/Development/git-python.git") | |
| 34 | 39 | ||
| 40 | + Raises | ||
| 41 | + InvalidGitRepositoryError or NoSuchPathError | ||
| 42 | + | ||
| 35 | 43 | Returns | |
| 36 | 44 | ``git.Repo`` | |
| 37 | 45 | """ | |
@@ -110,13 +118,15 @@ def commits(self, start='master', path='', max_count=10, skip=0): | |||
| 110 | 118 | is the branch/commit name (default 'master') | |
| 111 | 119 | ||
| 112 | 120 | ``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. | ||
| 114 | 123 | ||
| 115 | 124 | ``max_count`` | |
| 116 | 125 | is the maximum number of commits to return (default 10) | |
| 117 | 126 | ||
| 118 | 127 | ``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. | ||
| 120 | 130 | ||
| 121 | 131 | Returns | |
| 122 | 132 | ``git.Commit[]`` | |
@@ -126,7 +136,7 @@ def commits(self, start='master', path='', max_count=10, skip=0): | |||
| 126 | 136 | ||
| 127 | 137 | return Commit.find_all(self, start, path, **options) | |
| 128 | 138 | ||
| 129 | - def commits_between(self, frm, to, path = ''): | ||
| 139 | + def commits_between(self, frm, to): | ||
| 130 | 140 | """ | |
| 131 | 141 | The Commits objects that are reachable via ``to`` but not via ``frm`` | |
| 132 | 142 | Commits are returned in chronological order. | |
@@ -137,9 +147,6 @@ def commits_between(self, frm, to, path = ''): | |||
| 137 | 147 | ``to`` | |
| 138 | 148 | is the branch/commit name of the older item | |
| 139 | 149 | ||
| 140 | - ``path`` | ||
| 141 | - is an optional path | ||
| 142 | - | ||
| 143 | 150 | Returns | |
| 144 | 151 | ``git.Commit[]`` | |
| 145 | 152 | """ | |
@@ -154,7 +161,8 @@ def commits_since(self, start='master', path='', since='1970-01-01'): | |||
| 154 | 161 | is the branch/commit name (default 'master') | |
| 155 | 162 | ||
| 156 | 163 | ``path`` | |
| 157 | - is an optinal path | ||
| 164 | + is an optinal path to limit the returned commits to. | ||
| 165 | + | ||
| 158 | 166 | ||
| 159 | 167 | ``since`` | |
| 160 | 168 | is a string represeting a date/time | |
@@ -174,10 +182,11 @@ def commit_count(self, start='master', path=''): | |||
| 174 | 182 | is the branch/commit name (default 'master') | |
| 175 | 183 | ||
| 176 | 184 | ``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. | ||
| 178 | 187 | ||
| 179 | 188 | Returns | |
| 180 | - int | ||
| 189 | + ``int`` | ||
| 181 | 190 | """ | |
| 182 | 191 | return Commit.count(self, start, path) | |
| 183 | 192 | ||
@@ -189,25 +198,25 @@ def commit(self, id, path = ''): | |||
| 189 | 198 | is the SHA1 identifier of the commit | |
| 190 | 199 | ||
| 191 | 200 | ``path`` | |
| 192 | - is an optinal path | ||
| 201 | + is an optional path, if set the returned commit must contain the path. | ||
| 193 | 202 | ||
| 194 | 203 | Returns | |
| 195 | - git.Commit | ||
| 204 | + ``git.Commit`` | ||
| 196 | 205 | """ | |
| 197 | 206 | options = {'max_count': 1} | |
| 198 | 207 | ||
| 199 | 208 | commits = Commit.find_all(self, id, path, **options) | |
| 200 | 209 | ||
| 201 | 210 | if not commits: | |
| 202 | - raise ValueError, 'Invalid identifier %s' % id | ||
| 211 | + raise ValueError, "Invalid identifier %s, or given path '%s' too restrictive" % ( id, path ) | ||
| 203 | 212 | return commits[0] | |
| 204 | 213 | ||
| 205 | 214 | def commit_deltas_from(self, other_repo, ref='master', other_ref='master'): | |
| 206 | 215 | """ | |
| 207 | 216 | Returns a list of commits that is in ``other_repo`` but not in self | |
| 208 | 217 | ||
| 209 | 218 | Returns | |
| 210 | - ``git.Commit[]`` | ||
| 219 | + git.Commit[] | ||
| 211 | 220 | """ | |
| 212 | 221 | repo_refs = self.git.rev_list(ref, '--').strip().splitlines() | |
| 213 | 222 | other_repo_refs = other_repo.git.rev_list(other_ref, '--').strip().splitlines() | |
@@ -246,7 +255,11 @@ def blob(self, id): | |||
| 246 | 255 | ||
| 247 | 256 | def log(self, commit='master', path=None, **kwargs): | |
| 248 | 257 | """ | |
| 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 | ||
| 250 | 263 | ||
| 251 | 264 | Returns | |
| 252 | 265 | ``git.Commit[]`` | |
@@ -270,6 +283,9 @@ def diff(self, a, b, *paths): | |||
| 270 | 283 | ||
| 271 | 284 | ``paths`` | |
| 272 | 285 | is an optional list of file paths on which to restrict the diff | |
| 286 | + | ||
| 287 | + Returns | ||
| 288 | + ``str`` | ||
| 273 | 289 | """ | |
| 274 | 290 | return self.git.diff(a, b, '--', *paths) | |
| 275 | 291 | ||
@@ -296,7 +312,7 @@ def init_bare(self, path, mkdir=True, **kwargs): | |||
| 296 | 312 | already exists. Creates the directory with a mode=0755. | |
| 297 | 313 | ||
| 298 | 314 | ``kwargs`` | |
| 299 | - is any additional options to the git init command | ||
| 315 | + keyword arguments serving as additional options to the git init command | ||
| 300 | 316 | ||
| 301 | 317 | Examples:: | |
| 302 | 318 | ||
@@ -321,8 +337,8 @@ def fork_bare(self, path, **kwargs): | |||
| 321 | 337 | ``path`` | |
| 322 | 338 | is the full path of the new repo (traditionally ends with /<name>.git) | |
| 323 | 339 | ||
| 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 | ||
| 326 | 342 | ||
| 327 | 343 | Returns | |
| 328 | 344 | ``git.Repo`` (the newly forked repo) | |
@@ -340,7 +356,7 @@ def archive_tar(self, treeish='master', prefix=None): | |||
| 340 | 356 | is the treeish name/id (default 'master') | |
| 341 | 357 | ||
| 342 | 358 | ``prefix`` | |
| 343 | - is the optional prefix | ||
| 359 | + is the optional prefix to prepend to each filename in the archive | ||
| 344 | 360 | ||
| 345 | 361 | Examples:: | |
| 346 | 362 | ||
@@ -351,10 +367,10 @@ def archive_tar(self, treeish='master', prefix=None): | |||
| 351 | 367 | <String containing tar archive for commit a87ff14> | |
| 352 | 368 | ||
| 353 | 369 | >>> repo.archive_tar('master', 'myproject/') | |
| 354 | - <String containing tar archive and prefixed with 'myproject/'> | ||
| 370 | + <String containing tar bytes archive, whose files are prefixed with 'myproject/'> | ||
| 355 | 371 | ||
| 356 | 372 | Returns | |
| 357 | - str (containing tar archive) | ||
| 373 | + str (containing bytes of tar archive) | ||
| 358 | 374 | """ | |
| 359 | 375 | options = {} | |
| 360 | 376 | if prefix: | |
@@ -369,7 +385,7 @@ def archive_tar_gz(self, treeish='master', prefix=None): | |||
| 369 | 385 | is the treeish name/id (default 'master') | |
| 370 | 386 | ||
| 371 | 387 | ``prefix`` | |
| 372 | - is the optional prefix | ||
| 388 | + is the optional prefix to prepend to each filename in the archive | ||
| 373 | 389 | ||
| 374 | 390 | Examples:: | |
| 375 | 391 | ||
@@ -383,7 +399,7 @@ def archive_tar_gz(self, treeish='master', prefix=None): | |||
| 383 | 399 | <String containing tar.gz archive and prefixed with 'myproject/'> | |
| 384 | 400 | ||
| 385 | 401 | Returns | |
| 386 | - str (containing tar.gz archive) | ||
| 402 | + str (containing the bytes of tar.gz archive) | ||
| 387 | 403 | """ | |
| 388 | 404 | kwargs = {} | |
| 389 | 405 | if prefix: | |
@@ -408,16 +424,16 @@ def _set_daemon_export(self, value): | |||
| 408 | 424 | os.unlink(filename) | |
| 409 | 425 | ||
| 410 | 426 | daemon_export = property(_get_daemon_export, _set_daemon_export, | |
| 411 | - doc="git-daemon export of this repository") | ||
| 427 | + doc="If True, git-daemon may export this repository") | ||
| 412 | 428 | del _get_daemon_export | |
| 413 | 429 | del _set_daemon_export | |
| 414 | 430 | ||
| 415 | 431 | def _get_alternates(self): | |
| 416 | 432 | """ | |
| 417 | - The list of alternates for this repo | ||
| 433 | + The list of alternates for this repo from which objects can be retrieved | ||
| 418 | 434 | ||
| 419 | 435 | Returns | |
| 420 | - list[str] (pathnames of alternates) | ||
| 436 | + list of strings being pathnames of alternates | ||
| 421 | 437 | """ | |
| 422 | 438 | alternates_path = os.path.join(self.path, 'objects', 'info', 'alternates') | |
| 423 | 439 | ||
@@ -436,8 +452,12 @@ def _set_alternates(self, alts): | |||
| 436 | 452 | Sets the alternates | |
| 437 | 453 | ||
| 438 | 454 | ``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 | ||
| 440 | 457 | ||
| 458 | + Raises | ||
| 459 | + NoSuchPathError | ||
| 460 | + | ||
| 441 | 461 | Returns | |
| 442 | 462 | None | |
| 443 | 463 | """ | |
@@ -454,17 +474,19 @@ def _set_alternates(self, alts): | |||
| 454 | 474 | finally: | |
| 455 | 475 | f.close() | |
| 456 | 476 | ||
| 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") | ||
| 458 | 478 | ||
| 459 | 479 | @property | |
| 460 | 480 | def is_dirty(self): | |
| 461 | 481 | """ | |
| 462 | - Return the status of the working directory. | ||
| 482 | + Return the status of the index. | ||
| 463 | 483 | ||
| 464 | 484 | Returns | |
| 465 | - ``True``, if the working directory has any uncommitted changes, | ||
| 485 | + ``True``, if the index has any uncommitted changes, | ||
| 466 | 486 | otherwise ``False`` | |
| 467 | 487 | ||
| 488 | + NOTE | ||
| 489 | + Working tree changes that have not been staged will not be detected ! | ||
| 468 | 490 | """ | |
| 469 | 491 | if self.bare: | |
| 470 | 492 | # Bare repositories with no associated working directory are | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -193,10 +193,10 @@ def test_diff(self, git): | |||
| 193 | 193 | assert_true(git.called) | |
| 194 | 194 | ||
| 195 | 195 | def test_archive_tar(self): | |
| 196 | - self.repo.archive_tar | ||
| 196 | + assert self.repo.archive_tar() | ||
| 197 | 197 | ||
| 198 | 198 | def test_archive_tar_gz(self): | |
| 199 | - self.repo.archive_tar_gz | ||
| 199 | + assert self.repo.archive_tar_gz() | ||
| 200 | 200 | ||
| 201 | 201 | @patch('git.utils.touch') | |
| 202 | 202 | def test_enable_daemon_serve(self, touch): | |
0 commit comments