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

Commited6ead9

Browse files
committed
Correct and clarify Diffable.diff docstring
Incd16a35 (#1725), I had taken "Treeish" to mean the type of thatexact name, git.index.base.Treeish. But that type is only usedwithin the git.index package (actually only in git.index.baseitself). It is also nonpublic: git.index.base.__all__ exists anddoes not list it.So most likely this was not intended in the git.diff.Diffable.diffdocstring. Even if intended, it does not appear accurate, since thegit.index.base.Treeish union includes bytes, and the logic inDiffable.diff and its helpers does not appear to accommodate bytes.A closer type is the public git.types.Tree_ish union, which isnarrower than git.index.base.Treeish, including neither str norbytes. However, it does not include str, and Diffable.diff doesaccept str to specify a tree-ish for diff-ing. It may be that"Treeish" in the pre-#1725 docstring was capitalized for somereason other than to identify a type defined in GitPython's code.For now, I've changed it to refer to git.types.Tree_ish, but alsoexplicitly documented that a string can be used to specify atree-ish -- which is independently valuable, since previously theeffect of passing a str instance to the diff method was not statedanywhere in the method docstring. To clarify further, I included alink to tree-ish in gitglossary(7) as well.In addition, the original wording beforecd16a35 had included"(type)", which I had erroneously assumed was just meant to statethat it is a type (i.e. a class), so I had wrongly removed itwithout replacing it with anything when making it into a referenceto a type. But it was really an attempt to clarify thatDiffable.Index should be used directly, rather than an instance ofit. That is in effect the opposite of merely pointing out that itis a class; it is to express that it should be used in a way thatdoes not depend in any way on it being a class. This commit has thedocstring explicitly state that.
1 parent1cdec7a commited6ead9

File tree

1 file changed

+16
-7
lines changed

1 file changed

+16
-7
lines changed

‎git/diff.py

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -122,12 +122,21 @@ def diff(
122122
This the item to compare us with.
123123
124124
* If ``None``, we will be compared to the working tree.
125-
* If :class:`~git.index.base.Treeish`, it will be compared against the
126-
respective tree.
127-
* If :class:`Diffable.Index`, it will be compared against the index.
128-
* If :attr:`git.NULL_TREE`, it will compare against the empty tree.
129-
* It defaults to :class:`Diffable.Index` so that the method will not by
130-
default fail on bare repositories.
125+
126+
* If :class:`~git.types.Tree_ish`, it will be compared against the
127+
respective tree. (See https://git-scm.com/docs/gitglossary#def_tree-ish.)
128+
This can also be passed as a string.
129+
130+
* If :class:`Diffable.Index`, it will be compared against the index. Use the
131+
type object :class:`Index` itself, without attempting to instantiate it.
132+
(That is, you should treat :class:`Index` as an opqaue constant. Don't
133+
rely on it being a class or even callable.)
134+
135+
* If :attr:`git.NULL_TREE <NULL_TREE>`, it will compare against the empty
136+
tree.
137+
138+
This parameter defaults to :class:`Diffable.Index` (rather than ``None``) so
139+
that the method will not by default fail on bare repositories.
131140
132141
:param paths:
133142
This a list of paths or a single path to limit the diff to. It will only
@@ -143,7 +152,7 @@ def diff(
143152
sides of the diff.
144153
145154
:return:
146-
:class:`DiffIndex`
155+
A:class:`DiffIndex` representing the computed diff.
147156
148157
:note:
149158
On a bare repository, `other` needs to be provided as

0 commit comments

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