gitpane 1.0.0__py3-none-any.whl

gitpane/reference/stash_list.py

@@ -0,0 +1,164 @@
+"""Read the list of stashes from the stash reflog file, the way `git stash list` shows it, without starting Git."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from gitpane.config import GIT_REFTABLE_DIR_BASENAME, LINE_SEPARATOR
+from gitpane.history.repository_value import FULL_OID_PATTERN
+from gitpane.reference.stash import stash_reflog_filename
+from gitpane.sequencer.rebase_state import checked_metadata, metadata_signature
+from gitpane.worktree.worktree_snapshot import read_validated_size
+
+if TYPE_CHECKING:
+    from gitpane.history.repository_value import RepositoryContext
+
+# One reflog line per stash, about a hundred bytes each: a mebibyte holds thousands of stashes. A larger reflog is
+# not shown at all rather than read in part.
+STASH_REFLOG_LIMIT_BYTES = 1024 * 1024
+STASH_LIST_TOO_LARGE_CAUSE = "Stash list too large to show"
+STASH_LIST_NOT_REGULAR_CAUSE = "Stash list unreadable: the stash reflog is not a regular file"
+STASH_LIST_CHANGED_CAUSE = "Stash list changed while reading; refresh"
+STASH_LIST_UNREADABLE_PREFIX = "Stash list unreadable: "
+STASH_LIST_REFTABLE_CAUSE = "Stash list is not available for repositories using the reftable reference format"
+# A reflog line is `<old oid> <new oid> <name> <<email>> <timestamp> <timezone>[\t<message>]`. The pattern keeps the
+# lines Git keeps when it numbers `stash@{N}` and nothing else: the identity ends at the first ">", the timestamp is
+# digits, the timezone is a sign and four digits, and the tab and message are written only for a non-empty message.
+# A line Git skips must not take a number, or every older stash would be shown under another stash's selector.
+_REFLOG_OID_PATTERN = FULL_OID_PATTERN.pattern.encode("ascii")
+REFLOG_LINE_PATTERN = re.compile(
+    rb"(?P<old>" + _REFLOG_OID_PATTERN + rb") (?P<new>" + _REFLOG_OID_PATTERN + rb") [^>]*> (?P<timestamp>[0-9]+) (?P<timezone>[+-][0-9]{4})"
+    rb"(?:\t(?P<message>.*)|(?P<trailing>.*))",
+    re.DOTALL,
+)
+# Git reads a zero timestamp as a failed parse and skips the line.
+REFLOG_INVALID_TIMESTAMP = 0
+# The reflog is read as bytes; this form is drawn from the one text line end rather than written again.
+LINE_SEPARATOR_BYTES = LINE_SEPARATOR.encode("ascii")
+CARRIAGE_RETURN = b"\r"
+# Message Git writes for a stash made without a message. A reference name cannot contain ":", so the first ": "
+# ends the branch name even when the subject holds more.
+WIP_MESSAGE_PATTERN = re.compile(r"^WIP on (?P<branch>[^:]+): (?P<commit>[0-9a-f]+) (?P<subject>.*)$")
+
+
+@dataclass(frozen=True)
+class StashEntry:
+    """One stash as `git stash list` shows it: its selector index, stash commit, reflog message and creation time."""
+
+    index: int
+    oid: str
+    message: str
+    timestamp: int
+    timezone: str
+
+
+@dataclass(frozen=True)
+class StashList:
+    """The stashes of a repository, newest first, or the reason they could not be read.
+
+    An empty list without a cause means the repository has no stash.
+    """
+
+    entries: tuple[StashEntry, ...] = ()
+    cause: str = ""
+
+
+def stash_selector(index: int) -> str:
+    """Name a stash with Git's own selector syntax, `stash@{N}`."""
+    return f"stash@{{{index}}}"
+
+
+def stash_base_commit(message: str) -> str:
+    """Name the commit a stash was made from, `<short oid> <subject>`, or an empty text when the message does not say.
+
+    Only a stash made without a message tells it: Git then writes `WIP on <branch>: <short oid> <subject>`. A stash
+    made with a message is written `On <branch>: <message>` and keeps no trace of its starting commit in the reflog.
+    """
+    match = WIP_MESSAGE_PATTERN.fullmatch(message)
+    if match is None:
+        return ""
+    return f"{match['commit']} {match['subject']}".rstrip()
+
+
+def _parse_reflog_line(line: bytes, index: int) -> StashEntry | None:
+    """Turn one reflog line into a stash entry, or None for a line Git itself skips when it lists the stashes.
+
+    Only the lines Git keeps may take a `stash@{N}` number, so the numbers shown match the ones Git accepts in commands.
+    """
+    match = REFLOG_LINE_PATTERN.fullmatch(line.removesuffix(CARRIAGE_RETURN))
+    if match is None:
+        return None
+    timestamp = int(match["timestamp"])
+    if timestamp == REFLOG_INVALID_TIMESTAMP:
+        return None
+    # Without a tab, Git shows whatever follows the timezone as the message, which is empty for a line it wrote.
+    message = match["message"] if match["message"] is not None else match["trailing"]
+    return StashEntry(index, match["new"].decode("ascii"), message.decode("utf-8", "replace"), timestamp, match["timezone"].decode("ascii"))
+
+
+def parse_stash_reflog(content: bytes) -> tuple[StashEntry, ...]:
+    """Turn the stash reflog, written oldest first, into the newest-first list `git stash list` prints.
+
+    Lines that do not have the reflog layout are skipped instead of failing the whole list.
+    """
+    entries: list[StashEntry] = []
+    for line in reversed(content.split(LINE_SEPARATOR_BYTES)):
+        if not line.strip():
+            continue
+        entry = _parse_reflog_line(line, len(entries))
+        if entry is not None:
+            entries.append(entry)
+    return tuple(entries)
+
+
+def _read_stash_reflog(filename: str) -> StashList:
+    """Read the stash reflog with a bounded size, refusing links, special files and a file replaced while reading."""
+    try:
+        before = checked_metadata(filename)
+    except FileNotFoundError:
+        return StashList()
+    except ValueError:
+        return StashList(cause=STASH_LIST_NOT_REGULAR_CAUSE)
+    if before.st_size > STASH_REFLOG_LIMIT_BYTES:
+        return StashList(cause=STASH_LIST_TOO_LARGE_CAUSE)
+    flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+    with os.fdopen(os.open(filename, flags), "rb") as stream:
+        opened = os.fstat(stream.fileno())
+        # Windows descriptor and path stat disagree about ctime; compare it only within the same API.
+        if metadata_signature(opened, include_change_time=False) != metadata_signature(before, include_change_time=False):
+            return StashList(cause=STASH_LIST_CHANGED_CAUSE)
+        if opened.st_size > STASH_REFLOG_LIMIT_BYTES:
+            return StashList(cause=STASH_LIST_TOO_LARGE_CAUSE)
+        content = read_validated_size(stream, opened.st_size)
+    if len(content) != opened.st_size:
+        return StashList(cause=STASH_LIST_CHANGED_CAUSE)
+    try:
+        after = checked_metadata(filename)
+    except ValueError:
+        # The path became a link or special file while it was read: the content read may not be the stash reflog.
+        return StashList(cause=STASH_LIST_CHANGED_CAUSE)
+    if metadata_signature(after) != metadata_signature(before):
+        return StashList(cause=STASH_LIST_CHANGED_CAUSE)
+    return StashList(parse_stash_reflog(content))
+
+
+def read_stash_list(context: RepositoryContext) -> StashList:
+    """Read the stashes of a repository from its shared stash reflog, newest first, without ever raising.
+
+    The reflog lives in the shared Git directory, so a linked worktree lists the stashes of its main repository and a
+    submodule its own. An absent reflog means no stash; anything unreadable gives an empty list with a cause.
+    A repository using the reftable format keeps the reflog in its tables, so its list is not read at all rather
+    than shown as empty, even when a reflog file is left over from before a conversion.
+    """
+    try:
+        if os.path.isdir(os.path.join(context.common_git_dir, GIT_REFTABLE_DIR_BASENAME)):
+            return StashList(cause=STASH_LIST_REFTABLE_CAUSE)
+        return _read_stash_reflog(stash_reflog_filename(context))
+    except FileNotFoundError:
+        return StashList()
+    except (OSError, ValueError) as error:
+        detail = error.strerror if isinstance(error, OSError) and error.strerror else type(error).__name__
+        return StashList(cause=STASH_LIST_UNREADABLE_PREFIX + detail)

