|
75 | 75 | """ |
76 | 76 |
|
77 | 77 | Tree_ish = Union["Commit", "Tree", "TagObject"] |
78 | | -"""Union of :class:`~git.objects.base.Object`-based types that are sometimes tree-ish. |
| 78 | +"""Union of :class:`~git.objects.base.Object`-based types that are typically tree-ish. |
79 | 79 |
|
80 | 80 | See :manpage:`gitglossary(7)` on "tree-ish": |
81 | 81 | https://git-scm.com/docs/gitglossary#def_tree-ish |
82 | 82 |
|
83 | 83 | :note: |
84 | 84 | :class:`~git.objects.tree.Tree` and :class:`~git.objects.commit.Commit` are the |
85 | 85 | classes whose instances are all tree-ish. This union includes them, but also |
86 | | - :class:`~git.objects.tag.TagObject`, only **some** of whose instances are tree-ish. |
| 86 | + :class:`~git.objects.tag.TagObject`, only **most** of whose instances are tree-ish. |
87 | 87 | Whether a particular :class:`~git.objects.tag.TagObject` peels (recursively |
88 | 88 | dereferences) to a tree or commit, rather than a blob, can in general only be known |
89 | | - at runtime. |
| 89 | + at runtime. In practice, git tag objects are nearly always used for tagging commits, |
| 90 | + and such tags are tree-ish because commits are tree-ish. |
90 | 91 |
|
91 | 92 | :note: |
92 | 93 | See also the :class:`AnyGitObject` union of all four classes corresponding to git |
93 | 94 | object types. |
94 | 95 | """ |
95 | 96 |
|
96 | 97 | Commit_ish = Union["Commit", "TagObject"] |
97 | | -"""Union of :class:`~git.objects.base.Object`-based types that are sometimes commit-ish. |
| 98 | +"""Union of :class:`~git.objects.base.Object`-based types that are typically commit-ish. |
98 | 99 |
|
99 | 100 | See :manpage:`gitglossary(7)` on "commit-ish": |
100 | 101 | https://git-scm.com/docs/gitglossary#def_commit-ish |
101 | 102 |
|
102 | 103 | :note: |
103 | 104 | :class:`~git.objects.commit.Commit` is the only class whose instances are all |
104 | 105 | commit-ish. This union type includes :class:`~git.objects.commit.Commit`, but also |
105 | | - :class:`~git.objects.tag.TagObject`, only **some** of whose instances are |
| 106 | + :class:`~git.objects.tag.TagObject`, only **most** of whose instances are |
106 | 107 | commit-ish. Whether a particular :class:`~git.objects.tag.TagObject` peels |
107 | 108 | (recursively dereferences) to a commit, rather than a tree or blob, can in general |
108 | | - only be known at runtime. |
| 109 | + only be known at runtime. In practice, git tag objects are nearly always used for |
| 110 | + tagging commits, and such tags are of course commit-ish. |
109 | 111 |
|
110 | 112 | :note: |
111 | 113 | See also the :class:`AnyGitObject` union of all four classes corresponding to git |
|
0 commit comments