gitpane 1.0.0__py3-none-any.whl

gitpane/sequencer/merge_state.py

@@ -0,0 +1,166 @@
+"""Read the merge Git leaves waiting for its commit, from Git's own files alone, without starting a Git process.
+
+GitPane never starts a merge, but the user often concludes one begun on the command line or by a pull: the Commit
+that does it must expect the merged commits as extra parents, and can offer the message Git prepared.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from gitpane.config import MERGE_HEAD_BASENAME, MERGE_MODE_BASENAME, MERGE_MODE_NO_FAST_FORWARD, MERGE_STATE_FILE_LIMIT_BYTES, READ_SIZE_SENTINEL_BYTES
+from gitpane.history.repository_value import validate_oid
+from gitpane.sequencer.commit_message_rule import DEFAULT_COMMENT_PREFIX
+from gitpane.sequencer.rebase_state import REBASE_STATE_DIR_BASENAMES
+from gitpane.sequencer.replay_state import (
+    BUSY_ACTION_REASON,
+    CHERRY_PICK_HEAD_BASENAME,
+    MERGE_MESSAGE_BASENAME,
+    RESOLVE_CONFLICTS_FIRST_REASON,
+    REVERT_HEAD_BASENAME,
+    SEQUENCER_BASENAME,
+)
+
+MERGE_STATE_UNREADABLE_CAUSE = "The merge in progress could not be read. Refresh before committing."
+MERGE_STATE_TOO_LARGE_CAUSE = "The merge in progress is described by an unexpectedly large file. Refresh before committing."
+MERGE_HEAD_INVALID_CAUSE = "The merge in progress names something other than commits. Refresh before committing."
+# Why Abort is greyed for a merge that could not be read, and why a click finds no merge read to abort.
+MERGE_UNREADABLE_ABORT_REASON = "The merge in progress could not be read. Refresh before aborting it."
+MERGE_ABORT_REFRESH_REASON = "Refresh before aborting the merge."
+# The first line of the banner of a merge waiting for its commit, worded as Git Extensions words it.
+MERGE_IN_PROGRESS_TEXT = "Merge is currently in progress"
+# A rebase or a cherry-pick/revert can stop with a MERGE_HEAD of its own; that pause keeps its own banner and buttons.
+OTHER_PAUSE_MARKER_BASENAMES = (*REBASE_STATE_DIR_BASENAMES, CHERRY_PICK_HEAD_BASENAME, REVERT_HEAD_BASENAME, SEQUENCER_BASENAME)
+# The buttons of the merge banner, as merge_action_reason names them.
+CONTINUE_ACTION = "continue"
+ABORT_ACTION = "abort"
+
+
+@dataclass(frozen=True)
+class MergeInProgress:
+    """The commits a waiting merge adds after HEAD, in the order Git records them, and the raw message Git prepared.
+
+    ``keeps_every_parent`` is true for a merge started with --no-ff. Otherwise the commit that concludes the merge drops
+    any parent that another of its parents already contains, as an octopus merge of a branch and its own ancestor does.
+    """
+
+    parent_oids: tuple[str, ...]
+    message: str
+    keeps_every_parent: bool = False
+
+
+def _read_merge_file(filename: str) -> bytes | None:
+    """Read one small merge file whole, answering None when it does not exist.
+
+    Anything else that prevents a complete read, a folder in its place or a size no real merge reaches included,
+    is an error: a merge that cannot be read must never pass for no merge at all.
+    """
+    try:
+        with open(filename, "rb") as stream:
+            content = stream.read(MERGE_STATE_FILE_LIMIT_BYTES + READ_SIZE_SENTINEL_BYTES)
+    except FileNotFoundError:
+        return None
+    except OSError as error:
+        raise ValueError(MERGE_STATE_UNREADABLE_CAUSE) from error
+    if len(content) > MERGE_STATE_FILE_LIMIT_BYTES:
+        raise ValueError(MERGE_STATE_TOO_LARGE_CAUSE)
+    return content
+
+
+def read_merge_in_progress(git_dir: str) -> MergeInProgress | None:
+    """Answer the merge waiting for its commit in this worktree's Git directory, or None when there is none.
+
+    The commit IDs are validated one by one and kept in their order, whatever the line ends; the message is decoded
+    as UTF-8, any undecodable byte replaced, and is empty when Git left none. The merge mode is compared exactly as Git
+    compares it when it commits.
+    """
+    merge_head = _read_merge_file(os.path.join(git_dir, MERGE_HEAD_BASENAME))
+    if merge_head is None:
+        return None
+    parent_oids = []
+    try:
+        for line in merge_head.decode("ascii").splitlines():
+            if line.strip():
+                parent_oids.append(validate_oid(line.strip()))
+    except (UnicodeDecodeError, ValueError) as error:
+        raise ValueError(MERGE_HEAD_INVALID_CAUSE) from error
+    if not parent_oids:
+        raise ValueError(MERGE_HEAD_INVALID_CAUSE)
+    message = _read_merge_file(os.path.join(git_dir, MERGE_MESSAGE_BASENAME))
+    mode = _read_merge_file(os.path.join(git_dir, MERGE_MODE_BASENAME))
+    return MergeInProgress(tuple(parent_oids), (message or b"").decode("utf-8", "replace"), mode == MERGE_MODE_NO_FAST_FORWARD)
+
+
+def merge_message_text(raw: str) -> str:
+    """Turn the message Git prepared into the text offered for the commit: comment lines, blank lines around it and trailing blanks removed.
+
+    Git writes the conflicted paths as comment lines; it removes them itself only when it opens an editor, and a
+    commit given its message directly would record them.
+    """
+    # Git's default comment character. core.commentChar is not read: that would cost a Git process at every read, and a
+    # line kept by mistake stays visible and editable in the message before Commit.
+    kept_lines = []
+    for line in raw.splitlines():
+        if not line.startswith(DEFAULT_COMMENT_PREFIX):
+            kept_lines.append(line)
+    return "\n".join(kept_lines).lstrip("\n").rstrip()
+
+
+@dataclass(frozen=True)
+class MergeBannerState:
+    """What the repository window needs to show a merge waiting for its commit.
+
+    ``merge`` is the merge read from Git's files, ``other_pause`` tells that a rebase or a cherry-pick/revert is paused
+    beside it, and ``cause`` explains a MERGE_HEAD that exists but could not be read.
+    """
+
+    merge: MergeInProgress | None = None
+    other_pause: bool = False
+    cause: str = ""
+
+    @property
+    def in_progress(self) -> bool:
+        """Tell whether the window shows the merge banner: a MERGE_HEAD exists, readable or not, and no other operation is paused."""
+        return (self.merge is not None or bool(self.cause)) and not self.other_pause
+
+
+def read_merge_banner_state(git_dir: str) -> MergeBannerState:
+    """Read the merge state the banner shows from Git's files in this worktree's Git directory, without a Git process.
+
+    A MERGE_HEAD that cannot be read is answered with its cause, never as an exception, so the banner can say why.
+    The markers of another pause are only looked for when a MERGE_HEAD exists.
+    """
+    try:
+        merge = read_merge_in_progress(git_dir)
+    except ValueError as error:
+        merge, cause = None, str(error)
+    else:
+        cause = ""
+    if merge is None and not cause:
+        return MergeBannerState()
+    other_pause = False
+    for basename in OTHER_PAUSE_MARKER_BASENAMES:
+        if os.path.lexists(os.path.join(git_dir, basename)):
+            other_pause = True
+            break
+    return MergeBannerState(merge, other_pause, cause)
+
+
+def merge_action_reason(state: MergeBannerState, action: str, *, conflict_count: int, busy: bool) -> str:
+    """Tell why a button of the merge banner is greyed, or answer "" when it may act.
+
+    A merge tool or an operation at work comes first, then a merge that could not be read: Continue gives the cause the
+    Commit would give, and Abort its own reason, since an Abort only applies to the merged commits the banner showed and
+    an unreadable merge shows none. Continue also waits until no conflict is left, since the Commit it leads to cannot
+    conclude a merge with unresolved files.
+    """
+    if busy:
+        return BUSY_ACTION_REASON
+    if state.cause:
+        if action == ABORT_ACTION:
+            return MERGE_UNREADABLE_ABORT_REASON
+        return state.cause
+    if action == CONTINUE_ACTION and conflict_count:
+        return RESOLVE_CONFLICTS_FIRST_REASON
+    return ""