|
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 |
|
|