Repository navigation
Commit 3bd8177
committed
Document Tree_ish, Commit_ish, and related types
The Commit_ish docstring may require substantive revision. The
follow claims about the reasion for the design of Commit_ish should
be checked, and if false removed or fixed, and if true then
possibly clarified or otherwise refined:
- "often usable where a commit-ish is expected" (both as for
whether it is a reasonable generalization and for whether it is
actually part of the reason Commit_ish includes Blob and Tree)
- "It is done for practical reasons including backward
compatibility." (for whether that is why it was done is or kept)1 parent 9e47083 commit 3bd8177
1 file changed
Lines changed: 50 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -53,8 +53,58 @@ | |||
| 53 | 53 | _T = TypeVar("_T") | |
| 54 | 54 | ||
| 55 | 55 | Tree_ish = Union["Commit", "Tree"] | |
| 56 | + """Union of :class:`~git.objects.base.Object`-based types that are inherently tree-ish. | ||
| 57 | + | ||
| 58 | + See gitglossary(7) on "tree-ish": https://git-scm.com/docs/gitglossary#def_tree-ish | ||
| 59 | + | ||
| 60 | + :note: | ||
| 61 | + This union comprises **only** the :class:`~git.objects.commit.Commit` and | ||
| 62 | + :class:`~git.objects.tree.Tree` classes, **all** of whose instances are tree-ish. | ||
| 63 | + This is done because of the way GitPython uses it as a static type annotation. | ||
| 64 | + | ||
| 65 | + :class:`~git.objects.tag.TagObject`, some but not all of whose instances are | ||
| 66 | + tree-ish (those representing git tag objects that ultimately resolve to a tree or | ||
| 67 | + commit), is not covered as part of this union type. | ||
| 68 | + """ | ||
| 69 | + | ||
| 56 | 70 | Commit_ish = Union["Commit", "TagObject", "Blob", "Tree"] | |
| 71 | + """Union of the :class:`~git.objects.base.Object`-based types that represent kinds of | ||
| 72 | + git objects. This union is often usable where a commit-ish is expected, but is not | ||
| 73 | + actually limited to types representing commit-ish git objects. | ||
| 74 | + | ||
| 75 | + See gitglossary(7) on: | ||
| 76 | + | ||
| 77 | + * "commit-ish": https://git-scm.com/docs/gitglossary#def_commit-ish | ||
| 78 | + * "object type": https://git-scm.com/docs/gitglossary#def_object_type | ||
| 79 | + | ||
| 80 | + :note: | ||
| 81 | + This union comprises **more** classes than those whose instances really represent | ||
| 82 | + commit-ish git objects: | ||
| 83 | + | ||
| 84 | + * A :class:`~git.objects.commit.Commit` is of course always | ||
| 85 | + commit-ish, and a :class:`~git.objects.tag.TagObject` is commit-ish if, when | ||
| 86 | + peeled (recursively followed), a :class:`~git.objects.commit.Commit` is obtained. | ||
| 87 | + * However, :class:`~git.objects.blob.Blob` and :class:`~git.objects.tree.Tree` are | ||
| 88 | + also included, and they represent git objects that are never really commit-ish. | ||
| 89 | + | ||
| 90 | + This is an inversion of the situation with :class:`Tree_ish`, which is narrower than | ||
| 91 | + all tree-ish objects. It is done for practical reasons including backward | ||
| 92 | + compatibility. | ||
| 93 | + """ | ||
| 94 | + | ||
| 57 | 95 | Lit_commit_ish = Literal["commit", "tag", "blob", "tree"] | |
| 96 | + """Literal strings identifying concrete :class:`~git.objects.base.Object` subtypes. | ||
| 97 | + | ||
| 98 | + See :class:`Object.type <git.objects.base.Object.type>`. | ||
| 99 | + | ||
| 100 | + :note: | ||
| 101 | + See also :class:`Commit_ish`, a union of the the :class:`~git.objects.base.Object` | ||
| 102 | + subtypes associated with these literal strings. | ||
| 103 | + | ||
| 104 | + :note: | ||
| 105 | + As noted in :class:`Commit_ish`, this is not limited to types of git objects that | ||
| 106 | + are actually commit-ish. | ||
| 107 | + """ | ||
| 58 | 108 | ||
| 59 | 109 | # Config_levels --------------------------------------------------------- | |
| 60 | 110 | ||
0 commit comments