Commit 787f65c
committed
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -46,6 +46,33 @@ | |||
| 46 | 46 | _T = TypeVar("_T") | |
| 47 | 47 | """Type variable used internally in GitPython.""" | |
| 48 | 48 | ||
| 49 | + AnyGitObject = Union["Commit", "Tree", "TagObject", "Blob"] | ||
| 50 | + """Union of the :class:`~git.objects.base.Object`-based types that represent actual git | ||
| 51 | + object types. | ||
| 52 | + | ||
| 53 | + As noted in :class:`~git.objects.base.Object`, which has further details, these are: | ||
| 54 | + | ||
| 55 | + * :class:`Blob <git.objects.blob.Blob>` | ||
| 56 | + * :class:`Tree <git.objects.tree.Tree>` | ||
| 57 | + * :class:`Commit <git.objects.commit.Commit>` | ||
| 58 | + * :class:`TagObject <git.objects.tag.TagObject>` | ||
| 59 | + | ||
| 60 | + Those GitPython classes represent the four git object types, per gitglossary(7): | ||
| 61 | + | ||
| 62 | + * "blob": https://git-scm.com/docs/gitglossary#def_blob_object | ||
| 63 | + * "tree object": https://git-scm.com/docs/gitglossary#def_tree_object | ||
| 64 | + * "commit object": https://git-scm.com/docs/gitglossary#def_commit_object | ||
| 65 | + * "tag object": https://git-scm.com/docs/gitglossary#def_tag_object | ||
| 66 | + | ||
| 67 | + For more general information on git objects and their types as git understands them: | ||
| 68 | + | ||
| 69 | + * "object": https://git-scm.com/docs/gitglossary#def_object | ||
| 70 | + * "object type": https://git-scm.com/docs/gitglossary#def_object_type | ||
| 71 | + | ||
| 72 | + :note: | ||
| 73 | + See also the :class:`Tree_ish` and :class:`Commit_ish` unions. | ||
| 74 | + """ | ||
| 75 | + | ||
| 49 | 76 | Tree_ish = Union["Commit", "Tree"] | |
| 50 | 77 | """Union of :class:`~git.objects.base.Object`-based types that are inherently tree-ish. | |
| 51 | 78 | ||
@@ -54,13 +81,40 @@ | |||
| 54 | 81 | :note: | |
| 55 | 82 | This union comprises **only** the :class:`~git.objects.commit.Commit` and | |
| 56 | 83 | :class:`~git.objects.tree.Tree` classes, **all** of whose instances are tree-ish. | |
| 57 | - This is done because of the way GitPython uses it as a static type annotation. | ||
| 84 | + This has been done because of the way GitPython uses it as a static type annotation. | ||
| 58 | 85 | ||
| 59 | 86 | :class:`~git.objects.tag.TagObject`, some but not all of whose instances are | |
| 60 | 87 | tree-ish (those representing git tag objects that ultimately resolve to a tree or | |
| 61 | 88 | commit), is not covered as part of this union type. | |
| 89 | + | ||
| 90 | + :note: | ||
| 91 | + See also the :class:`AnyGitObject` union of all four classes corresponding to git | ||
| 92 | + object types. | ||
| 93 | + """ | ||
| 94 | + | ||
| 95 | + Commit_ish = Union["Commit", "TagObject"] | ||
| 96 | + """Union of :class:`~git.objects.base.Object`-based types that are sometimes commit-ish. | ||
| 97 | + | ||
| 98 | + See gitglossary(7) on "commit-ish": https://git-scm.com/docs/gitglossary#def_commit-ish | ||
| 99 | + | ||
| 100 | + :note: | ||
| 101 | + :class:`~git.objects.commit.Commit` is the only class whose instances are all | ||
| 102 | + commit-ish. This union type includes :class:`~git.objects.commit.Commit`, but also | ||
| 103 | + :class:`~git.objects.tag.TagObject`, only **some** of whose instances are | ||
| 104 | + commit-ish. Whether a particular :class:`~git.objects.tag.TagObject` peels | ||
| 105 | + (recursively dereferences) to a commit can in general only be known at runtime. | ||
| 106 | + | ||
| 107 | + :note: | ||
| 108 | + This is an inversion of the situation with :class:`Tree_ish`. This union is broader | ||
| 109 | + than all commit-ish objects, while :class:`Tree_ish` is narrower than all tree-ish | ||
| 110 | + objects. | ||
| 111 | + | ||
| 112 | + :note: | ||
| 113 | + See also the :class:`AnyGitObject` union of all four classes corresponding to git | ||
| 114 | + object types. | ||
| 62 | 115 | """ | |
| 63 | 116 | ||
| 117 | + # FIXME: Replace uses with AnyGitObject and Commit_ish, and remove this. | ||
| 64 | 118 | Old_commit_ish = Union["Commit", "TagObject", "Blob", "Tree"] | |
| 65 | 119 | """Union of the :class:`~git.objects.base.Object`-based types that represent git object | |
| 66 | 120 | types. This union is often usable where a commit-ish is expected, but is not actually | |
0 commit comments