Skip to content

Commit

Permalink
Clarify how tag objects are usually tree-ish and commit-ish
Browse files Browse the repository at this point in the history
This revises the docstrings of the Tree_ish and Commit_ish unions,
to make clearer that tags objects are usually used to identify
commits and are thus usually tree-ish and commit-ish.

This change relates to the discussion in gitpython-developers#1878, starting at:
gitpython-developers#1878 (review)
  • Loading branch information
EliahKagan committed Mar 19, 2024
1 parent 4fb6d24 commit 838eb92
Showing 1 changed file with 8 additions and 6 deletions.
14 changes: 8 additions & 6 deletions git/types.py
Original file line number Diff line number Diff line change
Expand Up @@ -75,37 +75,39 @@
"""

Tree_ish = Union["Commit", "Tree", "TagObject"]
"""Union of :class:`~git.objects.base.Object`-based types that are sometimes tree-ish.
"""Union of :class:`~git.objects.base.Object`-based types that are typically tree-ish.
See :manpage:`gitglossary(7)` on "tree-ish":
https://git-scm.com/docs/gitglossary#def_tree-ish
:note:
:class:`~git.objects.tree.Tree` and :class:`~git.objects.commit.Commit` are the
classes whose instances are all tree-ish. This union includes them, but also
:class:`~git.objects.tag.TagObject`, only **some** of whose instances are tree-ish.
:class:`~git.objects.tag.TagObject`, only **most** of whose instances are tree-ish.
Whether a particular :class:`~git.objects.tag.TagObject` peels (recursively
dereferences) to a tree or commit, rather than a blob, can in general only be known
at runtime.
at runtime. In practice, git tag objects are nearly always used for tagging commits,
and such tags are tree-ish because commits are tree-ish.
:note:
See also the :class:`AnyGitObject` union of all four classes corresponding to git
object types.
"""

Commit_ish = Union["Commit", "TagObject"]
"""Union of :class:`~git.objects.base.Object`-based types that are sometimes commit-ish.
"""Union of :class:`~git.objects.base.Object`-based types that are typically commit-ish.
See :manpage:`gitglossary(7)` on "commit-ish":
https://git-scm.com/docs/gitglossary#def_commit-ish
:note:
:class:`~git.objects.commit.Commit` is the only class whose instances are all
commit-ish. This union type includes :class:`~git.objects.commit.Commit`, but also
:class:`~git.objects.tag.TagObject`, only **some** of whose instances are
:class:`~git.objects.tag.TagObject`, only **most** of whose instances are
commit-ish. Whether a particular :class:`~git.objects.tag.TagObject` peels
(recursively dereferences) to a commit, rather than a tree or blob, can in general
only be known at runtime.
only be known at runtime. In practice, git tag objects are nearly always used for
tagging commits, and such tags are of course commit-ish.
:note:
See also the :class:`AnyGitObject` union of all four classes corresponding to git
Expand Down

0 comments on commit 838eb92

Please sign in to comment.