Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/dulwich/objects.py: 46%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# objects.py -- Access to base git objects
2# Copyright (C) 2007 James Westby <jw+debian@jameswestby.net>
3# Copyright (C) 2008-2013 Jelmer Vernooij <jelmer@jelmer.uk>
4#
5# SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
6# Dulwich is dual-licensed under the Apache License, Version 2.0 and the GNU
7# General Public License as published by the Free Software Foundation; version 2.0
8# or (at your option) any later version. You can redistribute it and/or
9# modify it under the terms of either of these two licenses.
10#
11# Unless required by applicable law or agreed to in writing, software
12# distributed under the License is distributed on an "AS IS" BASIS,
13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14# See the License for the specific language governing permissions and
15# limitations under the License.
16#
17# You should have received a copy of the licenses; if not, see
18# <http://www.gnu.org/licenses/> for a copy of the GNU General Public License
19# and <http://www.apache.org/licenses/LICENSE-2.0> for a copy of the Apache
20# License, Version 2.0.
21#
23"""Access to base git objects."""
25import binascii
26import os
27import posixpath
28import stat
29import sys
30import zlib
31from collections.abc import Callable, Iterable, Iterator
32from hashlib import sha1
33from io import BufferedIOBase, BytesIO
34from typing import (
35 IO,
36 TYPE_CHECKING,
37 NamedTuple,
38 Optional,
39 Union,
40)
42if sys.version_info >= (3, 11):
43 from typing import Self
44else:
45 from typing_extensions import Self
47if sys.version_info >= (3, 10):
48 from typing import TypeGuard
49else:
50 from typing_extensions import TypeGuard
52from . import replace_me
53from .errors import (
54 ChecksumMismatch,
55 FileFormatException,
56 NotBlobError,
57 NotCommitError,
58 NotTagError,
59 NotTreeError,
60 ObjectFormatException,
61)
62from .file import GitFile
64if TYPE_CHECKING:
65 from _hashlib import HASH
67 from .file import _GitFile
69ZERO_SHA = b"0" * 40
71# Header fields for commits
72_TREE_HEADER = b"tree"
73_PARENT_HEADER = b"parent"
74_AUTHOR_HEADER = b"author"
75_COMMITTER_HEADER = b"committer"
76_ENCODING_HEADER = b"encoding"
77_MERGETAG_HEADER = b"mergetag"
78_GPGSIG_HEADER = b"gpgsig"
80# Header fields for objects
81_OBJECT_HEADER = b"object"
82_TYPE_HEADER = b"type"
83_TAG_HEADER = b"tag"
84_TAGGER_HEADER = b"tagger"
87S_IFGITLINK = 0o160000
90MAX_TIME = 9223372036854775807 # (2**63) - 1 - signed long int max
92BEGIN_PGP_SIGNATURE = b"-----BEGIN PGP SIGNATURE-----"
95ObjectID = bytes
98class EmptyFileException(FileFormatException):
99 """An unexpectedly empty file was encountered."""
102def S_ISGITLINK(m: int) -> bool:
103 """Check if a mode indicates a submodule.
105 Args:
106 m: Mode to check
107 Returns: a ``boolean``
108 """
109 return stat.S_IFMT(m) == S_IFGITLINK
112def _decompress(string: bytes) -> bytes:
113 dcomp = zlib.decompressobj()
114 dcomped = dcomp.decompress(string)
115 dcomped += dcomp.flush()
116 return dcomped
119def sha_to_hex(sha: ObjectID) -> bytes:
120 """Takes a string and returns the hex of the sha within."""
121 hexsha = binascii.hexlify(sha)
122 assert len(hexsha) == 40, f"Incorrect length of sha1 string: {hexsha!r}"
123 return hexsha
126def hex_to_sha(hex: Union[bytes, str]) -> bytes:
127 """Takes a hex sha and returns a binary sha."""
128 assert len(hex) == 40, f"Incorrect length of hexsha: {hex!r}"
129 try:
130 return binascii.unhexlify(hex)
131 except TypeError as exc:
132 if not isinstance(hex, bytes):
133 raise
134 raise ValueError(exc.args[0]) from exc
137def valid_hexsha(hex: Union[bytes, str]) -> bool:
138 """Check if a string is a valid hex SHA.
140 Args:
141 hex: Hex string to check
143 Returns:
144 True if valid hex SHA, False otherwise
145 """
146 if len(hex) != 40:
147 return False
148 try:
149 binascii.unhexlify(hex)
150 except (TypeError, binascii.Error):
151 return False
152 else:
153 return True
156def hex_to_filename(
157 path: Union[str, bytes], hex: Union[str, bytes]
158) -> Union[str, bytes]:
159 """Takes a hex sha and returns its filename relative to the given path."""
160 # os.path.join accepts bytes or unicode, but all args must be of the same
161 # type. Make sure that hex which is expected to be bytes, is the same type
162 # as path.
163 if type(path) is not type(hex) and isinstance(path, str):
164 hex = hex.decode("ascii") # type: ignore
165 dir_name = hex[:2]
166 file_name = hex[2:]
167 # Check from object dir
168 return os.path.join(path, dir_name, file_name) # type: ignore
171def filename_to_hex(filename: Union[str, bytes]) -> str:
172 """Takes an object filename and returns its corresponding hex sha."""
173 # grab the last (up to) two path components
174 names = filename.rsplit(os.path.sep, 2)[-2:] # type: ignore
175 errmsg = f"Invalid object filename: {filename!r}"
176 assert len(names) == 2, errmsg
177 base, rest = names
178 assert len(base) == 2 and len(rest) == 38, errmsg
179 hex_bytes = (base + rest).encode("ascii") # type: ignore
180 hex_to_sha(hex_bytes)
181 return hex_bytes.decode("ascii")
184def object_header(num_type: int, length: int) -> bytes:
185 """Return an object header for the given numeric type and text length."""
186 cls = object_class(num_type)
187 if cls is None:
188 raise AssertionError(f"unsupported class type num: {num_type}")
189 return cls.type_name + b" " + str(length).encode("ascii") + b"\0"
192def serializable_property(name: str, docstring: Optional[str] = None) -> property:
193 """A property that helps tracking whether serialization is necessary."""
195 def set(obj: "ShaFile", value: object) -> None:
196 """Set the property value and mark the object as needing serialization.
198 Args:
199 obj: The ShaFile object
200 value: The value to set
201 """
202 setattr(obj, "_" + name, value)
203 obj._needs_serialization = True
205 def get(obj: "ShaFile") -> object:
206 """Get the property value.
208 Args:
209 obj: The ShaFile object
211 Returns:
212 The property value
213 """
214 return getattr(obj, "_" + name)
216 return property(get, set, doc=docstring)
219def object_class(type: Union[bytes, int]) -> Optional[type["ShaFile"]]:
220 """Get the object class corresponding to the given type.
222 Args:
223 type: Either a type name string or a numeric type.
224 Returns: The ShaFile subclass corresponding to the given type, or None if
225 type is not a valid type name/number.
226 """
227 return _TYPE_MAP.get(type, None)
230def check_hexsha(hex: Union[str, bytes], error_msg: str) -> None:
231 """Check if a string is a valid hex sha string.
233 Args:
234 hex: Hex string to check
235 error_msg: Error message to use in exception
236 Raises:
237 ObjectFormatException: Raised when the string is not valid
238 """
239 if not valid_hexsha(hex):
240 raise ObjectFormatException(f"{error_msg} {hex!r}")
243def check_identity(identity: Optional[bytes], error_msg: str) -> None:
244 """Check if the specified identity is valid.
246 This will raise an exception if the identity is not valid.
248 Args:
249 identity: Identity string
250 error_msg: Error message to use in exception
251 """
252 if identity is None:
253 raise ObjectFormatException(error_msg)
254 email_start = identity.find(b"<")
255 email_end = identity.find(b">")
256 if not all(
257 [
258 email_start >= 1,
259 identity[email_start - 1] == b" "[0],
260 identity.find(b"<", email_start + 1) == -1,
261 email_end == len(identity) - 1,
262 b"\0" not in identity,
263 b"\n" not in identity,
264 ]
265 ):
266 raise ObjectFormatException(error_msg)
269def _path_to_bytes(path: Union[str, bytes]) -> bytes:
270 """Convert a path to bytes for use in error messages."""
271 if isinstance(path, str):
272 return path.encode("utf-8", "surrogateescape")
273 return path
276def check_time(time_seconds: int) -> None:
277 """Check if the specified time is not prone to overflow error.
279 This will raise an exception if the time is not valid.
281 Args:
282 time_seconds: time in seconds
284 """
285 # Prevent overflow error
286 if time_seconds > MAX_TIME:
287 raise ObjectFormatException(f"Date field should not exceed {MAX_TIME}")
290def git_line(*items: bytes) -> bytes:
291 """Formats items into a space separated line."""
292 return b" ".join(items) + b"\n"
295class FixedSha:
296 """SHA object that behaves like hashlib's but is given a fixed value."""
298 __slots__ = ("_hexsha", "_sha")
300 def __init__(self, hexsha: Union[str, bytes]) -> None:
301 """Initialize FixedSha with a fixed SHA value.
303 Args:
304 hexsha: Hex SHA value as string or bytes
305 """
306 if isinstance(hexsha, str):
307 hexsha = hexsha.encode("ascii")
308 if not isinstance(hexsha, bytes):
309 raise TypeError(f"Expected bytes for hexsha, got {hexsha!r}")
310 self._hexsha = hexsha
311 self._sha = hex_to_sha(hexsha)
313 def digest(self) -> bytes:
314 """Return the raw SHA digest."""
315 return self._sha
317 def hexdigest(self) -> str:
318 """Return the hex SHA digest."""
319 return self._hexsha.decode("ascii")
322# Type guard functions for runtime type narrowing
323if TYPE_CHECKING:
325 def is_commit(obj: "ShaFile") -> TypeGuard["Commit"]:
326 """Check if a ShaFile is a Commit."""
327 return obj.type_name == b"commit"
329 def is_tree(obj: "ShaFile") -> TypeGuard["Tree"]:
330 """Check if a ShaFile is a Tree."""
331 return obj.type_name == b"tree"
333 def is_blob(obj: "ShaFile") -> TypeGuard["Blob"]:
334 """Check if a ShaFile is a Blob."""
335 return obj.type_name == b"blob"
337 def is_tag(obj: "ShaFile") -> TypeGuard["Tag"]:
338 """Check if a ShaFile is a Tag."""
339 return obj.type_name == b"tag"
340else:
341 # Runtime versions without type narrowing
342 def is_commit(obj: "ShaFile") -> bool:
343 """Check if a ShaFile is a Commit."""
344 return obj.type_name == b"commit"
346 def is_tree(obj: "ShaFile") -> bool:
347 """Check if a ShaFile is a Tree."""
348 return obj.type_name == b"tree"
350 def is_blob(obj: "ShaFile") -> bool:
351 """Check if a ShaFile is a Blob."""
352 return obj.type_name == b"blob"
354 def is_tag(obj: "ShaFile") -> bool:
355 """Check if a ShaFile is a Tag."""
356 return obj.type_name == b"tag"
359class ShaFile:
360 """A git SHA file."""
362 __slots__ = ("_chunked_text", "_needs_serialization", "_sha")
364 _needs_serialization: bool
365 type_name: bytes
366 type_num: int
367 _chunked_text: Optional[list[bytes]]
368 _sha: Union[FixedSha, None, "HASH"]
370 @staticmethod
371 def _parse_legacy_object_header(
372 magic: bytes, f: Union[BufferedIOBase, IO[bytes], "_GitFile"]
373 ) -> "ShaFile":
374 """Parse a legacy object, creating it but not reading the file."""
375 bufsize = 1024
376 decomp = zlib.decompressobj()
377 header = decomp.decompress(magic)
378 start = 0
379 end = -1
380 while end < 0:
381 extra = f.read(bufsize)
382 header += decomp.decompress(extra)
383 magic += extra
384 end = header.find(b"\0", start)
385 start = len(header)
386 header = header[:end]
387 type_name, size = header.split(b" ", 1)
388 try:
389 int(size) # sanity check
390 except ValueError as exc:
391 raise ObjectFormatException(f"Object size not an integer: {exc}") from exc
392 obj_class = object_class(type_name)
393 if not obj_class:
394 raise ObjectFormatException(
395 "Not a known type: {}".format(type_name.decode("ascii"))
396 )
397 return obj_class()
399 def _parse_legacy_object(self, map: bytes) -> None:
400 """Parse a legacy object, setting the raw string."""
401 text = _decompress(map)
402 header_end = text.find(b"\0")
403 if header_end < 0:
404 raise ObjectFormatException("Invalid object header, no \\0")
405 self.set_raw_string(text[header_end + 1 :])
407 def as_legacy_object_chunks(self, compression_level: int = -1) -> Iterator[bytes]:
408 """Return chunks representing the object in the experimental format.
410 Returns: List of strings
411 """
412 compobj = zlib.compressobj(compression_level)
413 yield compobj.compress(self._header())
414 for chunk in self.as_raw_chunks():
415 yield compobj.compress(chunk)
416 yield compobj.flush()
418 def as_legacy_object(self, compression_level: int = -1) -> bytes:
419 """Return string representing the object in the experimental format."""
420 return b"".join(
421 self.as_legacy_object_chunks(compression_level=compression_level)
422 )
424 def as_raw_chunks(self) -> list[bytes]:
425 """Return chunks with serialization of the object.
427 Returns: List of strings, not necessarily one per line
428 """
429 if self._needs_serialization:
430 self._sha = None
431 self._chunked_text = self._serialize()
432 self._needs_serialization = False
433 assert self._chunked_text is not None
434 return self._chunked_text
436 def as_raw_string(self) -> bytes:
437 """Return raw string with serialization of the object.
439 Returns: String object
440 """
441 return b"".join(self.as_raw_chunks())
443 def __bytes__(self) -> bytes:
444 """Return raw string serialization of this object."""
445 return self.as_raw_string()
447 def __hash__(self) -> int:
448 """Return unique hash for this object."""
449 return hash(self.id)
451 def as_pretty_string(self) -> str:
452 """Return a string representing this object, fit for display."""
453 return self.as_raw_string().decode("utf-8", "replace")
455 def set_raw_string(self, text: bytes, sha: Optional[ObjectID] = None) -> None:
456 """Set the contents of this object from a serialized string."""
457 if not isinstance(text, bytes):
458 raise TypeError(f"Expected bytes for text, got {text!r}")
459 self.set_raw_chunks([text], sha)
461 def set_raw_chunks(
462 self, chunks: list[bytes], sha: Optional[ObjectID] = None
463 ) -> None:
464 """Set the contents of this object from a list of chunks."""
465 self._chunked_text = chunks
466 self._deserialize(chunks)
467 if sha is None:
468 self._sha = None
469 else:
470 self._sha = FixedSha(sha)
471 self._needs_serialization = False
473 @staticmethod
474 def _parse_object_header(
475 magic: bytes, f: Union[BufferedIOBase, IO[bytes], "_GitFile"]
476 ) -> "ShaFile":
477 """Parse a new style object, creating it but not reading the file."""
478 num_type = (ord(magic[0:1]) >> 4) & 7
479 obj_class = object_class(num_type)
480 if not obj_class:
481 raise ObjectFormatException(f"Not a known type {num_type}")
482 return obj_class()
484 def _parse_object(self, map: bytes) -> None:
485 """Parse a new style object, setting self._text."""
486 # skip type and size; type must have already been determined, and
487 # we trust zlib to fail if it's otherwise corrupted
488 byte = ord(map[0:1])
489 used = 1
490 while (byte & 0x80) != 0:
491 byte = ord(map[used : used + 1])
492 used += 1
493 raw = map[used:]
494 self.set_raw_string(_decompress(raw))
496 @classmethod
497 def _is_legacy_object(cls, magic: bytes) -> bool:
498 b0 = ord(magic[0:1])
499 b1 = ord(magic[1:2])
500 word = (b0 << 8) + b1
501 return (b0 & 0x8F) == 0x08 and (word % 31) == 0
503 @classmethod
504 def _parse_file(cls, f: Union[BufferedIOBase, IO[bytes], "_GitFile"]) -> "ShaFile":
505 map = f.read()
506 if not map:
507 raise EmptyFileException("Corrupted empty file detected")
509 if cls._is_legacy_object(map):
510 obj = cls._parse_legacy_object_header(map, f)
511 obj._parse_legacy_object(map)
512 else:
513 obj = cls._parse_object_header(map, f)
514 obj._parse_object(map)
515 return obj
517 def __init__(self) -> None:
518 """Don't call this directly."""
519 self._sha = None
520 self._chunked_text = []
521 self._needs_serialization = True
523 def _deserialize(self, chunks: list[bytes]) -> None:
524 raise NotImplementedError(self._deserialize)
526 def _serialize(self) -> list[bytes]:
527 raise NotImplementedError(self._serialize)
529 @classmethod
530 def from_path(cls, path: Union[str, bytes]) -> "ShaFile":
531 """Open a SHA file from disk."""
532 with GitFile(path, "rb") as f:
533 return cls.from_file(f)
535 @classmethod
536 def from_file(cls, f: Union[BufferedIOBase, IO[bytes], "_GitFile"]) -> "ShaFile":
537 """Get the contents of a SHA file on disk."""
538 try:
539 obj = cls._parse_file(f)
540 obj._sha = None
541 return obj
542 except (IndexError, ValueError) as exc:
543 raise ObjectFormatException("invalid object header") from exc
545 @staticmethod
546 def from_raw_string(
547 type_num: int, string: bytes, sha: Optional[ObjectID] = None
548 ) -> "ShaFile":
549 """Creates an object of the indicated type from the raw string given.
551 Args:
552 type_num: The numeric type of the object.
553 string: The raw uncompressed contents.
554 sha: Optional known sha for the object
555 """
556 cls = object_class(type_num)
557 if cls is None:
558 raise AssertionError(f"unsupported class type num: {type_num}")
559 obj = cls()
560 obj.set_raw_string(string, sha)
561 return obj
563 @staticmethod
564 def from_raw_chunks(
565 type_num: int, chunks: list[bytes], sha: Optional[ObjectID] = None
566 ) -> "ShaFile":
567 """Creates an object of the indicated type from the raw chunks given.
569 Args:
570 type_num: The numeric type of the object.
571 chunks: An iterable of the raw uncompressed contents.
572 sha: Optional known sha for the object
573 """
574 cls = object_class(type_num)
575 if cls is None:
576 raise AssertionError(f"unsupported class type num: {type_num}")
577 obj = cls()
578 obj.set_raw_chunks(chunks, sha)
579 return obj
581 @classmethod
582 def from_string(cls, string: bytes) -> Self:
583 """Create a ShaFile from a string."""
584 obj = cls()
585 obj.set_raw_string(string)
586 return obj
588 def _check_has_member(self, member: str, error_msg: str) -> None:
589 """Check that the object has a given member variable.
591 Args:
592 member: the member variable to check for
593 error_msg: the message for an error if the member is missing
594 Raises:
595 ObjectFormatException: with the given error_msg if member is
596 missing or is None
597 """
598 if getattr(self, member, None) is None:
599 raise ObjectFormatException(error_msg)
601 def check(self) -> None:
602 """Check this object for internal consistency.
604 Raises:
605 ObjectFormatException: if the object is malformed in some way
606 ChecksumMismatch: if the object was created with a SHA that does
607 not match its contents
608 """
609 # TODO: if we find that error-checking during object parsing is a
610 # performance bottleneck, those checks should be moved to the class's
611 # check() method during optimization so we can still check the object
612 # when necessary.
613 old_sha = self.id
614 try:
615 self._deserialize(self.as_raw_chunks())
616 self._sha = None
617 new_sha = self.id
618 except Exception as exc:
619 raise ObjectFormatException(exc) from exc
620 if old_sha != new_sha:
621 raise ChecksumMismatch(new_sha, old_sha)
623 def _header(self) -> bytes:
624 return object_header(self.type_num, self.raw_length())
626 def raw_length(self) -> int:
627 """Returns the length of the raw string of this object."""
628 return sum(map(len, self.as_raw_chunks()))
630 def sha(self) -> Union[FixedSha, "HASH"]:
631 """The SHA1 object that is the name of this object."""
632 if self._sha is None or self._needs_serialization:
633 # this is a local because as_raw_chunks() overwrites self._sha
634 new_sha = sha1()
635 new_sha.update(self._header())
636 for chunk in self.as_raw_chunks():
637 new_sha.update(chunk)
638 self._sha = new_sha
639 return self._sha
641 def copy(self) -> "ShaFile":
642 """Create a new copy of this SHA1 object from its raw string."""
643 obj_class = object_class(self.type_num)
644 if obj_class is None:
645 raise AssertionError(f"invalid type num {self.type_num}")
646 return obj_class.from_raw_string(self.type_num, self.as_raw_string(), self.id)
648 @property
649 def id(self) -> bytes:
650 """The hex SHA of this object."""
651 return self.sha().hexdigest().encode("ascii")
653 def __repr__(self) -> str:
654 """Return string representation of this object."""
655 return f"<{self.__class__.__name__} {self.id!r}>"
657 def __ne__(self, other: object) -> bool:
658 """Check whether this object does not match the other."""
659 return not isinstance(other, ShaFile) or self.id != other.id
661 def __eq__(self, other: object) -> bool:
662 """Return True if the SHAs of the two objects match."""
663 return isinstance(other, ShaFile) and self.id == other.id
665 def __lt__(self, other: object) -> bool:
666 """Return whether SHA of this object is less than the other."""
667 if not isinstance(other, ShaFile):
668 raise TypeError
669 return self.id < other.id
671 def __le__(self, other: object) -> bool:
672 """Check whether SHA of this object is less than or equal to the other."""
673 if not isinstance(other, ShaFile):
674 raise TypeError
675 return self.id <= other.id
678class Blob(ShaFile):
679 """A Git Blob object."""
681 __slots__ = ()
683 type_name = b"blob"
684 type_num = 3
686 _chunked_text: list[bytes]
688 def __init__(self) -> None:
689 """Initialize a new Blob object."""
690 super().__init__()
691 self._chunked_text = []
692 self._needs_serialization = False
694 def _get_data(self) -> bytes:
695 return self.as_raw_string()
697 def _set_data(self, data: bytes) -> None:
698 self.set_raw_string(data)
700 data = property(
701 _get_data, _set_data, doc="The text contained within the blob object."
702 )
704 def _get_chunked(self) -> list[bytes]:
705 return self._chunked_text
707 def _set_chunked(self, chunks: list[bytes]) -> None:
708 self._chunked_text = chunks
710 def _serialize(self) -> list[bytes]:
711 return self._chunked_text
713 def _deserialize(self, chunks: list[bytes]) -> None:
714 self._chunked_text = chunks
716 chunked = property(
717 _get_chunked,
718 _set_chunked,
719 doc="The text in the blob object, as chunks (not necessarily lines)",
720 )
722 @classmethod
723 def from_path(cls, path: Union[str, bytes]) -> "Blob":
724 """Read a blob from a file on disk.
726 Args:
727 path: Path to the blob file
729 Returns:
730 A Blob object
732 Raises:
733 NotBlobError: If the file is not a blob
734 """
735 blob = ShaFile.from_path(path)
736 if not isinstance(blob, cls):
737 raise NotBlobError(_path_to_bytes(path))
738 return blob
740 def check(self) -> None:
741 """Check this object for internal consistency.
743 Raises:
744 ObjectFormatException: if the object is malformed in some way
745 """
746 super().check()
748 def splitlines(self) -> list[bytes]:
749 """Return list of lines in this blob.
751 This preserves the original line endings.
752 """
753 chunks = self.chunked
754 if not chunks:
755 return []
756 if len(chunks) == 1:
757 return chunks[0].splitlines(True) # type: ignore[no-any-return]
758 remaining = None
759 ret = []
760 for chunk in chunks:
761 lines = chunk.splitlines(True)
762 if len(lines) > 1:
763 ret.append((remaining or b"") + lines[0])
764 ret.extend(lines[1:-1])
765 remaining = lines[-1]
766 elif len(lines) == 1:
767 if remaining is None:
768 remaining = lines.pop()
769 else:
770 remaining += lines.pop()
771 if remaining is not None:
772 ret.append(remaining)
773 return ret
776def _parse_message(
777 chunks: Iterable[bytes],
778) -> Iterator[Union[tuple[None, None], tuple[Optional[bytes], bytes]]]:
779 """Parse a message with a list of fields and a body.
781 Args:
782 chunks: the raw chunks of the tag or commit object.
783 Returns: iterator of tuples of (field, value), one per header line, in the
784 order read from the text, possibly including duplicates. Includes a
785 field named None for the freeform tag/commit text.
786 """
787 f = BytesIO(b"".join(chunks))
788 k = None
789 v = b""
790 eof = False
792 def _strip_last_newline(value: bytes) -> bytes:
793 """Strip the last newline from value."""
794 if value and value.endswith(b"\n"):
795 return value[:-1]
796 return value
798 # Parse the headers
799 #
800 # Headers can contain newlines. The next line is indented with a space.
801 # We store the latest key as 'k', and the accumulated value as 'v'.
802 for line in f:
803 if line.startswith(b" "):
804 # Indented continuation of the previous line
805 v += line[1:]
806 else:
807 if k is not None:
808 # We parsed a new header, return its value
809 yield (k, _strip_last_newline(v))
810 if line == b"\n":
811 # Empty line indicates end of headers
812 break
813 (k, v) = line.split(b" ", 1)
815 else:
816 # We reached end of file before the headers ended. We still need to
817 # return the previous header, then we need to return a None field for
818 # the text.
819 eof = True
820 if k is not None:
821 yield (k, _strip_last_newline(v))
822 yield (None, None)
824 if not eof:
825 # We didn't reach the end of file while parsing headers. We can return
826 # the rest of the file as a message.
827 yield (None, f.read())
829 f.close()
832def _format_message(
833 headers: list[tuple[bytes, bytes]], body: Optional[bytes]
834) -> Iterator[bytes]:
835 for field, value in headers:
836 lines = value.split(b"\n")
837 yield git_line(field, lines[0])
838 for line in lines[1:]:
839 yield b" " + line + b"\n"
840 yield b"\n" # There must be a new line after the headers
841 if body:
842 yield body
845class Tag(ShaFile):
846 """A Git Tag object."""
848 type_name = b"tag"
849 type_num = 4
851 __slots__ = (
852 "_message",
853 "_name",
854 "_object_class",
855 "_object_sha",
856 "_signature",
857 "_tag_time",
858 "_tag_timezone",
859 "_tag_timezone_neg_utc",
860 "_tagger",
861 )
863 _message: Optional[bytes]
864 _name: Optional[bytes]
865 _object_class: Optional[type["ShaFile"]]
866 _object_sha: Optional[bytes]
867 _signature: Optional[bytes]
868 _tag_time: Optional[int]
869 _tag_timezone: Optional[int]
870 _tag_timezone_neg_utc: Optional[bool]
871 _tagger: Optional[bytes]
873 def __init__(self) -> None:
874 """Initialize a new Tag object."""
875 super().__init__()
876 self._tagger = None
877 self._tag_time = None
878 self._tag_timezone = None
879 self._tag_timezone_neg_utc = False
880 self._signature: Optional[bytes] = None
882 @classmethod
883 def from_path(cls, filename: Union[str, bytes]) -> "Tag":
884 """Read a tag from a file on disk.
886 Args:
887 filename: Path to the tag file
889 Returns:
890 A Tag object
892 Raises:
893 NotTagError: If the file is not a tag
894 """
895 tag = ShaFile.from_path(filename)
896 if not isinstance(tag, cls):
897 raise NotTagError(_path_to_bytes(filename))
898 return tag
900 def check(self) -> None:
901 """Check this object for internal consistency.
903 Raises:
904 ObjectFormatException: if the object is malformed in some way
905 """
906 super().check()
907 assert self._chunked_text is not None
908 self._check_has_member("_object_sha", "missing object sha")
909 self._check_has_member("_object_class", "missing object type")
910 self._check_has_member("_name", "missing tag name")
912 if not self._name:
913 raise ObjectFormatException("empty tag name")
915 if self._object_sha is None:
916 raise ObjectFormatException("missing object sha")
917 check_hexsha(self._object_sha, "invalid object sha")
919 if self._tagger is not None:
920 check_identity(self._tagger, "invalid tagger")
922 self._check_has_member("_tag_time", "missing tag time")
923 if self._tag_time is None:
924 raise ObjectFormatException("missing tag time")
925 check_time(self._tag_time)
927 last = None
928 for field, _ in _parse_message(self._chunked_text):
929 if field == _OBJECT_HEADER and last is not None:
930 raise ObjectFormatException("unexpected object")
931 elif field == _TYPE_HEADER and last != _OBJECT_HEADER:
932 raise ObjectFormatException("unexpected type")
933 elif field == _TAG_HEADER and last != _TYPE_HEADER:
934 raise ObjectFormatException("unexpected tag name")
935 elif field == _TAGGER_HEADER and last != _TAG_HEADER:
936 raise ObjectFormatException("unexpected tagger")
937 last = field
939 def _serialize(self) -> list[bytes]:
940 headers = []
941 if self._object_sha is None:
942 raise ObjectFormatException("missing object sha")
943 headers.append((_OBJECT_HEADER, self._object_sha))
944 if self._object_class is None:
945 raise ObjectFormatException("missing object class")
946 headers.append((_TYPE_HEADER, self._object_class.type_name))
947 if self._name is None:
948 raise ObjectFormatException("missing tag name")
949 headers.append((_TAG_HEADER, self._name))
950 if self._tagger:
951 if self._tag_time is None:
952 headers.append((_TAGGER_HEADER, self._tagger))
953 else:
954 if self._tag_timezone is None or self._tag_timezone_neg_utc is None:
955 raise ObjectFormatException("missing timezone info")
956 headers.append(
957 (
958 _TAGGER_HEADER,
959 format_time_entry(
960 self._tagger,
961 self._tag_time,
962 (self._tag_timezone, self._tag_timezone_neg_utc),
963 ),
964 )
965 )
967 if self.message is None and self._signature is None:
968 body = None
969 else:
970 body = (self.message or b"") + (self._signature or b"")
971 return list(_format_message(headers, body))
973 def _deserialize(self, chunks: list[bytes]) -> None:
974 """Grab the metadata attached to the tag."""
975 self._tagger = None
976 self._tag_time = None
977 self._tag_timezone = None
978 self._tag_timezone_neg_utc = False
979 for field, value in _parse_message(chunks):
980 if field == _OBJECT_HEADER:
981 self._object_sha = value
982 elif field == _TYPE_HEADER:
983 assert isinstance(value, bytes)
984 obj_class = object_class(value)
985 if not obj_class:
986 raise ObjectFormatException(f"Not a known type: {value!r}")
987 self._object_class = obj_class
988 elif field == _TAG_HEADER:
989 self._name = value
990 elif field == _TAGGER_HEADER:
991 if value is None:
992 raise ObjectFormatException("missing tagger value")
993 (
994 self._tagger,
995 self._tag_time,
996 (self._tag_timezone, self._tag_timezone_neg_utc),
997 ) = parse_time_entry(value)
998 elif field is None:
999 if value is None:
1000 self._message = None
1001 self._signature = None
1002 else:
1003 try:
1004 sig_idx = value.index(BEGIN_PGP_SIGNATURE)
1005 except ValueError:
1006 self._message = value
1007 self._signature = None
1008 else:
1009 self._message = value[:sig_idx]
1010 self._signature = value[sig_idx:]
1011 else:
1012 raise ObjectFormatException(
1013 f"Unknown field {field.decode('ascii', 'replace')}"
1014 )
1016 def _get_object(self) -> tuple[type[ShaFile], bytes]:
1017 """Get the object pointed to by this tag.
1019 Returns: tuple of (object class, sha).
1020 """
1021 if self._object_class is None or self._object_sha is None:
1022 raise ValueError("Tag object is not properly initialized")
1023 return (self._object_class, self._object_sha)
1025 def _set_object(self, value: tuple[type[ShaFile], bytes]) -> None:
1026 (self._object_class, self._object_sha) = value
1027 self._needs_serialization = True
1029 object = property(_get_object, _set_object)
1031 name = serializable_property("name", "The name of this tag")
1032 tagger = serializable_property(
1033 "tagger", "Returns the name of the person who created this tag"
1034 )
1035 tag_time = serializable_property(
1036 "tag_time",
1037 "The creation timestamp of the tag. As the number of seconds since the epoch",
1038 )
1039 tag_timezone = serializable_property(
1040 "tag_timezone", "The timezone that tag_time is in."
1041 )
1042 message = serializable_property("message", "the message attached to this tag")
1044 signature = serializable_property("signature", "Optional detached GPG signature")
1046 def sign(self, keyid: Optional[str] = None) -> None:
1047 """Sign this tag with a GPG key.
1049 Args:
1050 keyid: Optional GPG key ID to use for signing. If not specified,
1051 the default GPG key will be used.
1052 """
1053 import gpg
1055 with gpg.Context(armor=True) as c:
1056 if keyid is not None:
1057 key = c.get_key(keyid)
1058 with gpg.Context(armor=True, signers=[key]) as ctx:
1059 self.signature, unused_result = ctx.sign(
1060 self.as_raw_string(),
1061 mode=gpg.constants.sig.mode.DETACH,
1062 )
1063 else:
1064 self.signature, unused_result = c.sign(
1065 self.as_raw_string(), mode=gpg.constants.sig.mode.DETACH
1066 )
1068 def raw_without_sig(self) -> bytes:
1069 """Return raw string serialization without the GPG/SSH signature.
1071 self.signature is a signature for the returned raw byte string serialization.
1072 """
1073 ret = self.as_raw_string()
1074 if self._signature:
1075 ret = ret[: -len(self._signature)]
1076 return ret
1078 def verify(self, keyids: Optional[Iterable[str]] = None) -> None:
1079 """Verify GPG signature for this tag (if it is signed).
1081 Args:
1082 keyids: Optional iterable of trusted keyids for this tag.
1083 If this tag is not signed by any key in keyids verification will
1084 fail. If not specified, this function only verifies that the tag
1085 has a valid signature.
1087 Raises:
1088 gpg.errors.BadSignatures: if GPG signature verification fails
1089 gpg.errors.MissingSignatures: if tag was not signed by a key
1090 specified in keyids
1091 """
1092 if self._signature is None:
1093 return
1095 import gpg
1097 with gpg.Context() as ctx:
1098 data, result = ctx.verify(
1099 self.raw_without_sig(),
1100 signature=self._signature,
1101 )
1102 if keyids:
1103 keys = [ctx.get_key(key) for key in keyids]
1104 for key in keys:
1105 for subkey in keys:
1106 for sig in result.signatures:
1107 if subkey.can_sign and subkey.fpr == sig.fpr:
1108 return
1109 raise gpg.errors.MissingSignatures(result, keys, results=(data, result))
1112class TreeEntry(NamedTuple):
1113 """Named tuple encapsulating a single tree entry."""
1115 path: bytes
1116 mode: int
1117 sha: bytes
1119 def in_path(self, path: bytes) -> "TreeEntry":
1120 """Return a copy of this entry with the given path prepended."""
1121 if not isinstance(self.path, bytes):
1122 raise TypeError(f"Expected bytes for path, got {path!r}")
1123 return TreeEntry(posixpath.join(path, self.path), self.mode, self.sha)
1126def parse_tree(text: bytes, strict: bool = False) -> Iterator[tuple[bytes, int, bytes]]:
1127 """Parse a tree text.
1129 Args:
1130 text: Serialized text to parse
1131 strict: If True, enforce strict validation
1132 Returns: iterator of tuples of (name, mode, sha)
1134 Raises:
1135 ObjectFormatException: if the object was malformed in some way
1136 """
1137 count = 0
1138 length = len(text)
1139 while count < length:
1140 mode_end = text.index(b" ", count)
1141 mode_text = text[count:mode_end]
1142 if strict and mode_text.startswith(b"0"):
1143 raise ObjectFormatException(f"Invalid mode {mode_text!r}")
1144 try:
1145 mode = int(mode_text, 8)
1146 except ValueError as exc:
1147 raise ObjectFormatException(f"Invalid mode {mode_text!r}") from exc
1148 name_end = text.index(b"\0", mode_end)
1149 name = text[mode_end + 1 : name_end]
1150 count = name_end + 21
1151 sha = text[name_end + 1 : count]
1152 if len(sha) != 20:
1153 raise ObjectFormatException("Sha has invalid length")
1154 hexsha = sha_to_hex(sha)
1155 yield (name, mode, hexsha)
1158def serialize_tree(items: Iterable[tuple[bytes, int, bytes]]) -> Iterator[bytes]:
1159 """Serialize the items in a tree to a text.
1161 Args:
1162 items: Sorted iterable over (name, mode, sha) tuples
1163 Returns: Serialized tree text as chunks
1164 """
1165 for name, mode, hexsha in items:
1166 yield (
1167 (f"{mode:04o}").encode("ascii") + b" " + name + b"\0" + hex_to_sha(hexsha)
1168 )
1171def sorted_tree_items(
1172 entries: dict[bytes, tuple[int, bytes]], name_order: bool
1173) -> Iterator[TreeEntry]:
1174 """Iterate over a tree entries dictionary.
1176 Args:
1177 name_order: If True, iterate entries in order of their name. If
1178 False, iterate entries in tree order, that is, treat subtree entries as
1179 having '/' appended.
1180 entries: Dictionary mapping names to (mode, sha) tuples
1181 Returns: Iterator over (name, mode, hexsha)
1182 """
1183 if name_order:
1184 key_func = key_entry_name_order
1185 else:
1186 key_func = key_entry
1187 for name, entry in sorted(entries.items(), key=key_func):
1188 mode, hexsha = entry
1189 # Stricter type checks than normal to mirror checks in the Rust version.
1190 mode = int(mode)
1191 if not isinstance(hexsha, bytes):
1192 raise TypeError(f"Expected bytes for SHA, got {hexsha!r}")
1193 yield TreeEntry(name, mode, hexsha)
1196def key_entry(entry: tuple[bytes, tuple[int, ObjectID]]) -> bytes:
1197 """Sort key for tree entry.
1199 Args:
1200 entry: (name, value) tuple
1201 """
1202 (name, (mode, _sha)) = entry
1203 if stat.S_ISDIR(mode):
1204 name += b"/"
1205 return name
1208def key_entry_name_order(entry: tuple[bytes, tuple[int, ObjectID]]) -> bytes:
1209 """Sort key for tree entry in name order."""
1210 return entry[0]
1213def pretty_format_tree_entry(
1214 name: bytes, mode: int, hexsha: bytes, encoding: str = "utf-8"
1215) -> str:
1216 """Pretty format tree entry.
1218 Args:
1219 name: Name of the directory entry
1220 mode: Mode of entry
1221 hexsha: Hexsha of the referenced object
1222 encoding: Character encoding for the name
1223 Returns: string describing the tree entry
1224 """
1225 if mode & stat.S_IFDIR:
1226 kind = "tree"
1227 else:
1228 kind = "blob"
1229 return "{:04o} {} {}\t{}\n".format(
1230 mode,
1231 kind,
1232 hexsha.decode("ascii"),
1233 name.decode(encoding, "replace"),
1234 )
1237class SubmoduleEncountered(Exception):
1238 """A submodule was encountered while resolving a path."""
1240 def __init__(self, path: bytes, sha: ObjectID) -> None:
1241 """Initialize SubmoduleEncountered exception.
1243 Args:
1244 path: Path where the submodule was encountered
1245 sha: SHA of the submodule
1246 """
1247 self.path = path
1248 self.sha = sha
1251class Tree(ShaFile):
1252 """A Git tree object."""
1254 type_name = b"tree"
1255 type_num = 2
1257 __slots__ = "_entries"
1259 def __init__(self) -> None:
1260 """Initialize an empty Tree."""
1261 super().__init__()
1262 self._entries: dict[bytes, tuple[int, bytes]] = {}
1264 @classmethod
1265 def from_path(cls, filename: Union[str, bytes]) -> "Tree":
1266 """Read a tree from a file on disk.
1268 Args:
1269 filename: Path to the tree file
1271 Returns:
1272 A Tree object
1274 Raises:
1275 NotTreeError: If the file is not a tree
1276 """
1277 tree = ShaFile.from_path(filename)
1278 if not isinstance(tree, cls):
1279 raise NotTreeError(_path_to_bytes(filename))
1280 return tree
1282 def __contains__(self, name: bytes) -> bool:
1283 """Check if name exists in tree."""
1284 return name in self._entries
1286 def __getitem__(self, name: bytes) -> tuple[int, ObjectID]:
1287 """Get tree entry by name."""
1288 return self._entries[name]
1290 def __setitem__(self, name: bytes, value: tuple[int, ObjectID]) -> None:
1291 """Set a tree entry by name.
1293 Args:
1294 name: The name of the entry, as a string.
1295 value: A tuple of (mode, hexsha), where mode is the mode of the
1296 entry as an integral type and hexsha is the hex SHA of the entry as
1297 a string.
1298 """
1299 mode, hexsha = value
1300 self._entries[name] = (mode, hexsha)
1301 self._needs_serialization = True
1303 def __delitem__(self, name: bytes) -> None:
1304 """Delete tree entry by name."""
1305 del self._entries[name]
1306 self._needs_serialization = True
1308 def __len__(self) -> int:
1309 """Return number of entries in tree."""
1310 return len(self._entries)
1312 def __iter__(self) -> Iterator[bytes]:
1313 """Iterate over tree entry names."""
1314 return iter(self._entries)
1316 def add(self, name: bytes, mode: int, hexsha: bytes) -> None:
1317 """Add an entry to the tree.
1319 Args:
1320 mode: The mode of the entry as an integral type. Not all
1321 possible modes are supported by git; see check() for details.
1322 name: The name of the entry, as a string.
1323 hexsha: The hex SHA of the entry as a string.
1324 """
1325 self._entries[name] = mode, hexsha
1326 self._needs_serialization = True
1328 def iteritems(self, name_order: bool = False) -> Iterator[TreeEntry]:
1329 """Iterate over entries.
1331 Args:
1332 name_order: If True, iterate in name order instead of tree
1333 order.
1334 Returns: Iterator over (name, mode, sha) tuples
1335 """
1336 return sorted_tree_items(self._entries, name_order)
1338 def items(self) -> list[TreeEntry]:
1339 """Return the sorted entries in this tree.
1341 Returns: List with (name, mode, sha) tuples
1342 """
1343 return list(self.iteritems())
1345 def _deserialize(self, chunks: list[bytes]) -> None:
1346 """Grab the entries in the tree."""
1347 try:
1348 parsed_entries = parse_tree(b"".join(chunks))
1349 except ValueError as exc:
1350 raise ObjectFormatException(exc) from exc
1351 # TODO: list comprehension is for efficiency in the common (small)
1352 # case; if memory efficiency in the large case is a concern, use a
1353 # genexp.
1354 self._entries = {n: (m, s) for n, m, s in parsed_entries}
1356 def check(self) -> None:
1357 """Check this object for internal consistency.
1359 Raises:
1360 ObjectFormatException: if the object is malformed in some way
1361 """
1362 super().check()
1363 assert self._chunked_text is not None
1364 last = None
1365 allowed_modes = (
1366 stat.S_IFREG | 0o755,
1367 stat.S_IFREG | 0o644,
1368 stat.S_IFLNK,
1369 stat.S_IFDIR,
1370 S_IFGITLINK,
1371 # TODO: optionally exclude as in git fsck --strict
1372 stat.S_IFREG | 0o664,
1373 )
1374 for name, mode, sha in parse_tree(b"".join(self._chunked_text), True):
1375 check_hexsha(sha, f"invalid sha {sha!r}")
1376 if b"/" in name or name in (b"", b".", b"..", b".git"):
1377 raise ObjectFormatException(
1378 "invalid name {}".format(name.decode("utf-8", "replace"))
1379 )
1381 if mode not in allowed_modes:
1382 raise ObjectFormatException(f"invalid mode {mode:06o}")
1384 entry = (name, (mode, sha))
1385 if last:
1386 if key_entry(last) > key_entry(entry):
1387 raise ObjectFormatException("entries not sorted")
1388 if name == last[0]:
1389 raise ObjectFormatException(f"duplicate entry {name!r}")
1390 last = entry
1392 def _serialize(self) -> list[bytes]:
1393 return list(serialize_tree(self.iteritems()))
1395 def as_pretty_string(self) -> str:
1396 """Return a human-readable string representation of this tree.
1398 Returns:
1399 Pretty-printed tree entries
1400 """
1401 text: list[str] = []
1402 for name, mode, hexsha in self.iteritems():
1403 text.append(pretty_format_tree_entry(name, mode, hexsha))
1404 return "".join(text)
1406 def lookup_path(
1407 self, lookup_obj: Callable[[ObjectID], ShaFile], path: bytes
1408 ) -> tuple[int, ObjectID]:
1409 """Look up an object in a Git tree.
1411 Args:
1412 lookup_obj: Callback for retrieving object by SHA1
1413 path: Path to lookup
1414 Returns: A tuple of (mode, SHA) of the resulting path.
1415 """
1416 # Handle empty path - return the tree itself
1417 if not path:
1418 return stat.S_IFDIR, self.id
1420 parts = path.split(b"/")
1421 sha = self.id
1422 mode: Optional[int] = None
1423 for i, p in enumerate(parts):
1424 if not p:
1425 continue
1426 if mode is not None and S_ISGITLINK(mode):
1427 raise SubmoduleEncountered(b"/".join(parts[:i]), sha)
1428 obj = lookup_obj(sha)
1429 if not isinstance(obj, Tree):
1430 raise NotTreeError(sha)
1431 mode, sha = obj[p]
1432 if mode is None:
1433 raise ValueError("No valid path found")
1434 return mode, sha
1437def parse_timezone(text: bytes) -> tuple[int, bool]:
1438 """Parse a timezone text fragment (e.g. '+0100').
1440 Args:
1441 text: Text to parse.
1442 Returns: Tuple with timezone as seconds difference to UTC
1443 and a boolean indicating whether this was a UTC timezone
1444 prefixed with a negative sign (-0000).
1445 """
1446 # cgit parses the first character as the sign, and the rest
1447 # as an integer (using strtol), which could also be negative.
1448 # We do the same for compatibility. See #697828.
1449 if text[0] not in b"+-":
1450 raise ValueError("Timezone must start with + or - ({text})".format(**vars()))
1451 sign = text[:1]
1452 offset = int(text[1:])
1453 if sign == b"-":
1454 offset = -offset
1455 unnecessary_negative_timezone = offset >= 0 and sign == b"-"
1456 signum = ((offset < 0) and -1) or 1
1457 offset = abs(offset)
1458 hours = int(offset / 100)
1459 minutes = offset % 100
1460 return (
1461 signum * (hours * 3600 + minutes * 60),
1462 unnecessary_negative_timezone,
1463 )
1466def format_timezone(offset: int, unnecessary_negative_timezone: bool = False) -> bytes:
1467 """Format a timezone for Git serialization.
1469 Args:
1470 offset: Timezone offset as seconds difference to UTC
1471 unnecessary_negative_timezone: Whether to use a minus sign for
1472 UTC or positive timezones (-0000 and --700 rather than +0000 / +0700).
1473 """
1474 if offset % 60 != 0:
1475 raise ValueError("Unable to handle non-minute offset.")
1476 if offset < 0 or unnecessary_negative_timezone:
1477 sign = "-"
1478 offset = -offset
1479 else:
1480 sign = "+"
1481 return ("%c%02d%02d" % (sign, offset / 3600, (offset / 60) % 60)).encode("ascii") # noqa: UP031
1484def parse_time_entry(
1485 value: bytes,
1486) -> tuple[bytes, Optional[int], tuple[Optional[int], bool]]:
1487 """Parse event.
1489 Args:
1490 value: Bytes representing a git commit/tag line
1491 Raises:
1492 ObjectFormatException in case of parsing error (malformed
1493 field date)
1494 Returns: Tuple of (author, time, (timezone, timezone_neg_utc))
1495 """
1496 try:
1497 sep = value.rindex(b"> ")
1498 except ValueError:
1499 return (value, None, (None, False))
1500 try:
1501 person = value[0 : sep + 1]
1502 rest = value[sep + 2 :]
1503 timetext, timezonetext = rest.rsplit(b" ", 1)
1504 time = int(timetext)
1505 timezone, timezone_neg_utc = parse_timezone(timezonetext)
1506 except ValueError as exc:
1507 raise ObjectFormatException(exc) from exc
1508 return person, time, (timezone, timezone_neg_utc)
1511def format_time_entry(
1512 person: bytes, time: int, timezone_info: tuple[int, bool]
1513) -> bytes:
1514 """Format an event."""
1515 (timezone, timezone_neg_utc) = timezone_info
1516 return b" ".join(
1517 [person, str(time).encode("ascii"), format_timezone(timezone, timezone_neg_utc)]
1518 )
1521@replace_me(since="0.21.0", remove_in="0.24.0")
1522def parse_commit(
1523 chunks: Iterable[bytes],
1524) -> tuple[
1525 Optional[bytes],
1526 list[bytes],
1527 tuple[Optional[bytes], Optional[int], tuple[Optional[int], Optional[bool]]],
1528 tuple[Optional[bytes], Optional[int], tuple[Optional[int], Optional[bool]]],
1529 Optional[bytes],
1530 list[Tag],
1531 Optional[bytes],
1532 Optional[bytes],
1533 list[tuple[bytes, bytes]],
1534]:
1535 """Parse a commit object from chunks.
1537 Args:
1538 chunks: Chunks to parse
1539 Returns: Tuple of (tree, parents, author_info, commit_info,
1540 encoding, mergetag, gpgsig, message, extra)
1541 """
1542 parents = []
1543 extra = []
1544 tree = None
1545 author_info: tuple[
1546 Optional[bytes], Optional[int], tuple[Optional[int], Optional[bool]]
1547 ] = (None, None, (None, None))
1548 commit_info: tuple[
1549 Optional[bytes], Optional[int], tuple[Optional[int], Optional[bool]]
1550 ] = (None, None, (None, None))
1551 encoding = None
1552 mergetag = []
1553 message = None
1554 gpgsig = None
1556 for field, value in _parse_message(chunks):
1557 # TODO(jelmer): Enforce ordering
1558 if field == _TREE_HEADER:
1559 tree = value
1560 elif field == _PARENT_HEADER:
1561 if value is None:
1562 raise ObjectFormatException("missing parent value")
1563 parents.append(value)
1564 elif field == _AUTHOR_HEADER:
1565 if value is None:
1566 raise ObjectFormatException("missing author value")
1567 author_info = parse_time_entry(value)
1568 elif field == _COMMITTER_HEADER:
1569 if value is None:
1570 raise ObjectFormatException("missing committer value")
1571 commit_info = parse_time_entry(value)
1572 elif field == _ENCODING_HEADER:
1573 encoding = value
1574 elif field == _MERGETAG_HEADER:
1575 if value is None:
1576 raise ObjectFormatException("missing mergetag value")
1577 tag = Tag.from_string(value + b"\n")
1578 assert isinstance(tag, Tag)
1579 mergetag.append(tag)
1580 elif field == _GPGSIG_HEADER:
1581 gpgsig = value
1582 elif field is None:
1583 message = value
1584 else:
1585 if value is None:
1586 raise ObjectFormatException(f"missing value for field {field!r}")
1587 extra.append((field, value))
1588 return (
1589 tree,
1590 parents,
1591 author_info,
1592 commit_info,
1593 encoding,
1594 mergetag,
1595 gpgsig,
1596 message,
1597 extra,
1598 )
1601class Commit(ShaFile):
1602 """A git commit object."""
1604 type_name = b"commit"
1605 type_num = 1
1607 __slots__ = (
1608 "_author",
1609 "_author_time",
1610 "_author_timezone",
1611 "_author_timezone_neg_utc",
1612 "_commit_time",
1613 "_commit_timezone",
1614 "_commit_timezone_neg_utc",
1615 "_committer",
1616 "_encoding",
1617 "_extra",
1618 "_gpgsig",
1619 "_mergetag",
1620 "_message",
1621 "_parents",
1622 "_tree",
1623 )
1625 def __init__(self) -> None:
1626 """Initialize an empty Commit."""
1627 super().__init__()
1628 self._parents: list[bytes] = []
1629 self._encoding: Optional[bytes] = None
1630 self._mergetag: list[Tag] = []
1631 self._gpgsig: Optional[bytes] = None
1632 self._extra: list[tuple[bytes, Optional[bytes]]] = []
1633 self._author_timezone_neg_utc: Optional[bool] = False
1634 self._commit_timezone_neg_utc: Optional[bool] = False
1636 @classmethod
1637 def from_path(cls, path: Union[str, bytes]) -> "Commit":
1638 """Read a commit from a file on disk.
1640 Args:
1641 path: Path to the commit file
1643 Returns:
1644 A Commit object
1646 Raises:
1647 NotCommitError: If the file is not a commit
1648 """
1649 commit = ShaFile.from_path(path)
1650 if not isinstance(commit, cls):
1651 raise NotCommitError(_path_to_bytes(path))
1652 return commit
1654 def _deserialize(self, chunks: list[bytes]) -> None:
1655 self._parents = []
1656 self._extra = []
1657 self._tree = None
1658 author_info: tuple[
1659 Optional[bytes], Optional[int], tuple[Optional[int], Optional[bool]]
1660 ] = (None, None, (None, None))
1661 commit_info: tuple[
1662 Optional[bytes], Optional[int], tuple[Optional[int], Optional[bool]]
1663 ] = (None, None, (None, None))
1664 self._encoding = None
1665 self._mergetag = []
1666 self._message = None
1667 self._gpgsig = None
1669 for field, value in _parse_message(chunks):
1670 # TODO(jelmer): Enforce ordering
1671 if field == _TREE_HEADER:
1672 self._tree = value
1673 elif field == _PARENT_HEADER:
1674 assert value is not None
1675 self._parents.append(value)
1676 elif field == _AUTHOR_HEADER:
1677 if value is None:
1678 raise ObjectFormatException("missing author value")
1679 author_info = parse_time_entry(value)
1680 elif field == _COMMITTER_HEADER:
1681 if value is None:
1682 raise ObjectFormatException("missing committer value")
1683 commit_info = parse_time_entry(value)
1684 elif field == _ENCODING_HEADER:
1685 self._encoding = value
1686 elif field == _MERGETAG_HEADER:
1687 assert value is not None
1688 tag = Tag.from_string(value + b"\n")
1689 assert isinstance(tag, Tag)
1690 self._mergetag.append(tag)
1691 elif field == _GPGSIG_HEADER:
1692 self._gpgsig = value
1693 elif field is None:
1694 self._message = value
1695 else:
1696 self._extra.append((field, value))
1698 (
1699 self._author,
1700 self._author_time,
1701 (self._author_timezone, self._author_timezone_neg_utc),
1702 ) = author_info
1703 (
1704 self._committer,
1705 self._commit_time,
1706 (self._commit_timezone, self._commit_timezone_neg_utc),
1707 ) = commit_info
1709 def check(self) -> None:
1710 """Check this object for internal consistency.
1712 Raises:
1713 ObjectFormatException: if the object is malformed in some way
1714 """
1715 super().check()
1716 assert self._chunked_text is not None
1717 self._check_has_member("_tree", "missing tree")
1718 self._check_has_member("_author", "missing author")
1719 self._check_has_member("_committer", "missing committer")
1720 self._check_has_member("_author_time", "missing author time")
1721 self._check_has_member("_commit_time", "missing commit time")
1723 for parent in self._parents:
1724 check_hexsha(parent, "invalid parent sha")
1725 assert self._tree is not None # checked by _check_has_member above
1726 check_hexsha(self._tree, "invalid tree sha")
1728 assert self._author is not None # checked by _check_has_member above
1729 assert self._committer is not None # checked by _check_has_member above
1730 check_identity(self._author, "invalid author")
1731 check_identity(self._committer, "invalid committer")
1733 assert self._author_time is not None # checked by _check_has_member above
1734 assert self._commit_time is not None # checked by _check_has_member above
1735 check_time(self._author_time)
1736 check_time(self._commit_time)
1738 last = None
1739 for field, _ in _parse_message(self._chunked_text):
1740 if field == _TREE_HEADER and last is not None:
1741 raise ObjectFormatException("unexpected tree")
1742 elif field == _PARENT_HEADER and last not in (
1743 _PARENT_HEADER,
1744 _TREE_HEADER,
1745 ):
1746 raise ObjectFormatException("unexpected parent")
1747 elif field == _AUTHOR_HEADER and last not in (
1748 _TREE_HEADER,
1749 _PARENT_HEADER,
1750 ):
1751 raise ObjectFormatException("unexpected author")
1752 elif field == _COMMITTER_HEADER and last != _AUTHOR_HEADER:
1753 raise ObjectFormatException("unexpected committer")
1754 elif field == _ENCODING_HEADER and last != _COMMITTER_HEADER:
1755 raise ObjectFormatException("unexpected encoding")
1756 last = field
1758 # TODO: optionally check for duplicate parents
1760 def sign(self, keyid: Optional[str] = None) -> None:
1761 """Sign this commit with a GPG key.
1763 Args:
1764 keyid: Optional GPG key ID to use for signing. If not specified,
1765 the default GPG key will be used.
1766 """
1767 import gpg
1769 with gpg.Context(armor=True) as c:
1770 if keyid is not None:
1771 key = c.get_key(keyid)
1772 with gpg.Context(armor=True, signers=[key]) as ctx:
1773 self.gpgsig, unused_result = ctx.sign(
1774 self.as_raw_string(),
1775 mode=gpg.constants.sig.mode.DETACH,
1776 )
1777 else:
1778 self.gpgsig, unused_result = c.sign(
1779 self.as_raw_string(), mode=gpg.constants.sig.mode.DETACH
1780 )
1782 def raw_without_sig(self) -> bytes:
1783 """Return raw string serialization without the GPG/SSH signature.
1785 self.gpgsig is a signature for the returned raw byte string serialization.
1786 """
1787 tmp = self.copy()
1788 assert isinstance(tmp, Commit)
1789 tmp._gpgsig = None
1790 tmp.gpgsig = None
1791 return tmp.as_raw_string()
1793 def verify(self, keyids: Optional[Iterable[str]] = None) -> None:
1794 """Verify GPG signature for this commit (if it is signed).
1796 Args:
1797 keyids: Optional iterable of trusted keyids for this commit.
1798 If this commit is not signed by any key in keyids verification will
1799 fail. If not specified, this function only verifies that the commit
1800 has a valid signature.
1802 Raises:
1803 gpg.errors.BadSignatures: if GPG signature verification fails
1804 gpg.errors.MissingSignatures: if commit was not signed by a key
1805 specified in keyids
1806 """
1807 if self._gpgsig is None:
1808 return
1810 import gpg
1812 with gpg.Context() as ctx:
1813 data, result = ctx.verify(
1814 self.raw_without_sig(),
1815 signature=self._gpgsig,
1816 )
1817 if keyids:
1818 keys = [ctx.get_key(key) for key in keyids]
1819 for key in keys:
1820 for subkey in keys:
1821 for sig in result.signatures:
1822 if subkey.can_sign and subkey.fpr == sig.fpr:
1823 return
1824 raise gpg.errors.MissingSignatures(result, keys, results=(data, result))
1826 def _serialize(self) -> list[bytes]:
1827 headers = []
1828 assert self._tree is not None
1829 tree_bytes = self._tree.id if isinstance(self._tree, Tree) else self._tree
1830 headers.append((_TREE_HEADER, tree_bytes))
1831 for p in self._parents:
1832 headers.append((_PARENT_HEADER, p))
1833 assert self._author is not None
1834 assert self._author_time is not None
1835 assert self._author_timezone is not None
1836 assert self._author_timezone_neg_utc is not None
1837 headers.append(
1838 (
1839 _AUTHOR_HEADER,
1840 format_time_entry(
1841 self._author,
1842 self._author_time,
1843 (self._author_timezone, self._author_timezone_neg_utc),
1844 ),
1845 )
1846 )
1847 assert self._committer is not None
1848 assert self._commit_time is not None
1849 assert self._commit_timezone is not None
1850 assert self._commit_timezone_neg_utc is not None
1851 headers.append(
1852 (
1853 _COMMITTER_HEADER,
1854 format_time_entry(
1855 self._committer,
1856 self._commit_time,
1857 (self._commit_timezone, self._commit_timezone_neg_utc),
1858 ),
1859 )
1860 )
1861 if self.encoding:
1862 headers.append((_ENCODING_HEADER, self.encoding))
1863 for mergetag in self.mergetag:
1864 headers.append((_MERGETAG_HEADER, mergetag.as_raw_string()[:-1]))
1865 headers.extend(
1866 (field, value) for field, value in self._extra if value is not None
1867 )
1868 if self.gpgsig:
1869 headers.append((_GPGSIG_HEADER, self.gpgsig))
1870 return list(_format_message(headers, self._message))
1872 tree = serializable_property("tree", "Tree that is the state of this commit")
1874 def _get_parents(self) -> list[bytes]:
1875 """Return a list of parents of this commit."""
1876 return self._parents
1878 def _set_parents(self, value: list[bytes]) -> None:
1879 """Set a list of parents of this commit."""
1880 self._needs_serialization = True
1881 self._parents = value
1883 parents = property(
1884 _get_parents,
1885 _set_parents,
1886 doc="Parents of this commit, by their SHA1.",
1887 )
1889 @replace_me(since="0.21.0", remove_in="0.24.0")
1890 def _get_extra(self) -> list[tuple[bytes, Optional[bytes]]]:
1891 """Return extra settings of this commit."""
1892 return self._extra
1894 extra = property(
1895 _get_extra,
1896 doc="Extra header fields not understood (presumably added in a "
1897 "newer version of git). Kept verbatim so the object can "
1898 "be correctly reserialized. For private commit metadata, use "
1899 "pseudo-headers in Commit.message, rather than this field.",
1900 )
1902 author = serializable_property("author", "The name of the author of the commit")
1904 committer = serializable_property(
1905 "committer", "The name of the committer of the commit"
1906 )
1908 message = serializable_property("message", "The commit message")
1910 commit_time = serializable_property(
1911 "commit_time",
1912 "The timestamp of the commit. As the number of seconds since the epoch.",
1913 )
1915 commit_timezone = serializable_property(
1916 "commit_timezone", "The zone the commit time is in"
1917 )
1919 author_time = serializable_property(
1920 "author_time",
1921 "The timestamp the commit was written. As the number of "
1922 "seconds since the epoch.",
1923 )
1925 author_timezone = serializable_property(
1926 "author_timezone", "Returns the zone the author time is in."
1927 )
1929 encoding = serializable_property("encoding", "Encoding of the commit message.")
1931 mergetag = serializable_property("mergetag", "Associated signed tag.")
1933 gpgsig = serializable_property("gpgsig", "GPG Signature.")
1936OBJECT_CLASSES = (
1937 Commit,
1938 Tree,
1939 Blob,
1940 Tag,
1941)
1943_TYPE_MAP: dict[Union[bytes, int], type[ShaFile]] = {}
1945for cls in OBJECT_CLASSES:
1946 _TYPE_MAP[cls.type_name] = cls
1947 _TYPE_MAP[cls.type_num] = cls
1950# Hold on to the pure-python implementations for testing
1951_parse_tree_py = parse_tree
1952_sorted_tree_items_py = sorted_tree_items
1953try:
1954 # Try to import Rust versions
1955 from dulwich._objects import (
1956 parse_tree as _parse_tree_rs,
1957 )
1958 from dulwich._objects import (
1959 sorted_tree_items as _sorted_tree_items_rs,
1960 )
1961except ImportError:
1962 pass
1963else:
1964 parse_tree = _parse_tree_rs
1965 sorted_tree_items = _sorted_tree_items_rs