gitpane/sequencer/commit_message_rule.py

@@ -0,0 +1,154 @@
+"""Judge a commit message empty the way Git's own cleanup would."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from gitpane.worktree.command_sequence import GitCommand
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+# Git's comment character when the configuration names none, and the value of core.commentChar that lets Git pick one
+# per message.
+DEFAULT_COMMENT_PREFIX = "#"
+AUTOMATIC_COMMENT_PREFIX = "auto"
+# What Git 2.53 writes after the comment prefix on the cut line of a message file when commit.cleanup is scissors: that
+# line and everything below it are dropped.
+SCISSORS_LINE_SUFFIX = " ------------------------ >8 ------------------------"
+# The trailer Git ignores when it judges a message: a message made only of sign-offs aborts the commit like an empty one.
+SIGN_OFF_PREFIX = "Signed-off-by: "
+# The only characters Git's own character table counts as blank. A vertical tab, a form feed or a no-break space is
+# message text for Git, so a message made of them is committed.
+GIT_BLANK_CHARACTERS = " \t\n\r"
+# Git cuts a message file into lines on line feeds only; a visual wrap in an editor is not a character of the file.
+MESSAGE_LINE_SEPARATOR = "\n"
+# The settings the rule depends on, as git config --get-regexp lists them: Git writes section and key names in lower case.
+COMMENT_CHAR_KEY = "core.commentchar"
+COMMENT_STRING_KEY = "core.commentstring"
+CLEANUP_KEY = "commit.cleanup"
+COMMIT_ENCODING_KEY = "i18n.commitencoding"
+COMMENT_KEY_SET = frozenset((COMMENT_CHAR_KEY, COMMENT_STRING_KEY))
+COMMIT_MESSAGE_SETTING_PATTERN = "^(" + "|".join(map(re.escape, (COMMENT_CHAR_KEY, COMMENT_STRING_KEY, CLEANUP_KEY, COMMIT_ENCODING_KEY))) + ")$"
+# git config --get-regexp writes one setting per line, its key then a space then its value; a key written without "="
+# in the file is listed alone.
+SETTING_KEY_VALUE_SEPARATOR = " "
+SETTING_OUTPUT_CODEC = "utf-8"
+
+
+class CleanupMode(Enum):
+    """How Git cleans a commit message before judging it, as commit.cleanup names it."""
+
+    DEFAULT = "default"
+    STRIP = "strip"
+    WHITESPACE = "whitespace"
+    VERBATIM = "verbatim"
+    SCISSORS = "scissors"
+
+    @property
+    def drops_comment_lines(self) -> bool:
+        """Tell whether this cleanup removes comment lines; default does, because it means strip when Git opens an editor."""
+        return self in (CleanupMode.DEFAULT, CleanupMode.STRIP)
+
+
+def cleanup_mode(value: str) -> CleanupMode:
+    """Read a commit.cleanup value, with the default cleanup for a value Git does not know (Git itself refuses it)."""
+    try:
+        return CleanupMode(value)
+    except ValueError:
+        return CleanupMode.DEFAULT
+
+
+@dataclass(frozen=True)
+class CommitMessageRule:
+    """The repository settings that decide how Git cleans and decodes a commit message the rebase asks for.
+
+    ``comment_prefix`` is None when core.commentChar is auto: Git then picks a character per message, so a comment
+    cannot be told from text. ``commit_encoding`` is empty when i18n.commitEncoding is not set.
+    """
+
+    comment_prefix: str | None
+    cleanup: CleanupMode
+    commit_encoding: str
+
+
+def message_is_empty(text: str, rule: CommitMessageRule) -> bool:
+    """Tell whether Git would abort the commit for an empty message once its own cleanup has run.
+
+    ``text`` is the content of the message file. verbatim keeps every character, so only an empty text is empty.
+    scissors drops the cut line and everything below it, and keeps the comments above it. default and strip drop the
+    lines that start, at the first column, with the comment prefix. What remains is empty when every line, trimmed of
+    Git's blanks, is empty or a sign-off. Without a known comment prefix only a blank text is refused: Git judges the
+    rest itself and pauses the rebase when it refuses the message.
+    """
+    if rule.cleanup == CleanupMode.VERBATIM:
+        return text == ""
+    lines = text.split(MESSAGE_LINE_SEPARATOR)
+    if rule.comment_prefix is None:
+        return _all_lines_blank(lines)
+    if rule.cleanup == CleanupMode.SCISSORS:
+        lines = _lines_above_cut(lines, rule.comment_prefix)
+    for line in lines:
+        if rule.cleanup.drops_comment_lines and line.startswith(rule.comment_prefix):
+            continue
+        trimmed_line = line.rstrip(GIT_BLANK_CHARACTERS)
+        if trimmed_line and not trimmed_line.startswith(SIGN_OFF_PREFIX):
+            return False
+    return True
+
+
+def _all_lines_blank(lines: list[str]) -> bool:
+    """Tell whether every line holds only characters Git counts as blank."""
+    for line in lines:
+        if line.strip(GIT_BLANK_CHARACTERS):
+            return False
+    return True
+
+
+def _lines_above_cut(lines: list[str], comment_prefix: str) -> list[str]:
+    """Keep the lines above Git's scissors cut line, the first line included as a possible cut.
+
+    Git only takes the cut line as one when a line feed follows it, so a cut line that ends the file is message text.
+    """
+    cut_line = comment_prefix + SCISSORS_LINE_SUFFIX
+    last_index = len(lines) - 1
+    for index, line in enumerate(lines):
+        if line == cut_line and index < last_index:
+            return lines[:index]
+    return lines
+
+
+def parse_commit_message_setting(output: bytes) -> CommitMessageRule:
+    """Build the rule from the settings git config listed, with Git's defaults for the ones not set.
+
+    Git lists the settings in the order it reads them, the command line last, so the last value of a key wins, and the
+    later of core.commentChar and core.commentString wins as it does for Git. The output is decoded with replacement
+    characters: a value that is not UTF-8 must not stop the user from editing the message.
+    """
+    comment_prefix: str | None = DEFAULT_COMMENT_PREFIX
+    cleanup = CleanupMode.DEFAULT
+    commit_encoding = ""
+    for line in output.decode(SETTING_OUTPUT_CODEC, errors="replace").split(MESSAGE_LINE_SEPARATOR):
+        key, separator, value = line.partition(SETTING_KEY_VALUE_SEPARATOR)
+        if not separator:
+            continue
+        if key in COMMENT_KEY_SET:
+            comment_prefix = None if value == AUTOMATIC_COMMENT_PREFIX else value
+        elif key == CLEANUP_KEY:
+            cleanup = cleanup_mode(value)
+        elif key == COMMIT_ENCODING_KEY:
+            commit_encoding = value
+    return CommitMessageRule(comment_prefix, cleanup, commit_encoding)
+
+
+def read_commit_message_rule() -> Generator[GitCommand, bytes, CommitMessageRule]:
+    """Read the comment prefix, the cleanup and the commit encoding of the repository in one Git process.
+
+    git config exits with 1 when none of the settings is set, which is the usual case, so that status is accepted and
+    gives Git's defaults.
+    """
+    output = yield GitCommand(["config", "--get-regexp", COMMIT_MESSAGE_SETTING_PATTERN], accepted_codes=(0, 1))
+    return parse_commit_message_setting(output)