1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
# This module is part of GitPython and is released under the
# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
"""Provides a :class:`~git.refs.reference.Reference`-based type for lightweight tags.
This defines the :class:`TagReference` class (and its alias :class:`Tag`), which
represents lightweight tags. For annotated tags (which are git objects), see the
:mod:`git.objects.tag` module.
"""
__all__ = ["TagReference", "Tag"]
from .reference import Reference
# typing ------------------------------------------------------------------
from typing import Any, TYPE_CHECKING, Type, Union
from git.types import AnyGitObject, PathLike
if TYPE_CHECKING:
from git.objects import Commit, TagObject
from git.refs import SymbolicReference
from git.repo import Repo
# ------------------------------------------------------------------------------
class TagReference(Reference):
"""A lightweight tag reference which either points to a commit, a tag object or any
other object. In the latter case additional information, like the signature or the
tag-creator, is available.
This tag object will always point to a commit object, but may carry additional
information in a tag object::
tagref = TagReference.list_items(repo)[0]
print(tagref.commit.message)
if tagref.tag is not None:
print(tagref.tag.message)
"""
__slots__ = ()
_common_default = "tags"
_common_path_default = Reference._common_path_default + "/" + _common_default
@property
def commit(self) -> "Commit": # type: ignore[override] # LazyMixin has unrelated commit method
""":return: Commit object the tag ref points to
:raise ValueError:
If the tag points to a tree or blob.
"""
obj = self.object
while obj.type != "commit":
if obj.type == "tag":
# It is a tag object which carries the commit as an object - we can point to anything.
obj = obj.object
else:
raise ValueError(
(
"Cannot resolve commit as tag %s points to a %s object - "
+ "use the `.object` property instead to access it"
)
% (self, obj.type)
)
return obj
@property
def tag(self) -> Union["TagObject", None]:
"""
:return:
Tag object this tag ref points to, or ``None`` in case we are a lightweight
tag
"""
obj = self.object
if obj.type == "tag":
return obj
return None
# Make object read-only. It should be reasonably hard to adjust an existing tag.
@property
def object(self) -> AnyGitObject: # type: ignore[override]
return Reference._get_object(self)
@classmethod
def create(
cls: Type["TagReference"],
repo: "Repo",
path: PathLike,
reference: Union[str, "SymbolicReference"] = "HEAD",
logmsg: Union[str, None] = None,
force: bool = False,
**kwargs: Any,
) -> "TagReference":
"""Create a new tag reference.
:param repo:
The :class:`~git.repo.base.Repo` to create the tag in.
:param path:
The name of the tag, e.g. ``1.0`` or ``releases/1.0``.
The prefix ``refs/tags`` is implied.
:param reference:
A reference to the :class:`~git.objects.base.Object` you want to tag.
The referenced object can be a commit, tree, or blob.
:param logmsg:
If not ``None``, the message will be used in your tag object. This will also
create an additional tag object that allows to obtain that information,
e.g.::
tagref.tag.message
:param message:
Synonym for the `logmsg` parameter. Included for backwards compatibility.
`logmsg` takes precedence if both are passed.
:param force:
If ``True``, force creation of a tag even though that tag already exists.
:param kwargs:
Additional keyword arguments to be passed to :manpage:`git-tag(1)`.
:return:
A new :class:`TagReference`.
"""
if "ref" in kwargs and kwargs["ref"]:
reference = kwargs["ref"]
if "message" in kwargs and kwargs["message"]:
kwargs["m"] = kwargs["message"]
del kwargs["message"]
if logmsg:
kwargs["m"] = logmsg
if force:
kwargs["f"] = True
args = (path, reference)
repo.git.tag(*args, **kwargs)
return TagReference(repo, "%s/%s" % (cls._common_path_default, path))
@classmethod
def delete(cls, repo: "Repo", *tags: "TagReference") -> None: # type: ignore[override]
"""Delete the given existing tag or tags."""
repo.git.tag("-d", *tags)
# Provide an alias.
Tag = TagReference
|
