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 import namedtuple
32from collections.abc import Callable, Iterable, Iterator
33from hashlib import sha1
34from io import BufferedIOBase, BytesIO
35from typing import (
36 IO,
37 TYPE_CHECKING,
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("TreeEntry", ["path", "mode", "sha"])):
1113 """Named tuple encapsulating a single tree entry."""
1115 def in_path(self, path: bytes) -> "TreeEntry":
1116 """Return a copy of this entry with the given path prepended."""
1117 if not isinstance(self.path, bytes):
1118 raise TypeError(f"Expected bytes for path, got {path!r}")
1119 return TreeEntry(posixpath.join(path, self.path), self.mode, self.sha)
1122def parse_tree(text: bytes, strict: bool = False) -> Iterator[tuple[bytes, int, bytes]]:
1123 """Parse a tree text.
1125 Args:
1126 text: Serialized text to parse
1127 strict: If True, enforce strict validation
1128 Returns: iterator of tuples of (name, mode, sha)
1130 Raises:
1131 ObjectFormatException: if the object was malformed in some way
1132 """
1133 count = 0
1134 length = len(text)
1135 while count < length:
1136 mode_end = text.index(b" ", count)
1137 mode_text = text[count:mode_end]
1138 if strict and mode_text.startswith(b"0"):
1139 raise ObjectFormatException(f"Invalid mode {mode_text!r}")
1140 try:
1141 mode = int(mode_text, 8)
1142 except ValueError as exc:
1143 raise ObjectFormatException(f"Invalid mode {mode_text!r}") from exc
1144 name_end = text.index(b"\0", mode_end)
1145 name = text[mode_end + 1 : name_end]
1146 count = name_end + 21
1147 sha = text[name_end + 1 : count]
1148 if len(sha) != 20:
1149 raise ObjectFormatException("Sha has invalid length")
1150 hexsha = sha_to_hex(sha)
1151 yield (name, mode, hexsha)
1154def serialize_tree(items: Iterable[tuple[bytes, int, bytes]]) -> Iterator[bytes]:
1155 """Serialize the items in a tree to a text.
1157 Args:
1158 items: Sorted iterable over (name, mode, sha) tuples
1159 Returns: Serialized tree text as chunks
1160 """
1161 for name, mode, hexsha in items:
1162 yield (
1163 (f"{mode:04o}").encode("ascii") + b" " + name + b"\0" + hex_to_sha(hexsha)
1164 )
1167def sorted_tree_items(
1168 entries: dict[bytes, tuple[int, bytes]], name_order: bool
1169) -> Iterator[TreeEntry]:
1170 """Iterate over a tree entries dictionary.
1172 Args:
1173 name_order: If True, iterate entries in order of their name. If
1174 False, iterate entries in tree order, that is, treat subtree entries as
1175 having '/' appended.
1176 entries: Dictionary mapping names to (mode, sha) tuples
1177 Returns: Iterator over (name, mode, hexsha)
1178 """
1179 if name_order:
1180 key_func = key_entry_name_order
1181 else:
1182 key_func = key_entry
1183 for name, entry in sorted(entries.items(), key=key_func):
1184 mode, hexsha = entry
1185 # Stricter type checks than normal to mirror checks in the Rust version.
1186 mode = int(mode)
1187 if not isinstance(hexsha, bytes):
1188 raise TypeError(f"Expected bytes for SHA, got {hexsha!r}")
1189 yield TreeEntry(name, mode, hexsha)
1192def key_entry(entry: tuple[bytes, tuple[int, ObjectID]]) -> bytes:
1193 """Sort key for tree entry.
1195 Args:
1196 entry: (name, value) tuple
1197 """
1198 (name, (mode, _sha)) = entry
1199 if stat.S_ISDIR(mode):
1200 name += b"/"
1201 return name
1204def key_entry_name_order(entry: tuple[bytes, tuple[int, ObjectID]]) -> bytes:
1205 """Sort key for tree entry in name order."""
1206 return entry[0]
1209def pretty_format_tree_entry(
1210 name: bytes, mode: int, hexsha: bytes, encoding: str = "utf-8"
1211) -> str:
1212 """Pretty format tree entry.
1214 Args:
1215 name: Name of the directory entry
1216 mode: Mode of entry
1217 hexsha: Hexsha of the referenced object
1218 encoding: Character encoding for the name
1219 Returns: string describing the tree entry
1220 """
1221 if mode & stat.S_IFDIR:
1222 kind = "tree"
1223 else:
1224 kind = "blob"
1225 return "{:04o} {} {}\t{}\n".format(
1226 mode,
1227 kind,
1228 hexsha.decode("ascii"),
1229 name.decode(encoding, "replace"),
1230 )
1233class SubmoduleEncountered(Exception):
1234 """A submodule was encountered while resolving a path."""
1236 def __init__(self, path: bytes, sha: ObjectID) -> None:
1237 """Initialize SubmoduleEncountered exception.
1239 Args:
1240 path: Path where the submodule was encountered
1241 sha: SHA of the submodule
1242 """
1243 self.path = path
1244 self.sha = sha
1247class Tree(ShaFile):
1248 """A Git tree object."""
1250 type_name = b"tree"
1251 type_num = 2
1253 __slots__ = "_entries"
1255 def __init__(self) -> None:
1256 """Initialize an empty Tree."""
1257 super().__init__()
1258 self._entries: dict[bytes, tuple[int, bytes]] = {}
1260 @classmethod
1261 def from_path(cls, filename: Union[str, bytes]) -> "Tree":
1262 """Read a tree from a file on disk.
1264 Args:
1265 filename: Path to the tree file
1267 Returns:
1268 A Tree object
1270 Raises:
1271 NotTreeError: If the file is not a tree
1272 """
1273 tree = ShaFile.from_path(filename)
1274 if not isinstance(tree, cls):
1275 raise NotTreeError(_path_to_bytes(filename))
1276 return tree
1278 def __contains__(self, name: bytes) -> bool:
1279 """Check if name exists in tree."""
1280 return name in self._entries
1282 def __getitem__(self, name: bytes) -> tuple[int, ObjectID]:
1283 """Get tree entry by name."""
1284 return self._entries[name]
1286 def __setitem__(self, name: bytes, value: tuple[int, ObjectID]) -> None:
1287 """Set a tree entry by name.
1289 Args:
1290 name: The name of the entry, as a string.
1291 value: A tuple of (mode, hexsha), where mode is the mode of the
1292 entry as an integral type and hexsha is the hex SHA of the entry as
1293 a string.
1294 """
1295 mode, hexsha = value
1296 self._entries[name] = (mode, hexsha)
1297 self._needs_serialization = True
1299 def __delitem__(self, name: bytes) -> None:
1300 """Delete tree entry by name."""
1301 del self._entries[name]
1302 self._needs_serialization = True
1304 def __len__(self) -> int:
1305 """Return number of entries in tree."""
1306 return len(self._entries)
1308 def __iter__(self) -> Iterator[bytes]:
1309 """Iterate over tree entry names."""
1310 return iter(self._entries)
1312 def add(self, name: bytes, mode: int, hexsha: bytes) -> None:
1313 """Add an entry to the tree.
1315 Args:
1316 mode: The mode of the entry as an integral type. Not all
1317 possible modes are supported by git; see check() for details.
1318 name: The name of the entry, as a string.
1319 hexsha: The hex SHA of the entry as a string.
1320 """
1321 self._entries[name] = mode, hexsha
1322 self._needs_serialization = True
1324 def iteritems(self, name_order: bool = False) -> Iterator[TreeEntry]:
1325 """Iterate over entries.
1327 Args:
1328 name_order: If True, iterate in name order instead of tree
1329 order.
1330 Returns: Iterator over (name, mode, sha) tuples
1331 """
1332 return sorted_tree_items(self._entries, name_order)
1334 def items(self) -> list[TreeEntry]:
1335 """Return the sorted entries in this tree.
1337 Returns: List with (name, mode, sha) tuples
1338 """
1339 return list(self.iteritems())
1341 def _deserialize(self, chunks: list[bytes]) -> None:
1342 """Grab the entries in the tree."""
1343 try:
1344 parsed_entries = parse_tree(b"".join(chunks))
1345 except ValueError as exc:
1346 raise ObjectFormatException(exc) from exc
1347 # TODO: list comprehension is for efficiency in the common (small)
1348 # case; if memory efficiency in the large case is a concern, use a
1349 # genexp.
1350 self._entries = {n: (m, s) for n, m, s in parsed_entries}
1352 def check(self) -> None:
1353 """Check this object for internal consistency.
1355 Raises:
1356 ObjectFormatException: if the object is malformed in some way
1357 """
1358 super().check()
1359 assert self._chunked_text is not None
1360 last = None
1361 allowed_modes = (
1362 stat.S_IFREG | 0o755,
1363 stat.S_IFREG | 0o644,
1364 stat.S_IFLNK,
1365 stat.S_IFDIR,
1366 S_IFGITLINK,
1367 # TODO: optionally exclude as in git fsck --strict
1368 stat.S_IFREG | 0o664,
1369 )
1370 for name, mode, sha in parse_tree(b"".join(self._chunked_text), True):
1371 check_hexsha(sha, f"invalid sha {sha!r}")
1372 if b"/" in name or name in (b"", b".", b"..", b".git"):
1373 raise ObjectFormatException(
1374 "invalid name {}".format(name.decode("utf-8", "replace"))
1375 )
1377 if mode not in allowed_modes:
1378 raise ObjectFormatException(f"invalid mode {mode:06o}")
1380 entry = (name, (mode, sha))
1381 if last:
1382 if key_entry(last) > key_entry(entry):
1383 raise ObjectFormatException("entries not sorted")
1384 if name == last[0]:
1385 raise ObjectFormatException(f"duplicate entry {name!r}")
1386 last = entry
1388 def _serialize(self) -> list[bytes]:
1389 return list(serialize_tree(self.iteritems()))
1391 def as_pretty_string(self) -> str:
1392 """Return a human-readable string representation of this tree.
1394 Returns:
1395 Pretty-printed tree entries
1396 """
1397 text: list[str] = []
1398 for name, mode, hexsha in self.iteritems():
1399 text.append(pretty_format_tree_entry(name, mode, hexsha))
1400 return "".join(text)
1402 def lookup_path(
1403 self, lookup_obj: Callable[[ObjectID], ShaFile], path: bytes
1404 ) -> tuple[int, ObjectID]:
1405 """Look up an object in a Git tree.
1407 Args:
1408 lookup_obj: Callback for retrieving object by SHA1
1409 path: Path to lookup
1410 Returns: A tuple of (mode, SHA) of the resulting path.
1411 """
1412 # Handle empty path - return the tree itself
1413 if not path:
1414 return stat.S_IFDIR, self.id
1416 parts = path.split(b"/")
1417 sha = self.id
1418 mode: Optional[int] = None
1419 for i, p in enumerate(parts):
1420 if not p:
1421 continue
1422 if mode is not None and S_ISGITLINK(mode):
1423 raise SubmoduleEncountered(b"/".join(parts[:i]), sha)
1424 obj = lookup_obj(sha)
1425 if not isinstance(obj, Tree):
1426 raise NotTreeError(sha)
1427 mode, sha = obj[p]
1428 if mode is None:
1429 raise ValueError("No valid path found")
1430 return mode, sha
1433def parse_timezone(text: bytes) -> tuple[int, bool]:
1434 """Parse a timezone text fragment (e.g. '+0100').
1436 Args:
1437 text: Text to parse.
1438 Returns: Tuple with timezone as seconds difference to UTC
1439 and a boolean indicating whether this was a UTC timezone
1440 prefixed with a negative sign (-0000).
1441 """
1442 # cgit parses the first character as the sign, and the rest
1443 # as an integer (using strtol), which could also be negative.
1444 # We do the same for compatibility. See #697828.
1445 if text[0] not in b"+-":
1446 raise ValueError("Timezone must start with + or - ({text})".format(**vars()))
1447 sign = text[:1]
1448 offset = int(text[1:])
1449 if sign == b"-":
1450 offset = -offset
1451 unnecessary_negative_timezone = offset >= 0 and sign == b"-"
1452 signum = ((offset < 0) and -1) or 1
1453 offset = abs(offset)
1454 hours = int(offset / 100)
1455 minutes = offset % 100
1456 return (
1457 signum * (hours * 3600 + minutes * 60),
1458 unnecessary_negative_timezone,
1459 )
1462def format_timezone(offset: int, unnecessary_negative_timezone: bool = False) -> bytes:
1463 """Format a timezone for Git serialization.
1465 Args:
1466 offset: Timezone offset as seconds difference to UTC
1467 unnecessary_negative_timezone: Whether to use a minus sign for
1468 UTC or positive timezones (-0000 and --700 rather than +0000 / +0700).
1469 """
1470 if offset % 60 != 0:
1471 raise ValueError("Unable to handle non-minute offset.")
1472 if offset < 0 or unnecessary_negative_timezone:
1473 sign = "-"
1474 offset = -offset
1475 else:
1476 sign = "+"
1477 return ("%c%02d%02d" % (sign, offset / 3600, (offset / 60) % 60)).encode("ascii") # noqa: UP031
1480def parse_time_entry(
1481 value: bytes,
1482) -> tuple[bytes, Optional[int], tuple[Optional[int], bool]]:
1483 """Parse event.
1485 Args:
1486 value: Bytes representing a git commit/tag line
1487 Raises:
1488 ObjectFormatException in case of parsing error (malformed
1489 field date)
1490 Returns: Tuple of (author, time, (timezone, timezone_neg_utc))
1491 """
1492 try:
1493 sep = value.rindex(b"> ")
1494 except ValueError:
1495 return (value, None, (None, False))
1496 try:
1497 person = value[0 : sep + 1]
1498 rest = value[sep + 2 :]
1499 timetext, timezonetext = rest.rsplit(b" ", 1)
1500 time = int(timetext)
1501 timezone, timezone_neg_utc = parse_timezone(timezonetext)
1502 except ValueError as exc:
1503 raise ObjectFormatException(exc) from exc
1504 return person, time, (timezone, timezone_neg_utc)
1507def format_time_entry(
1508 person: bytes, time: int, timezone_info: tuple[int, bool]
1509) -> bytes:
1510 """Format an event."""
1511 (timezone, timezone_neg_utc) = timezone_info
1512 return b" ".join(
1513 [person, str(time).encode("ascii"), format_timezone(timezone, timezone_neg_utc)]
1514 )
1517@replace_me(since="0.21.0", remove_in="0.24.0")
1518def parse_commit(
1519 chunks: Iterable[bytes],
1520) -> tuple[
1521 Optional[bytes],
1522 list[bytes],
1523 tuple[Optional[bytes], Optional[int], tuple[Optional[int], Optional[bool]]],
1524 tuple[Optional[bytes], Optional[int], tuple[Optional[int], Optional[bool]]],
1525 Optional[bytes],
1526 list[Tag],
1527 Optional[bytes],
1528 Optional[bytes],
1529 list[tuple[bytes, bytes]],
1530]:
1531 """Parse a commit object from chunks.
1533 Args:
1534 chunks: Chunks to parse
1535 Returns: Tuple of (tree, parents, author_info, commit_info,
1536 encoding, mergetag, gpgsig, message, extra)
1537 """
1538 parents = []
1539 extra = []
1540 tree = None
1541 author_info: tuple[
1542 Optional[bytes], Optional[int], tuple[Optional[int], Optional[bool]]
1543 ] = (None, None, (None, None))
1544 commit_info: tuple[
1545 Optional[bytes], Optional[int], tuple[Optional[int], Optional[bool]]
1546 ] = (None, None, (None, None))
1547 encoding = None
1548 mergetag = []
1549 message = None
1550 gpgsig = None
1552 for field, value in _parse_message(chunks):
1553 # TODO(jelmer): Enforce ordering
1554 if field == _TREE_HEADER:
1555 tree = value
1556 elif field == _PARENT_HEADER:
1557 if value is None:
1558 raise ObjectFormatException("missing parent value")
1559 parents.append(value)
1560 elif field == _AUTHOR_HEADER:
1561 if value is None:
1562 raise ObjectFormatException("missing author value")
1563 author_info = parse_time_entry(value)
1564 elif field == _COMMITTER_HEADER:
1565 if value is None:
1566 raise ObjectFormatException("missing committer value")
1567 commit_info = parse_time_entry(value)
1568 elif field == _ENCODING_HEADER:
1569 encoding = value
1570 elif field == _MERGETAG_HEADER:
1571 if value is None:
1572 raise ObjectFormatException("missing mergetag value")
1573 tag = Tag.from_string(value + b"\n")
1574 assert isinstance(tag, Tag)
1575 mergetag.append(tag)
1576 elif field == _GPGSIG_HEADER:
1577 gpgsig = value
1578 elif field is None:
1579 message = value
1580 else:
1581 if value is None:
1582 raise ObjectFormatException(f"missing value for field {field!r}")
1583 extra.append((field, value))
1584 return (
1585 tree,
1586 parents,
1587 author_info,
1588 commit_info,
1589 encoding,
1590 mergetag,
1591 gpgsig,
1592 message,
1593 extra,
1594 )
1597class Commit(ShaFile):
1598 """A git commit object."""
1600 type_name = b"commit"
1601 type_num = 1
1603 __slots__ = (
1604 "_author",
1605 "_author_time",
1606 "_author_timezone",
1607 "_author_timezone_neg_utc",
1608 "_commit_time",
1609 "_commit_timezone",
1610 "_commit_timezone_neg_utc",
1611 "_committer",
1612 "_encoding",
1613 "_extra",
1614 "_gpgsig",
1615 "_mergetag",
1616 "_message",
1617 "_parents",
1618 "_tree",
1619 )
1621 def __init__(self) -> None:
1622 """Initialize an empty Commit."""
1623 super().__init__()
1624 self._parents: list[bytes] = []
1625 self._encoding: Optional[bytes] = None
1626 self._mergetag: list[Tag] = []
1627 self._gpgsig: Optional[bytes] = None
1628 self._extra: list[tuple[bytes, Optional[bytes]]] = []
1629 self._author_timezone_neg_utc: Optional[bool] = False
1630 self._commit_timezone_neg_utc: Optional[bool] = False
1632 @classmethod
1633 def from_path(cls, path: Union[str, bytes]) -> "Commit":
1634 """Read a commit from a file on disk.
1636 Args:
1637 path: Path to the commit file
1639 Returns:
1640 A Commit object
1642 Raises:
1643 NotCommitError: If the file is not a commit
1644 """
1645 commit = ShaFile.from_path(path)
1646 if not isinstance(commit, cls):
1647 raise NotCommitError(_path_to_bytes(path))
1648 return commit
1650 def _deserialize(self, chunks: list[bytes]) -> None:
1651 self._parents = []
1652 self._extra = []
1653 self._tree = None
1654 author_info: tuple[
1655 Optional[bytes], Optional[int], tuple[Optional[int], Optional[bool]]
1656 ] = (None, None, (None, None))
1657 commit_info: tuple[
1658 Optional[bytes], Optional[int], tuple[Optional[int], Optional[bool]]
1659 ] = (None, None, (None, None))
1660 self._encoding = None
1661 self._mergetag = []
1662 self._message = None
1663 self._gpgsig = None
1665 for field, value in _parse_message(chunks):
1666 # TODO(jelmer): Enforce ordering
1667 if field == _TREE_HEADER:
1668 self._tree = value
1669 elif field == _PARENT_HEADER:
1670 assert value is not None
1671 self._parents.append(value)
1672 elif field == _AUTHOR_HEADER:
1673 if value is None:
1674 raise ObjectFormatException("missing author value")
1675 author_info = parse_time_entry(value)
1676 elif field == _COMMITTER_HEADER:
1677 if value is None:
1678 raise ObjectFormatException("missing committer value")
1679 commit_info = parse_time_entry(value)
1680 elif field == _ENCODING_HEADER:
1681 self._encoding = value
1682 elif field == _MERGETAG_HEADER:
1683 assert value is not None
1684 tag = Tag.from_string(value + b"\n")
1685 assert isinstance(tag, Tag)
1686 self._mergetag.append(tag)
1687 elif field == _GPGSIG_HEADER:
1688 self._gpgsig = value
1689 elif field is None:
1690 self._message = value
1691 else:
1692 self._extra.append((field, value))
1694 (
1695 self._author,
1696 self._author_time,
1697 (self._author_timezone, self._author_timezone_neg_utc),
1698 ) = author_info
1699 (
1700 self._committer,
1701 self._commit_time,
1702 (self._commit_timezone, self._commit_timezone_neg_utc),
1703 ) = commit_info
1705 def check(self) -> None:
1706 """Check this object for internal consistency.
1708 Raises:
1709 ObjectFormatException: if the object is malformed in some way
1710 """
1711 super().check()
1712 assert self._chunked_text is not None
1713 self._check_has_member("_tree", "missing tree")
1714 self._check_has_member("_author", "missing author")
1715 self._check_has_member("_committer", "missing committer")
1716 self._check_has_member("_author_time", "missing author time")
1717 self._check_has_member("_commit_time", "missing commit time")
1719 for parent in self._parents:
1720 check_hexsha(parent, "invalid parent sha")
1721 assert self._tree is not None # checked by _check_has_member above
1722 check_hexsha(self._tree, "invalid tree sha")
1724 assert self._author is not None # checked by _check_has_member above
1725 assert self._committer is not None # checked by _check_has_member above
1726 check_identity(self._author, "invalid author")
1727 check_identity(self._committer, "invalid committer")
1729 assert self._author_time is not None # checked by _check_has_member above
1730 assert self._commit_time is not None # checked by _check_has_member above
1731 check_time(self._author_time)
1732 check_time(self._commit_time)
1734 last = None
1735 for field, _ in _parse_message(self._chunked_text):
1736 if field == _TREE_HEADER and last is not None:
1737 raise ObjectFormatException("unexpected tree")
1738 elif field == _PARENT_HEADER and last not in (
1739 _PARENT_HEADER,
1740 _TREE_HEADER,
1741 ):
1742 raise ObjectFormatException("unexpected parent")
1743 elif field == _AUTHOR_HEADER and last not in (
1744 _TREE_HEADER,
1745 _PARENT_HEADER,
1746 ):
1747 raise ObjectFormatException("unexpected author")
1748 elif field == _COMMITTER_HEADER and last != _AUTHOR_HEADER:
1749 raise ObjectFormatException("unexpected committer")
1750 elif field == _ENCODING_HEADER and last != _COMMITTER_HEADER:
1751 raise ObjectFormatException("unexpected encoding")
1752 last = field
1754 # TODO: optionally check for duplicate parents
1756 def sign(self, keyid: Optional[str] = None) -> None:
1757 """Sign this commit with a GPG key.
1759 Args:
1760 keyid: Optional GPG key ID to use for signing. If not specified,
1761 the default GPG key will be used.
1762 """
1763 import gpg
1765 with gpg.Context(armor=True) as c:
1766 if keyid is not None:
1767 key = c.get_key(keyid)
1768 with gpg.Context(armor=True, signers=[key]) as ctx:
1769 self.gpgsig, unused_result = ctx.sign(
1770 self.as_raw_string(),
1771 mode=gpg.constants.sig.mode.DETACH,
1772 )
1773 else:
1774 self.gpgsig, unused_result = c.sign(
1775 self.as_raw_string(), mode=gpg.constants.sig.mode.DETACH
1776 )
1778 def raw_without_sig(self) -> bytes:
1779 """Return raw string serialization without the GPG/SSH signature.
1781 self.gpgsig is a signature for the returned raw byte string serialization.
1782 """
1783 tmp = self.copy()
1784 assert isinstance(tmp, Commit)
1785 tmp._gpgsig = None
1786 tmp.gpgsig = None
1787 return tmp.as_raw_string()
1789 def verify(self, keyids: Optional[Iterable[str]] = None) -> None:
1790 """Verify GPG signature for this commit (if it is signed).
1792 Args:
1793 keyids: Optional iterable of trusted keyids for this commit.
1794 If this commit is not signed by any key in keyids verification will
1795 fail. If not specified, this function only verifies that the commit
1796 has a valid signature.
1798 Raises:
1799 gpg.errors.BadSignatures: if GPG signature verification fails
1800 gpg.errors.MissingSignatures: if commit was not signed by a key
1801 specified in keyids
1802 """
1803 if self._gpgsig is None:
1804 return
1806 import gpg
1808 with gpg.Context() as ctx:
1809 data, result = ctx.verify(
1810 self.raw_without_sig(),
1811 signature=self._gpgsig,
1812 )
1813 if keyids:
1814 keys = [ctx.get_key(key) for key in keyids]
1815 for key in keys:
1816 for subkey in keys:
1817 for sig in result.signatures:
1818 if subkey.can_sign and subkey.fpr == sig.fpr:
1819 return
1820 raise gpg.errors.MissingSignatures(result, keys, results=(data, result))
1822 def _serialize(self) -> list[bytes]:
1823 headers = []
1824 assert self._tree is not None
1825 tree_bytes = self._tree.id if isinstance(self._tree, Tree) else self._tree
1826 headers.append((_TREE_HEADER, tree_bytes))
1827 for p in self._parents:
1828 headers.append((_PARENT_HEADER, p))
1829 assert self._author is not None
1830 assert self._author_time is not None
1831 assert self._author_timezone is not None
1832 assert self._author_timezone_neg_utc is not None
1833 headers.append(
1834 (
1835 _AUTHOR_HEADER,
1836 format_time_entry(
1837 self._author,
1838 self._author_time,
1839 (self._author_timezone, self._author_timezone_neg_utc),
1840 ),
1841 )
1842 )
1843 assert self._committer is not None
1844 assert self._commit_time is not None
1845 assert self._commit_timezone is not None
1846 assert self._commit_timezone_neg_utc is not None
1847 headers.append(
1848 (
1849 _COMMITTER_HEADER,
1850 format_time_entry(
1851 self._committer,
1852 self._commit_time,
1853 (self._commit_timezone, self._commit_timezone_neg_utc),
1854 ),
1855 )
1856 )
1857 if self.encoding:
1858 headers.append((_ENCODING_HEADER, self.encoding))
1859 for mergetag in self.mergetag:
1860 headers.append((_MERGETAG_HEADER, mergetag.as_raw_string()[:-1]))
1861 headers.extend(
1862 (field, value) for field, value in self._extra if value is not None
1863 )
1864 if self.gpgsig:
1865 headers.append((_GPGSIG_HEADER, self.gpgsig))
1866 return list(_format_message(headers, self._message))
1868 tree = serializable_property("tree", "Tree that is the state of this commit")
1870 def _get_parents(self) -> list[bytes]:
1871 """Return a list of parents of this commit."""
1872 return self._parents
1874 def _set_parents(self, value: list[bytes]) -> None:
1875 """Set a list of parents of this commit."""
1876 self._needs_serialization = True
1877 self._parents = value
1879 parents = property(
1880 _get_parents,
1881 _set_parents,
1882 doc="Parents of this commit, by their SHA1.",
1883 )
1885 @replace_me(since="0.21.0", remove_in="0.24.0")
1886 def _get_extra(self) -> list[tuple[bytes, Optional[bytes]]]:
1887 """Return extra settings of this commit."""
1888 return self._extra
1890 extra = property(
1891 _get_extra,
1892 doc="Extra header fields not understood (presumably added in a "
1893 "newer version of git). Kept verbatim so the object can "
1894 "be correctly reserialized. For private commit metadata, use "
1895 "pseudo-headers in Commit.message, rather than this field.",
1896 )
1898 author = serializable_property("author", "The name of the author of the commit")
1900 committer = serializable_property(
1901 "committer", "The name of the committer of the commit"
1902 )
1904 message = serializable_property("message", "The commit message")
1906 commit_time = serializable_property(
1907 "commit_time",
1908 "The timestamp of the commit. As the number of seconds since the epoch.",
1909 )
1911 commit_timezone = serializable_property(
1912 "commit_timezone", "The zone the commit time is in"
1913 )
1915 author_time = serializable_property(
1916 "author_time",
1917 "The timestamp the commit was written. As the number of "
1918 "seconds since the epoch.",
1919 )
1921 author_timezone = serializable_property(
1922 "author_timezone", "Returns the zone the author time is in."
1923 )
1925 encoding = serializable_property("encoding", "Encoding of the commit message.")
1927 mergetag = serializable_property("mergetag", "Associated signed tag.")
1929 gpgsig = serializable_property("gpgsig", "GPG Signature.")
1932OBJECT_CLASSES = (
1933 Commit,
1934 Tree,
1935 Blob,
1936 Tag,
1937)
1939_TYPE_MAP: dict[Union[bytes, int], type[ShaFile]] = {}
1941for cls in OBJECT_CLASSES:
1942 _TYPE_MAP[cls.type_name] = cls
1943 _TYPE_MAP[cls.type_num] = cls
1946# Hold on to the pure-python implementations for testing
1947_parse_tree_py = parse_tree
1948_sorted_tree_items_py = sorted_tree_items
1949try:
1950 # Try to import Rust versions
1951 from dulwich._objects import (
1952 parse_tree as _parse_tree_rs,
1953 )
1954 from dulwich._objects import (
1955 sorted_tree_items as _sorted_tree_items_rs,
1956 )
1957except ImportError:
1958 pass
1959else:
1960 parse_tree = _parse_tree_rs
1961 sorted_tree_items = _sorted_tree_items_rs