gitpane 1.0.0__py3-none-any.whl

gitpane/history/history_parse.py

@@ -0,0 +1,605 @@
+"""Parse the answers of Git's history reads into repository values."""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from gitpane.config import (
+    CAT_FILE_HEADER_LIMIT_BYTES,
+    COMMIT_HEADER_LIMIT_BYTES,
+    COMMIT_LIMIT_BYTES,
+    COMMIT_PREVIEW_LIMIT_CHARS,
+    COMMIT_SUBJECT_LIMIT_CHARS,
+    PARSING_BACKLOG_LIMIT_BYTES,
+    SharedText,
+)
+from gitpane.history.repository_value import Commit, CommitLink, FileStatus, HistorySnapshot, RevisionEntry, TreeEntry, file_status, validate_oid
+from gitpane.text.text_query import TextQuery
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+def parse_tree_entries(output: bytes) -> list[TreeEntry]:
+    """Split only Git's NUL records and first tab, preserving arbitrary path bytes."""
+    if output and not output.endswith(b"\0"):
+        raise ValueError("Incomplete tree record")
+    entries = []
+    for record in output.split(b"\0"):
+        if not record:
+            continue
+        header, separator, path = record.partition(b"\t")
+        mode, object_type, oid = header.decode("ascii").split()
+        if not separator or not path or object_type not in ("blob", "commit"):
+            raise ValueError("Invalid tree record")
+        entries.append(TreeEntry(path, mode, object_type, validate_oid(oid)))
+    entries.sort(key=lambda entry: entry.path)
+    return entries
+
+
+def parse_revision_entries(output: bytes, commit_oid: str, parent_oid: str | None) -> list[RevisionEntry]:
+    """Decode NUL-delimited raw changes while preserving arbitrary Git path bytes."""
+    fields = iter(output.split(b"\0"))
+    entries = []
+    for header in fields:
+        if not header:
+            continue
+        if not header.startswith(b":"):
+            raise ValueError("Invalid changed-file record")
+        old_mode, new_mode, old_blob, new_blob, raw_status = header[1:].decode("ascii").split()
+        status = file_status(raw_status)
+        old_blob_oid = None if set(old_blob) == {"0"} else validate_oid(old_blob)
+        new_blob_oid = None if set(new_blob) == {"0"} else validate_oid(new_blob)
+        try:
+            old_path = new_path = next(fields)
+            if status in (FileStatus.RENAMED, FileStatus.COPIED):
+                new_path = next(fields)
+        except StopIteration as error:
+            raise ValueError("Incomplete changed-file record") from error
+        entries.append(RevisionEntry(commit_oid, parent_oid, old_path if old_blob_oid else None, new_path if new_blob_oid else None,
+                                     old_blob_oid, new_blob_oid, old_mode, new_mode, status))
+    return entries
+
+
+def parse_history_comparisons(output: bytes, comparisons: list[tuple[str | None, str]]) -> dict[tuple[str | None, str], list[RevisionEntry]]:
+    """Validate explicitly identified raw comparisons without treating path bytes as framing."""
+    expected_comparison_set = set(comparisons)
+    entry_by_comparison: dict[tuple[str | None, str], list[RevisionEntry]] = {}
+    fields = iter(output.split(b"\0"))
+    comparison = None
+    for token in fields:
+        header = token.lstrip(b"\n")
+        if not header:
+            continue
+        if not header.startswith(b":"):
+            child_oid = validate_oid(header.decode("ascii"))
+            try:
+                parent = next(fields).decode("ascii")
+            except StopIteration as error:
+                raise ValueError("Incomplete file-history comparison identity") from error
+            parent_oid = validate_oid(parent) if parent else None
+            comparison = (parent_oid, child_oid)
+            if comparison not in expected_comparison_set or comparison in entry_by_comparison:
+                raise ValueError("Unexpected file-history comparison identity")
+            entry_by_comparison[comparison] = []
+            continue
+        if comparison is None:
+            raise ValueError("Missing file-history comparison identity")
+        try:
+            paths = [next(fields)]
+            status_index = -1
+            status = file_status(header.rsplit(b" ", maxsplit=1)[status_index].decode("ascii"))
+            if status in (FileStatus.RENAMED, FileStatus.COPIED):
+                paths.append(next(fields))
+        except StopIteration as error:
+            raise ValueError("Incomplete file-history changed path") from error
+        if not all(paths):
+            raise ValueError("Empty file-history changed path")
+        parent_oid, child_oid = comparison
+        entry_by_comparison[comparison].extend(parse_revision_entries(b"\0".join([header, *paths, b""]), child_oid, parent_oid))
+    if output and not output.endswith(b"\0"):
+        raise ValueError("Incomplete file-history comparison output")
+    if set(entry_by_comparison) != expected_comparison_set:
+        raise ValueError("Missing file-history comparisons")
+    return entry_by_comparison
+
+
+# The encoding Git assumes for a commit whose object declares none.
+DEFAULT_COMMIT_ENCODING = "UTF-8"
+REPLACEMENT_ENCODING = "utf-8"
+UNKNOWN_ENCODING_SUFFIX = " (unknown, UTF-8 replacement)"
+ENCODING_PROBE_BYTES = b"a"
+UNAVAILABLE_COMMIT_TIMESTAMP = 0
+COMMIT_TIME_UNAVAILABLE_CAUSE = "author or committer time is missing or invalid"
+COMMIT_TIME_PATTERN = re.compile(rb"-?\d+")
+IDENTITY_PATTERN = re.compile(rb"(.*) <(.*)> (-?\d+) [+-]\d{4}")
+IDENTITY_NAME_EMAIL_PATTERN = re.compile(rb"(.*) <(.*?)>")
+IDENTITY_NAME_GROUP = 1
+IDENTITY_EMAIL_GROUP = 2
+IDENTITY_TIME_GROUP = 3
+
+
+def decode_commit_fields(oid: str, short_oid: str, parent_oids: list[str], author_name: bytes, author_email: bytes, author_timestamp: int | None,
+                         committer_timestamp: int | None, encoding: bytes | None, message: bytes, *, converted_to_utf8: bool = False) -> Commit:
+    """Build a commit from the bytes of its fields, decoding the message and the author with the commit's own encoding.
+
+    Both the raw object reader and the history stream go through here, so a commit reads the same whichever way it
+    arrived. A missing encoding means UTF-8; an encoding Python does not know is replaced by UTF-8 and says so in the
+    commit's encoding label.
+
+    ``converted_to_utf8`` says Git was asked to convert the text to UTF-8 before handing it over, as the history stream
+    does. Git leaves the bytes as they are when its own converter does not know the encoding, so text that is not
+    valid UTF-8 is then decoded with the declared encoding, exactly as the raw object would be.
+
+    A time given as None could not be read: the commit keeps everything else and says its time is unavailable.
+    """
+    encoding_label = DEFAULT_COMMIT_ENCODING if encoding is None else encoding.decode("ascii", "replace")
+    try:
+        # Python skips the codec lookup for empty bytes, so a one-byte probe is what tells an unknown or non-text encoding.
+        ENCODING_PROBE_BYTES.decode(encoding_label, "replace")
+        text_encoding = encoding_label
+    # An unknown name raises LookupError. Python also knows names it refuses for text: "undefined" refuses everything
+    # and "idna" refuses the replace handler, both with UnicodeError, and a name holding a NUL byte raises ValueError.
+    # Every one of them is read as an unknown encoding.
+    except (LookupError, ValueError):
+        text_encoding = REPLACEMENT_ENCODING
+        encoding_label += UNKNOWN_ENCODING_SUFFIX
+    field_texts: list[str] = []
+    for value in (message, author_name, author_email):
+        field_texts.append(decode_commit_text(value, text_encoding, converted_to_utf8))
+    decoded_message, decoded_author_name, decoded_author_email = field_texts
+    if author_timestamp is None or committer_timestamp is None:
+        return Commit(oid, short_oid, parent_oids, decoded_author_name, decoded_author_email, UNAVAILABLE_COMMIT_TIMESTAMP, UNAVAILABLE_COMMIT_TIMESTAMP,
+                      encoding_label, decoded_message, time_unavailable=True)
+    return Commit(oid, short_oid, parent_oids, decoded_author_name, decoded_author_email, author_timestamp, committer_timestamp, encoding_label, decoded_message)
+
+
+def readable_commit_time(value: bytes) -> int | None:
+    """Read one commit time, or answer None when it is not a whole number of seconds a date can hold on this platform.
+
+    Git copies the raw time of the object as it is, so a value can lie far beyond any date; Windows also refuses dates
+    after the year 3000 and long before 1970, and every display of a commit turns its time into a date.
+    """
+    if COMMIT_TIME_PATTERN.fullmatch(value) is None:
+        return None
+    timestamp = int(value)
+    try:
+        datetime.fromtimestamp(timestamp, UTC)
+    except (ValueError, OverflowError, OSError):
+        return None
+    return timestamp
+
+
+def decode_commit_text(value: bytes, text_encoding: str, converted_to_utf8: bool) -> str:
+    """Decode one text field of a commit: as UTF-8 when Git converted it, otherwise with the commit's encoding, never failing."""
+    if converted_to_utf8:
+        try:
+            return value.decode(REPLACEMENT_ENCODING)
+        except UnicodeDecodeError:
+            pass
+    return value.decode(text_encoding, "replace")
+
+
+def oversized_commit_cause(object_limit_bytes: int) -> str:
+    """Name the cause of a commit whose message or header is too large to keep, the same whichever read met it."""
+    return f"message exceeds {object_limit_bytes} bytes or its header is too large"
+
+
+def unavailable_commit(oid: str, short_oid: str, parent_oids: list[str], cause: str) -> Commit:
+    """Stand in for a commit whose details cannot be kept: its row stays, its details say why they are missing.
+
+    The caller names the cause, since a message too large and a time Git could not give lead to the same row.
+    """
+    error = SharedText.DETAIL_UNAVAILABLE.value + " : " + cause
+    return Commit(oid, short_oid, parent_oids, "", "", UNAVAILABLE_COMMIT_TIMESTAMP, UNAVAILABLE_COMMIT_TIMESTAMP, DEFAULT_COMMIT_ENCODING, error, error)
+
+
+def parse_identity(value: bytes) -> tuple[bytes, bytes, int | None]:
+    """Split an author or committer header into name, e-mail and time, keeping what is readable of an identity Git accepted.
+
+    A missing or unreadable time gives None, and an identity without its ``<e-mail>`` part gives an empty name and
+    e-mail, as Git's own log shows such a commit.
+    """
+    identity = IDENTITY_PATTERN.fullmatch(value)
+    if identity is not None:
+        return identity.group(IDENTITY_NAME_GROUP), identity.group(IDENTITY_EMAIL_GROUP), readable_commit_time(identity.group(IDENTITY_TIME_GROUP))
+    name_and_email = IDENTITY_NAME_EMAIL_PATTERN.match(value)
+    if name_and_email is None:
+        return b"", b"", None
+    return name_and_email.group(IDENTITY_NAME_GROUP), name_and_email.group(IDENTITY_EMAIL_GROUP), None
+
+
+def parse_commit(oid: str, raw: bytes, short_oid: str) -> Commit:
+    """Decode an exact commit object without changing its message or ancestry.
+
+    The ancestry stays strict; an unreadable identity or time only costs the commit its dates, as in the history stream.
+    """
+    header, separator, message = raw.partition(b"\n\n")
+    if not separator:
+        raise ValueError("Incomplete commit header")
+    value_by_key: dict[bytes, bytes] = {}
+    parent_oids = []
+    for line in header.splitlines():
+        key, _, value = line.partition(b" ")
+        if key == b"parent":
+            parent_oids.append(validate_oid(value.decode("ascii")))
+        elif not line.startswith(b" "):
+            value_by_key[key] = value
+    author_name, author_email, author_timestamp = parse_identity(value_by_key.get(b"author", b""))
+    _committer_name, _committer_email, committer_timestamp = parse_identity(value_by_key.get(b"committer", b""))
+    return decode_commit_fields(oid, short_oid, parent_oids, author_name, author_email, author_timestamp, committer_timestamp,
+                                value_by_key.get(b"encoding"), message)
+
+
+# The characters Git's own isspace() accepts; Python's str.isspace() accepts many more.
+GIT_WHITESPACE = " \t\n\r"
+GIT_MESSAGE_END = "\0"
+
+
+def commit_subject(message: str) -> str:
+    """Answer the subject Git's %s format shows for a commit message.
+
+    Git skips the blank lines at the start, takes the first paragraph, drops the trailing whitespace of each of its
+    lines and joins them with one space; its message handling stops at the first NUL character. A cached commit shows
+    the same text for its parent as asking Git would.
+    """
+    lines = message.split(GIT_MESSAGE_END, 1)[0].split("\n")
+    index = 0
+    while index < len(lines) and not lines[index].rstrip(GIT_WHITESPACE):
+        index += 1
+    subject_lines: list[str] = []
+    while index < len(lines):
+        line = lines[index].rstrip(GIT_WHITESPACE)
+        if not line:
+            break
+        subject_lines.append(line)
+        index += 1
+    return " ".join(subject_lines)
+
+
+def relation_link(commit: Commit) -> CommitLink:
+    """Describe a direct relative from its full commit: Git's abbreviation and the first line of its message."""
+    subject, _, _body = commit.message.partition("\n")
+    return CommitLink(commit.oid, commit.short_oid, commit.detail_error or subject, not bool(commit.detail_error))
+
+
+def parse_presence_answer(output: bytes, oids: list[str]) -> dict[str, str]:
+    """Read one presence check, matching Git's answers to the requested object IDs rather than to their order.
+
+    Every requested object must be answered exactly once, and nothing else; the answer is its type, or "missing".
+    """
+    requested_oid_set = set(oids)
+    type_by_oid: dict[str, str] = {}
+    for line in output.decode("ascii").splitlines():
+        oid, _separator, object_type = line.partition(" ")
+        validate_oid(oid)
+        if oid not in requested_oid_set or oid in type_by_oid or not object_type:
+            raise ValueError("Unexpected object presence answer")
+        type_by_oid[oid] = object_type
+    if len(type_by_oid) != len(requested_oid_set):
+        raise ValueError("Incomplete object presence answer")
+    return type_by_oid
+
+
+def commit_matches_query(commit: Commit, query: TextQuery, text: str) -> bool:
+    """Tell whether a commit's message matches a search, refusing to guess about a message that could not be read.
+
+    An empty search matches every commit, even one whose details are unavailable; any other search stops there, since
+    it cannot tell whether the missing message would have matched.
+    """
+    if commit.detail_error and text:
+        raise ValueError(commit.detail_error + " ; search incomplete")
+    return query.matches(commit.message)
+
+
+def summarize_commit(commit: Commit) -> Commit:
+    """Retain bounded subject and body snippets in table rows while the full object stays in the cache."""
+    subject, _, body = commit.message.partition("\n")
+    if len(subject) > COMMIT_SUBJECT_LIMIT_CHARS:
+        subject = subject[:COMMIT_SUBJECT_LIMIT_CHARS] + "…"
+    preview = " ".join(body[:COMMIT_PREVIEW_LIMIT_CHARS].split())
+    # Built field by field rather than with dataclasses.replace, which costs several times more and runs once per row
+    # of a history of tens of thousands of commits.
+    return Commit(commit.oid, commit.short_oid, commit.parent_oids, commit.author_name, commit.author_email, commit.author_timestamp,
+                  commit.committer_timestamp, commit.encoding, subject, commit.detail_error, preview, commit.time_unavailable)
+
+
+class CatFileParser:
+    """Frame arbitrary byte fragments using Git's header, exact size and terminal LF."""
+
+    def __init__(self, oids: list[str], object_limit_bytes: int = COMMIT_LIMIT_BYTES, backlog_limit_bytes: int = PARSING_BACKLOG_LIMIT_BYTES,
+                 expected_object_type: str = "commit", body_callback: Callable[[bytes], None] | None = None) -> None:
+        """Capture expected identities and limits before consuming untrusted output."""
+        self.expected_oid_set = set(oids)
+        self.expected_object_type = expected_object_type
+        self.body_callback = body_callback
+        self.size_by_oid: dict[str, int] = {}
+        self.received_oid_set: set[str] = set()
+        self.object_limit_bytes = object_limit_bytes
+        self.backlog_limit_bytes = backlog_limit_bytes
+        self.buffer = bytearray()
+        self.body = bytearray()
+        self.oid: str | None = None
+        self.remaining_size = 0
+        self.oversized = False
+
+    def feed(self, chunk: bytes) -> list[tuple[str, bytes | None]]:
+        """Return whole objects, or explicit unavailable markers for oversized bodies."""
+        if len(self.buffer) + len(chunk) > self.backlog_limit_bytes:
+            raise ValueError("Parsing backlog exceeded; history incomplete")
+        self.buffer.extend(chunk)
+        records: list[tuple[str, bytes | None]] = []
+        while self.buffer:
+            if self.oid is None:
+                header_end = self.buffer.find(b"\n")
+                if header_end < 0:
+                    if len(self.buffer) > CAT_FILE_HEADER_LIMIT_BYTES:
+                        raise ValueError("cat-file header is too long")
+                    break
+                if header_end > CAT_FILE_HEADER_LIMIT_BYTES:
+                    raise ValueError("cat-file header is too long")
+                header = bytes(self.buffer[:header_end]).decode("ascii")
+                del self.buffer[:header_end + 1]
+                fields = header.split(" ")
+                if len(fields) != 3:
+                    raise ValueError(f"Git object unavailable: {header}")
+                oid, object_type, size_text = fields
+                validate_oid(oid)
+                if oid not in self.expected_oid_set or oid in self.received_oid_set or object_type != self.expected_object_type or not size_text.isdecimal():
+                    raise ValueError("Invalid cat-file header")
+                self.oid = oid
+                self.remaining_size = int(size_text)
+                self.size_by_oid[oid] = self.remaining_size
+                self.oversized = self.remaining_size > self.object_limit_bytes
+            consumed_size = min(self.remaining_size, len(self.buffer))
+            if self.body_callback is not None and consumed_size:
+                self.body_callback(bytes(self.buffer[:consumed_size]))
+            if not self.oversized:
+                self.body.extend(self.buffer[:consumed_size])
+            del self.buffer[:consumed_size]
+            self.remaining_size -= consumed_size
+            if self.remaining_size or not self.buffer:
+                break
+            terminal_index = 0
+            if self.buffer[terminal_index] != ord("\n"):
+                raise ValueError("Invalid cat-file terminator")
+            del self.buffer[:1]
+            records.append((self.oid, None if self.oversized else bytes(self.body)))
+            self.received_oid_set.add(self.oid)
+            self.oid = None
+            self.body.clear()
+        return records
+
+    def finish(self) -> None:
+        """Reject missing objects and partial headers, bodies or terminators at EOF."""
+        if self.buffer or self.oid is not None or self.received_oid_set != self.expected_oid_set:
+            raise ValueError("Incomplete cat-file stream; missing objects")
+
+
+# The one read of the whole history: each commit is a record of these fields, every field ended by a NUL byte.
+# The message comes last and whole; Git's own message handling stops at a NUL inside it, as the subject does.
+HISTORY_LOG_PLACEHOLDERS = ("%H", "%h", "%P", "%an", "%ae", "%at", "%ct", "%e", "%B")
+HISTORY_LOG_FORMAT = "%x00".join(HISTORY_LOG_PLACEHOLDERS)
+(HISTORY_OID_FIELD, HISTORY_SHORT_OID_FIELD, HISTORY_PARENT_OIDS_FIELD, HISTORY_AUTHOR_NAME_FIELD, HISTORY_AUTHOR_EMAIL_FIELD, HISTORY_AUTHOR_TIMESTAMP_FIELD,
+ HISTORY_COMMITTER_TIMESTAMP_FIELD, HISTORY_ENCODING_FIELD, HISTORY_MESSAGE_FIELD) = range(len(HISTORY_LOG_PLACEHOLDERS))
+HISTORY_FIELD_COUNT = len(HISTORY_LOG_PLACEHOLDERS)
+# Signatures and notes are turned off so that no setting of the user can add text into the records. Git converts the
+# message and the author of a commit that declares another encoding to UTF-8. Asking for no conversion at all is not
+# an option: Git then converts every record to the system code page, which on Windows is not UTF-8.
+HISTORY_LOG_ARGUMENTS = ["log", "-z", "--topo-order", "--no-show-signature", "--no-notes", "--encoding=" + DEFAULT_COMMIT_ENCODING, "--format=" + HISTORY_LOG_FORMAT,
+                         "--stdin"]
+# Only the fields that make the ancestry stop the read when they are too large, since the output can no longer be
+# trusted; any other field too large to keep only costs the commit its details.
+ANCESTRY_HISTORY_FIELD_SET = frozenset({HISTORY_OID_FIELD, HISTORY_SHORT_OID_FIELD, HISTORY_PARENT_OIDS_FIELD})
+DROPPABLE_HISTORY_FIELD_SET = frozenset(range(HISTORY_FIELD_COUNT)) - ANCESTRY_HISTORY_FIELD_SET
+HISTORY_FIELD_SEPARATOR = b"\0"
+HISTORY_PARENT_SEPARATOR = b" "
+# The one read of the files each commit of the history changes, fed with the commits on its input. Each commit is
+# compared with each of its parents (-m), which is what the diff panel lists for a merge; the root commit is compared
+# with the empty tree (--root); --always writes the commit line even when nothing changed, so every requested commit is
+# answered; a rename keeps both of its names (--no-renames). diff-tree rather than log: log's option that shows merges
+# also accepts a mode that runs merge drivers, and the process runner keeps log to its list of read options.
+CHANGED_PATH_ARGUMENTS = ["diff-tree", "--stdin", "-r", "-m", "--root", "--always", "--name-only", "-z", "--no-renames", "--format=%x00%H"]
+CHANGED_PATH_FIELD_SEPARATOR = b"\0"
+# Git writes a newline between the commit line and the names of the files it changed.
+CHANGED_PATH_LIST_START = b"\n"
+
+
+class HistoryLogParser:
+    """Turn the NUL-framed records of the history read into ancestry and commits, whatever the chunk boundaries.
+
+    It grows the order, the parents and the children of the shared history exactly once per commit, in Git's order,
+    and answers the complete commits of each chunk. Every field is bounded while it is still arriving: a message or
+    any other field outside the ancestry above its limit stops being kept at once and the commit becomes a row whose
+    details are unavailable.
+    """
+
+    def __init__(self, snapshot: HistorySnapshot, object_limit_bytes: int = COMMIT_LIMIT_BYTES, header_limit_bytes: int = COMMIT_HEADER_LIMIT_BYTES) -> None:
+        """Share the accepted capture while keeping the unfinished record private."""
+        self.snapshot = snapshot
+        self.object_limit_bytes = object_limit_bytes
+        self.header_limit_bytes = header_limit_bytes
+        # The fields of the record still arriving, the bytes of its unfinished field, and whether one of its fields
+        # went over its limit and is no longer kept.
+        self.fields: list[bytes] = []
+        self.partial_field = bytearray()
+        self.field_dropped = False
+        self.record_dropped = False
+
+    def feed(self, chunk: bytes) -> list[Commit]:
+        """Take the next bytes of the output and answer the commits whose record they complete, in Git's order.
+
+        The record left unfinished by the previous chunk is completed field by field; the whole records of the chunk
+        are then read in one go each, which is what keeps a long history fast; what remains starts the next record.
+        """
+        commits: list[Commit] = []
+        pieces = chunk.split(HISTORY_FIELD_SEPARATOR)
+        last_piece_index = len(pieces) - 1
+        piece_index = 0
+        while piece_index < last_piece_index and self._record_started():
+            self._extend_field(pieces[piece_index])
+            self._close_field(commits)
+            piece_index += 1
+        while piece_index + HISTORY_FIELD_COUNT <= last_piece_index:
+            fields = pieces[piece_index:piece_index + HISTORY_FIELD_COUNT]
+            if len(fields[HISTORY_MESSAGE_FIELD]) > self.object_limit_bytes or max(map(len, fields[:HISTORY_MESSAGE_FIELD])) > self.header_limit_bytes:
+                break
+            self._add_record(fields, False, commits)
+            piece_index += HISTORY_FIELD_COUNT
+        while piece_index < last_piece_index:
+            self._extend_field(pieces[piece_index])
+            self._close_field(commits)
+            piece_index += 1
+        self._extend_field(pieces[last_piece_index])
+        return commits
+
+    def _record_started(self) -> bool:
+        """Tell whether a record was left unfinished by the bytes already read."""
+        return bool(self.fields or self.partial_field or self.field_dropped)
+
+    def _extend_field(self, piece: bytes) -> None:
+        """Keep the next bytes of the field now arriving, or stop keeping them once the field goes over its limit."""
+        if self.field_dropped or not piece:
+            return
+        field_index = len(self.fields)
+        limit_bytes = self.object_limit_bytes if field_index == HISTORY_MESSAGE_FIELD else self.header_limit_bytes
+        if len(self.partial_field) + len(piece) <= limit_bytes:
+            self.partial_field.extend(piece)
+            return
+        if field_index not in DROPPABLE_HISTORY_FIELD_SET:
+            raise ValueError("History record field is too large; history incomplete")
+        self.field_dropped = True
+        self.record_dropped = True
+        self.partial_field.clear()
+
+    def _close_field(self, commits: list[Commit]) -> None:
+        """End the field now arriving, and turn the record into a commit once its last field has ended."""
+        self.fields.append(bytes(self.partial_field))
+        self.partial_field.clear()
+        self.field_dropped = False
+        if len(self.fields) < HISTORY_FIELD_COUNT:
+            return
+        fields = self.fields
+        record_dropped = self.record_dropped
+        self.fields = []
+        self.record_dropped = False
+        self._add_record(fields, record_dropped, commits)
+
+    def _add_record(self, fields: list[bytes], record_dropped: bool, commits: list[Commit]) -> None:
+        """Check one whole record, add it to the ancestry and answer its commit, unless the commit was already listed.
+
+        The ancestry comes first and its fields stay strict: a wrong hash, abbreviation or parent means the output can
+        no longer be trusted, so the read stops. A time Git accepted but that cannot be read only costs the commit
+        its dates, and a field too large to keep costs it its details: its row stays in place either way.
+        """
+        oid = validate_oid(fields[HISTORY_OID_FIELD].decode("ascii"))
+        short_oid = fields[HISTORY_SHORT_OID_FIELD].decode("ascii")
+        if not short_oid or not oid.startswith(short_oid):
+            raise ValueError("Unexpected commit abbreviation in the history")
+        parent_oids: list[str] = []
+        for parent in fields[HISTORY_PARENT_OIDS_FIELD].split(HISTORY_PARENT_SEPARATOR):
+            if parent:
+                parent_oids.append(validate_oid(parent.decode("ascii")))
+        snapshot = self.snapshot
+        if oid in snapshot.parent_oids_by_oid:
+            return
+        snapshot.ordered_oids.append(oid)
+        snapshot.parent_oids_by_oid[oid] = parent_oids
+        snapshot.child_oids_by_oid.setdefault(oid, [])
+        for parent_oid in parent_oids:
+            snapshot.child_oids_by_oid.setdefault(parent_oid, []).append(oid)
+        if record_dropped:
+            commits.append(unavailable_commit(oid, short_oid, parent_oids, oversized_commit_cause(self.object_limit_bytes)))
+            return
+        author_timestamp = readable_commit_time(fields[HISTORY_AUTHOR_TIMESTAMP_FIELD])
+        committer_timestamp = readable_commit_time(fields[HISTORY_COMMITTER_TIMESTAMP_FIELD])
+        encoding = fields[HISTORY_ENCODING_FIELD] or None
+        commits.append(decode_commit_fields(oid, short_oid, parent_oids, fields[HISTORY_AUTHOR_NAME_FIELD], fields[HISTORY_AUTHOR_EMAIL_FIELD],
+                                            author_timestamp, committer_timestamp, encoding, fields[HISTORY_MESSAGE_FIELD], converted_to_utf8=True))
+
+    def finish(self) -> None:
+        """Refuse a record cut short at the end of the output, then declare the ancestry, and every child list, complete."""
+        self.check_ended()
+        self.snapshot.complete = True
+
+    def check_ended(self) -> None:
+        """Refuse an output that ended in the middle of a record."""
+        if self._record_started():
+            raise ValueError("Incomplete final history record")
+
+
+def parse_abbreviation_answer(output: bytes, oids: list[str]) -> dict[str, str]:
+    """Read Git's abbreviation of each requested commit, matched by object ID rather than by the order Git answers in.
+
+    Every requested commit must be answered exactly once, with a non-empty prefix of its own object ID.
+    """
+    requested_oid_set = set(oids)
+    short_oid_by_oid: dict[str, str] = {}
+    for line in output.decode("ascii").splitlines():
+        oid, separator, short_oid = line.partition("\0")
+        validate_oid(oid)
+        if not separator or oid not in requested_oid_set or oid in short_oid_by_oid or not short_oid or not oid.startswith(short_oid):
+            raise ValueError("Unexpected commit abbreviation answer")
+        short_oid_by_oid[oid] = short_oid
+    if len(short_oid_by_oid) != len(requested_oid_set):
+        raise ValueError("Incomplete commit abbreviation answer")
+    return short_oid_by_oid
+
+
+class ChangedPathParser:
+    """Turn the NUL-framed answer of the changed-file read into (commit OID, changed paths) records, whatever the chunk boundaries.
+
+    Each record of the answer is an empty field, the commit's OID, then one field per changed path, the first one
+    starting with the newline Git writes after the commit line. A merge compared with each parent gives one record per
+    parent, all with its OID: the caller joins them. Paths stay bytes, since Git may write any byte but NUL in them.
+    """
+
+    def __init__(self) -> None:
+        """Start before the first record, with nothing kept from a previous chunk."""
+        self.buffer = b""
+        self.expecting_oid = False
+        self.oid: str | None = None
+        self.paths: list[bytes] = []
+
+    def feed(self, chunk: bytes) -> list[tuple[str, list[bytes]]]:
+        """Read the fields this chunk completes and return the records that ended in it; the last unterminated field is kept for the next chunk."""
+        fields = (self.buffer + chunk).split(CHANGED_PATH_FIELD_SEPARATOR)
+        self.buffer = fields.pop()
+        records: list[tuple[str, list[bytes]]] = []
+        for field in fields:
+            self._read_field(field, records)
+        return records
+
+    def finish(self) -> list[tuple[str, list[bytes]]]:
+        """Refuse an answer cut in the middle of a field, then return the last record."""
+        if self.buffer:
+            raise ValueError("Incomplete changed-file answer")
+        records: list[tuple[str, list[bytes]]] = []
+        self._close_record(records)
+        return records
+
+    def _read_field(self, field: bytes, records: list[tuple[str, list[bytes]]]) -> None:
+        """Close the open record on an empty field, open one on the field that follows it, or add a path to the open record."""
+        if not field:
+            self._close_record(records)
+            self.expecting_oid = True
+            return
+        if self.expecting_oid:
+            self.oid = validate_oid(field.decode("ascii"))
+            self.expecting_oid = False
+            return
+        if self.oid is None:
+            raise ValueError("Invalid changed-file answer")
+        if not self.paths and field.startswith(CHANGED_PATH_LIST_START):
+            field = field[len(CHANGED_PATH_LIST_START):]
+        self.paths.append(field)
+
+    def _close_record(self, records: list[tuple[str, list[bytes]]]) -> None:
+        """Hand over the open record, if any, and start with no record open."""
+        if self.oid is None:
+            return
+        records.append((self.oid, self.paths))
+        self.oid = None
+        self.paths = []