From 838eb923751aad3063a47ef24c0b806e9c4e2453 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Tue, 19 Mar 2024 13:22:46 -0400 Subject: [PATCH] Clarify how tag objects are usually tree-ish and commit-ish 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 #1878, starting at: https://github.com/gitpython-developers/GitPython/pull/1878#pullrequestreview-1938343498 --- git/types.py | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/git/types.py b/git/types.py index 230422dff..a93ebdb4f 100644 --- a/git/types.py +++ b/git/types.py @@ -75,7 +75,7 @@ """ 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 @@ -83,10 +83,11 @@ :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 @@ -94,7 +95,7 @@ """ 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 @@ -102,10 +103,11 @@ :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 pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.

Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy