gitpane 1.0.0__py3-none-any.whl

gitpane/history_rewrite/value.py

@@ -0,0 +1,229 @@
+"""Describe the byte identities used by a private history rewrite."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from gitpane.history.repository_value import RepositoryContext
+
+
+class RewriteTargetKind(Enum):
+    """Choose exact-file or directory-descendant matching."""
+
+    FILE = "file"
+    FOLDER = "folder"
+
+
+@dataclass(frozen=True)
+class RewriteTarget:
+    """Keep a canonical Git path separate from its display label."""
+
+    path: bytes
+    kind: RewriteTargetKind
+
+    def __post_init__(self) -> None:
+        """Reject ambiguous repository paths before using them in any Git request."""
+        validate_path(self.path)
+
+
+def validate_path(path: bytes) -> bytes:
+    """Accept only literal, canonical repository-relative path bytes."""
+    if not path or b"\0" in path or any(part in (b"", b".", b"..") for part in path.split(b"/")):
+        raise ValueError("Invalid repository-relative path; select a canonical file or folder")
+    return path
+
+
+class RewriteStatus(Enum):
+    """Identify the visible contribution of a rewritten commit."""
+
+    MODIFIED = "M"
+    DELETED = "D"
+
+
+class RewriteProtectedKind(Enum):
+    """Name the repository entries that cannot participate in history removal."""
+
+    SUBMODULE = "a submodule"
+    MODULE_CONFIGURATION = "the .gitmodules file"
+
+
+class RewriteRefusalKind(Enum):
+    """Identify technical limits that cannot produce a faithful rewritten history."""
+
+    NO_SURVIVING_TIP = "no_surviving_tip"
+    INVALID_MERGE_PARENTS = "invalid_merge_parents"
+    UNSUPPORTED_METADATA = "unsupported_metadata"
+    DETACHED_HEAD = "detached_head"
+    UNBORN_BRANCH = "unborn_branch"
+    NATIVE_OPERATION = "native_operation"
+    UNMERGED_INDEX = "unmerged_index"
+    STAGED_TARGET = "staged_target"
+    PROTECTED_TARGET = "protected_target"
+    BEHIND_UPSTREAM = "behind_upstream"
+    OTHER_WORKTREE = "other_worktree"
+    STALE_CAPTURE = "stale_capture"
+    INCOMPLETE_HISTORY = "incomplete_history"
+    UNSUPPORTED_INDEX = "unsupported_index"
+
+
+class RewriteRefusal(ValueError):
+    """Carry a typed preparation refusal with an actionable diagnostic."""
+
+    def __init__(self, kind: RewriteRefusalKind, detail: str, *, path: bytes | None = None, commit_oid: str | None = None, branch: str | None = None) -> None:
+        """Keep the machine-readable cause alongside the user-facing explanation."""
+        super().__init__(detail)
+        self.kind = kind
+        self.detail = detail
+        self.path = path
+        self.commit_oid = commit_oid
+        self.branch = branch
+
+
+class ChangeKind(Enum):
+    """Identify the supported fast-export file directives."""
+
+    MODIFY = b"M"
+    DELETE = b"D"
+
+
+@dataclass(frozen=True)
+class FileChange:
+    """Keep a literal delta without loading its blob."""
+
+    kind: ChangeKind
+    path: bytes
+    mode: bytes = b""
+    oid: str = ""
+
+
+@dataclass(frozen=True)
+class ExportCommit:
+    """Retain export order, ancestry references and file deltas."""
+
+    oid: str
+    mark: str
+    parent_refs: tuple[str, ...]
+    changes: tuple[FileChange, ...]
+
+
+@dataclass(frozen=True)
+class RawCommit:
+    """Locate an original message in its spool with the metadata needed to rebuild it."""
+
+    oid: str
+    tree_oid: str
+    parent_oids: tuple[str, ...]
+    author: bytes
+    committer: bytes
+    encoding: bytes | None
+    message_offset: int
+    message_length: int
+    header_names: tuple[bytes, ...]
+    signed: bool
+
+
+@dataclass(frozen=True)
+class ImportCommit:
+    """Describe one generated private commit with remapped parents."""
+
+    raw: RawCommit
+    mark: str
+    parent_refs: tuple[str, ...]
+    changes: tuple[FileChange, ...]
+
+
+@dataclass(frozen=True)
+class RewriteRow:
+    """Project one changed contribution into bounded presentation text."""
+
+    oid: str
+    status: RewriteStatus
+    message: str
+    author: str
+    date: str
+    message_offset: int | None = None
+    message_length: int = 0
+
+
+@dataclass(frozen=True)
+class BranchRewrite:
+    """Describe a local reference's proposed destination."""
+
+    name: str
+    old_oid: str
+    new_oid: str
+    upstream: str | None = None
+    remote_refs: tuple[str, ...] = ()
+    tip_deleted: bool = False
+
+
+@dataclass(frozen=True)
+class RewriteCapture:
+    """Keep the source facts to which a rewrite proposal belongs.
+
+    ``git_version`` is the line ``git --version`` wrote for that executable; it says which options that Git accepts.
+    It is empty while the check of that Git, at start or in Settings, has not answered yet or after it failed, and
+    the preparation then reads it itself before its first export.
+    """
+
+    context: RepositoryContext
+    git_filename: str
+    head_ref: str | None
+    local_ref_by_name: dict[str, str] = field(default_factory=dict)
+    remote_ref_by_name: dict[str, str] = field(default_factory=dict)
+    index_identity: bytes | None = None
+    upstream_by_name: dict[str, str] = field(default_factory=dict)
+    worktrees: tuple[bytes, ...] = ()
+    native_state: tuple[str, ...] = ()
+    generation: int = 0
+    upstream_config: bytes = b""
+    index_stat: tuple[int, ...] | None = None
+    complete: bool = False
+    shared_index_filename: str = ""
+    shared_index_identity: bytes | None = None
+    git_version: str = ""
+
+
+@dataclass(frozen=True)
+class RewriteIndex:
+    """Bind private index files to their exact original and verified candidate digests."""
+
+    original_filename: str
+    candidate_filename: str
+    original_identity: bytes | None
+    candidate_identity: bytes | None
+
+
+@dataclass(frozen=True)
+class RewritePreparation:
+    """Expose only a verified proposal as executable preparation."""
+
+    capture: RewriteCapture
+    target: RewriteTarget
+    operation_dir: str = ""
+    stream_filename: str = ""
+    replacement_by_oid: dict[str, str | None] = field(default_factory=dict)
+    branches: tuple[BranchRewrite, ...] = ()
+    rows: tuple[RewriteRow, ...] = ()
+    signed_count: int = 0
+    current_absent: bool = False
+    complete: bool = False
+    refusal: str = ""
+    operation_identity: tuple[int, int] | None = None
+    refusal_kind: RewriteRefusalKind | None = None
+    index: RewriteIndex | None = None
+    message_filename: str = ""
+
+
+@dataclass(frozen=True)
+class HistoryAnalysis:
+    """Keep graph decisions separate from import serialization."""
+
+    replacement_by_oid: dict[str, str | None]
+    commits: tuple[ImportCommit, ...]
+    rows: tuple[RewriteRow, ...]
+    branches: tuple[BranchRewrite, ...]
+    signed_count: int

gitpane/operation/console_line.py

@@ -0,0 +1,313 @@
+"""Decide the text an operation console shows of a record, while the ``--log`` file keeps the full detail.
+
+The console reads like a terminal: a folder named once at the top, one ``$ `` line per command written as one would type
+it, the raw output of the command below it, and a single line when a process fails. This module holds those rules
+without any Qt type, so the trace, the view and the tests share one definition of each text.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from gitpane.operation.console_tone import ConsoleTone
+from gitpane.operation.diagnostic import MASKED_VALUE, mask_sensitive_arguments, terminal_text
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.process.process_runner import EXIT_CODE_CAUSE_TEMPLATE, ProcessStatus
+from gitpane.transport.git_refusal import is_trace_line
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from gitpane.process.process_runner import ProcessRequest, ProcessResult
+
+
+@dataclass(frozen=True)
+class ConsoleLine:
+    """One console line as it is shown, with its colour; a text holding line breaks spans several lines of one tone."""
+
+    text: str
+    tone: ConsoleTone = ConsoleTone.NEUTRAL
+
+
+@dataclass(frozen=True)
+class ConsoleHeader:
+    """The folder a console names once on its first line: the repository, or the destination of a clone."""
+
+    label: str
+    directory: str
+
+
+REPOSITORY_HEADER_LABEL = "Repository"
+DESTINATION_HEADER_LABEL = "Destination"
+HEADER_TEXT_TEMPLATE = "{label}: {directory}"
+COMMAND_PROMPT = "$ "
+COMMAND_WORD_SEPARATOR = " "
+
+# cmd.exe splits or interprets these characters, which Git accepts in a reference name (feature&x, for example).
+# subprocess.list2cmdline only quotes a space, a tab or an empty argument, so it would leave them bare.
+WINDOWS_SHELL_SPECIAL_CHARACTER_SET = frozenset(' \t&|<>^()%!"')
+WINDOWS_QUOTE = '"'
+WINDOWS_BACKSLASH = "\\"
+
+
+def header_text(header: ConsoleHeader) -> str:
+    """Return the first line of a console, such as ``Repository: /home/user/project``."""
+    return HEADER_TEXT_TEMPLATE.format(label=header.label, directory=header.directory)
+
+
+def quote_posix_argument(argument: str) -> str:
+    """Quote one word so a POSIX shell reads it back unchanged; a word with nothing special stays bare."""
+    return shlex.quote(argument)
+
+
+def quote_windows_argument(argument: str) -> str:
+    """Quote one word the way the Microsoft C runtime reads it back, also when cmd.exe would interpret one of its characters.
+
+    The rules are those of subprocess.list2cmdline: backslashes are doubled only before a quote and at the end of a
+    quoted word, and an inner quote is escaped with a backslash.
+    """
+    # Workaround: list2cmdline decides alone when to quote, and it leaves cmd.exe's special characters bare, so its
+    # escaping loop is written again here with a wider test. A %VAR% stays expanded by cmd.exe even between quotes;
+    # there is no way to write it literally on a line pasted into cmd.exe, a limit accepted for a line meant to be read.
+    if argument and not any(character in WINDOWS_SHELL_SPECIAL_CHARACTER_SET for character in argument):
+        return argument
+    pieces: list[str] = [WINDOWS_QUOTE]
+    backslash_count = 0
+    for character in argument:
+        if character == WINDOWS_BACKSLASH:
+            backslash_count += 1
+            continue
+        if character == WINDOWS_QUOTE:
+            pieces.append(WINDOWS_BACKSLASH * (backslash_count * 2 + 1) + WINDOWS_QUOTE)
+        else:
+            pieces.append(WINDOWS_BACKSLASH * backslash_count + character)
+        backslash_count = 0
+    pieces.append(WINDOWS_BACKSLASH * (backslash_count * 2) + WINDOWS_QUOTE)
+    return "".join(pieces)
+
+
+def quote_argument(argument: str, *, windows: bool | None = None) -> str:
+    """Quote one word in the style of the system's usual shell, so the line can be pasted there."""
+    windows = os.name == "nt" if windows is None else windows
+    if windows:
+        return quote_windows_argument(argument)
+    return quote_posix_argument(argument)
+
+
+def command_text(program_filename: str, arguments: list[str], *, redact: Callable[[str], str] | None = None, windows: bool | None = None) -> str:
+    """Return a command as one would type it: the full executable path then each argument, quoted where a shell needs it.
+
+    A value written after a secret-named option is replaced by its placeholder, left unquoted so it reads as one. Every
+    other word goes through ``redact`` first, the filter that already hides the secrets of the trace, and is quoted
+    after, so a replacement holding a space is still one word.
+    """
+    masked_arguments = mask_sensitive_arguments(arguments).arguments
+    words: list[str] = []
+    for word in [program_filename, *masked_arguments]:
+        if word == MASKED_VALUE:
+            words.append(word)
+            continue
+        if redact is not None:
+            word = redact(word)
+        words.append(quote_argument(word, windows=windows))
+    return COMMAND_WORD_SEPARATOR.join(words)
+
+
+WORKING_DIR_SUFFIX_TEMPLATE = "   (in {working_dir})"
+
+
+def _comparable_dir(directory: str) -> str:
+    """Return a folder spelled the way two spellings of the same folder compare equal: absolute, normalised, case folded where the system ignores case."""
+    return os.path.normcase(os.path.abspath(directory))
+
+
+def working_dir_suffix(working_dir: str, header_dir: str) -> str:
+    """Return what follows a command run in another folder than the one the header names, or nothing when it runs there.
+
+    The suffix is about the folder the process really runs in. A folder given to Git with ``-C`` is already read in the
+    arguments, so a command that passes it and runs in the header's folder gets no suffix. The folder is written as
+    received and without quotes: it is information placed after the command, not part of what one would paste.
+    """
+    if _comparable_dir(working_dir) == _comparable_dir(header_dir):
+        return ""
+    return WORKING_DIR_SUFFIX_TEMPLATE.format(working_dir=working_dir)
+
+
+def command_line(request: ProcessRequest, header: ConsoleHeader | None, *, redact: Callable[[str], str] | None = None, windows: bool | None = None) -> str:
+    """Return the ``$ `` line of a process: its full command, then its folder when it runs elsewhere than the header says.
+
+    Without a header there is no folder to compare with, so no suffix. ``redact`` filters every word of the command and
+    the suffix's folder, each on its own: filtering the joined line once more would let a hidden header value swallow
+    every word after it, since a header runs to the end of its line.
+    """
+    line = COMMAND_PROMPT + command_text(request.program_filename, request.arguments, redact=redact, windows=windows)
+    if header is None:
+        return line
+    suffix = working_dir_suffix(request.working_dir, header.directory)
+    if redact is not None:
+        suffix = redact(suffix)
+    return line + suffix
+
+
+# A hosting service answers "repository not found" for a private repository the chosen account cannot see, so the
+# console points at the account as the other likely cause.
+REPOSITORY_NOT_FOUND_LINE_PATTERN = re.compile(r"^(?:remote:\s*)?fatal: repository '.*' not found(?=\r?\n?$)", re.IGNORECASE)
+WRONG_ACCOUNT_HINT = " (or wrong account selected in settings)"
+
+
+def with_account_hint(line: str) -> str:
+    """Return a Git error line as the console shows it: a "repository not found" line also names a wrong account."""
+    match = REPOSITORY_NOT_FOUND_LINE_PATTERN.match(line)
+    if match is None:
+        return line
+    return match.group(0) + WRONG_ACCOUNT_HINT + line[match.end():]
+
+
+FAILED_TEXT = "Failed"
+FAILED_WITH_EXIT_TEMPLATE = "Failed (exit {return_code})"
+NOT_STARTED_TEXT = "Not started"
+CANCELLED_TEXT = "Cancelled"
+STOPPED_TEXT = "Stopped"
+# Endings of a request that may never have reached its launch: it did not start unless its command line was shown.
+NOT_STARTED_STATUS_SET = frozenset({ProcessStatus.START_FAILED, ProcessStatus.QUEUE_FULL})
+# Endings where GitPane stopped a running command at one of its limits: no output, too much output, total time.
+STOPPED_STATUS_SET = frozenset({ProcessStatus.IDLE_TIMEOUT, ProcessStatus.VOLUME, ProcessStatus.TIMEOUT})
+# Results after which nothing was written or nothing went through, so a form keeps what the user chose or typed for
+# another try.
+UNCHANGED_OUTCOME_STATUS_SET = frozenset((OperationStatus.REFUSED, OperationStatus.FAILED))
+# Results the user may let the console dismiss through Keep dialog open. An Abort is only reported once a requested native
+# Abort has been verified (rebase as well as cherry-pick and revert), so, like a success, nothing is left to inspect. A
+# pause without failure cause is dismissed the same way, though it is not listed here: the Rebase window, the banner or
+# the conflict question waits for the user, not the console.
+COMPLETED_STATUS_SET = frozenset((OperationStatus.SUCCESS, OperationStatus.ABORTED))
+
+
+END_TEXT_TEMPLATE = "{label}: {word}"
+# Names a clone's console gives its end line: the clone itself, and the later retry of the submodules it left missing.
+CLONE_LABEL = "Clone"
+RETRY_SUBMODULES_LABEL = "Retry submodules"
+# Name of the Stash pop operation: the title of its console, the start of its end line, and of the one its log keeps.
+STASH_POP_LABEL = "Stash pop"
+# Name of the rebase operation, used the same way by its console and its log.
+REBASE_LABEL = "Rebase"
+# Counts every reference whose result is not a success: refused, unknown or never sent. "Not pushed" rather than
+# "rejected", since only some of them were refused by the server.
+NOT_PUSHED_REFS_TEMPLATE = "{label}: {count} of {total} refs not pushed"
+# Counts every remote whose Fetch did not succeed, including the ones that never started after an earlier failure.
+FAILED_REMOTES_TEMPLATE = "{label}: {count} of {total} remotes failed"
+# A tag is deleted locally first, then on the server: this says the second step did not happen.
+DELETED_LOCALLY_ONLY_TEMPLATE = "{label}: deleted locally, not on the remote"
+# A branch is deleted on the server first, then locally: this says the local step did not happen.
+DELETED_REMOTELY_ONLY_TEMPLATE = "{label}: deleted on the remote, not locally"
+
+
+def operation_end_text(label: str, status: OperationStatus) -> str:
+    """Return the line that ends an operation which had none a reader could understand, such as ``Push: done``.
+
+    The log keeps the bare status (``success``); this is what the console shows in its place.
+    """
+    return END_TEXT_TEMPLATE.format(label=label, word=status.end_word)
+
+
+CAUSE_SEPARATOR = ": "
+# Sets the reason of a refusal apart from the end line it completes, which already holds a ": " of its own.
+END_CAUSE_SEPARATOR = " — "
+LINE_BREAK = "\n"
+
+
+def line_with_cause(head: str, cause: str) -> str:
+    """Return a head followed by its cause, or the head alone when there is no cause to give."""
+    if not cause:
+        return head
+    return head + CAUSE_SEPARATOR + cause
+
+
+def end_line_with_cause(end_text: str, cause: str) -> str:
+    """Return the end line of an operation followed by the reason it ended so, such as ``Create tag: not started — <reason>``.
+
+    A refusal then reads as one line that says why, instead of an end line and a separate line for its reason. Without a
+    reason the end line stays alone.
+    """
+    if not cause:
+        return end_text
+    return end_text + END_CAUSE_SEPARATOR + cause
+
+
+def _shown_lines(text: str) -> list[str]:
+    """Return the non-empty lines of a text as a terminal leaves them, without trace records and trailing blanks."""
+    lines: list[str] = []
+    for line in terminal_text(text).split(LINE_BREAK):
+        line = line.rstrip()
+        if line and not is_trace_line(line):
+            lines.append(line)
+    return lines
+
+
+def cause_without_shown_output(cause: str, shown_output: str) -> str:
+    """Return the part of a failure cause the console has not shown yet.
+
+    The console already showed the error output line by line. A cause that copies it, at its start, in its middle or at
+    its end, keeps only what GitPane adds. Both texts are read as a terminal leaves them, without trace records and
+    trailing blanks; the first run of cause lines equal to the output's lines is removed, and the rest is returned.
+    """
+    cause_lines = _shown_lines(cause)
+    output_lines = _shown_lines(shown_output)
+    output_line_count = len(output_lines)
+    if output_line_count:
+        for start in range(len(cause_lines) - output_line_count + 1):
+            if cause_lines[start:start + output_line_count] == output_lines:
+                cause_lines = cause_lines[:start] + cause_lines[start + output_line_count:]
+                break
+    return LINE_BREAK.join(cause_lines).strip()
+
+
+def cause_beyond_exit_code(cause: str, return_code: int | None) -> str:
+    """Return a failure cause without the generic sentence the runner writes for a silent failure.
+
+    That sentence only repeats the exit code the line already gives, so it becomes an empty cause. A cause without an
+    exit code, or different from that sentence, is returned as it is.
+    """
+    if return_code is not None and cause == EXIT_CODE_CAUSE_TEMPLATE.format(return_code=return_code):
+        return ""
+    return cause
+
+
+def process_end_line(result: ProcessResult, *, command_shown: bool) -> ConsoleLine | None:
+    """Return the line a console writes when a process ends, or None when a terminal would not mark the ending.
+
+    ``command_shown`` tells whether the console already wrote the process's ``$ `` line, which is what separates a
+    request that never started from a program that could not run once launched.
+
+    | Ending                                               | Line                                 | Colour                       |
+    |------------------------------------------------------|--------------------------------------|------------------------------|
+    | success, or an exit code the caller accepts          | none                                 |                              |
+    | failed                                               | ``Failed (exit N)``, then own cause  | red, neutral during a pause  |
+    | cancelled                                            | ``Cancelled: <cause>``               | orange                       |
+    | stopped at a limit (no output, too much, total time) | ``Stopped: <cause>``                 | red                          |
+    | refused before launch or queue full, no ``$`` line   | ``Not started: <cause>``             | red                          |
+    | could not run after its ``$`` line, or anything else | ``Failed: <cause>``                  | red                          |
+
+    An accepted exit code is a success: a lookup that may find nothing ends with 1 when nothing is there, and a red
+    line after it would make an operation that went well look broken. The cause loses the error output the console
+    already showed, and the runner's generic cause of a silent failure, which only repeats the exit code; an empty
+    cause leaves the word alone.
+    """
+    if result.status == ProcessStatus.SUCCESS:
+        return None
+    if result.status == ProcessStatus.FAILED and result.return_code in result.request.accepted_return_codes:
+        return None
+    cause = cause_beyond_exit_code(cause_without_shown_output(result.cause, result.stderr.decode("utf-8", "replace")), result.return_code)
+    if result.status == ProcessStatus.FAILED:
+        head = FAILED_TEXT if result.return_code is None else FAILED_WITH_EXIT_TEMPLATE.format(return_code=result.return_code)
+        return ConsoleLine(line_with_cause(head, cause), ConsoleTone.COMMAND_FAILURE)
+    if result.status == ProcessStatus.CANCELLED:
+        return ConsoleLine(line_with_cause(CANCELLED_TEXT, cause), ConsoleTone.CANCELLED)
+    if result.status in STOPPED_STATUS_SET:
+        return ConsoleLine(line_with_cause(STOPPED_TEXT, cause), ConsoleTone.FAILURE)
+    if result.status in NOT_STARTED_STATUS_SET and not command_shown:
+        return ConsoleLine(line_with_cause(NOT_STARTED_TEXT, cause), ConsoleTone.FAILURE)
+    return ConsoleLine(line_with_cause(FAILED_TEXT, cause), ConsoleTone.FAILURE)

gitpane/operation/console_tone.py

@@ -0,0 +1,76 @@
+"""Decide the colour an operation console gives a record.
+
+A Git error line is red, a warning orange, and the line that ends an operation takes the colour of its result. This
+module holds those rules without any Qt type, so the trace, the view and the tests share one definition of each tone.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import IntEnum
+
+from gitpane.operation.operation_status import OperationStatus
+
+
+class ConsoleTone(IntEnum):
+    """Say how a console line is coloured; the view stores it as the state of the line's Qt block."""
+
+    # Qt gives -1 to a block that never received a state, so a neutral line needs no state at all.
+    NEUTRAL = -1
+    # An operation that reached its goal, or an abort that put the repository back as it was.
+    SUCCESS = 1
+    # An operation stopped to wait for the user, such as a conflict to resolve.
+    PAUSED = 2
+    # An operation the user stopped.
+    CANCELLED = 3
+    # An error GitPane reports itself; it stays red whatever the operation's outcome.
+    FAILURE = 4
+    # A Git process that ended in failure; neutral while the operation waits on a pause, since that is why Git stopped.
+    COMMAND_FAILURE = 5
+    # Git's own error and fatal lines; neutral while the operation waits on a pause, for the same reason.
+    GIT_ERROR = 6
+    # Git's own warning lines.
+    GIT_WARNING = 7
+    # A cause GitPane writes to explain why Git refused something, such as a setting to change: red and bold whatever
+    # the operation's outcome, a pause included, so it is read at first glance among Git's lines.
+    FAILURE_CAUSE = 8
+
+
+# During a pause, what Git says when it stops is the reason for the pause, not a failure.
+PAUSE_NEUTRAL_TONE_SET = frozenset({ConsoleTone.GIT_ERROR, ConsoleTone.COMMAND_FAILURE})
+
+
+GIT_ERROR_LINE_PATTERN = re.compile(r"^(?:remote:\s*)?(?:error:|fatal:|Trace incomplete:)", re.IGNORECASE)
+GIT_WARNING_LINE_PATTERN = re.compile(r"^(?:remote:\s*)?warning:", re.IGNORECASE)
+
+
+def git_output_tone(line: str) -> ConsoleTone:
+    """Return the colour of a line Git wrote on its error output: red for an error, orange for a warning.
+
+    A ``hint:`` line and progress stay neutral: they explain or report, they do not tell that something went wrong.
+    """
+    if GIT_ERROR_LINE_PATTERN.match(line):
+        return ConsoleTone.GIT_ERROR
+    if GIT_WARNING_LINE_PATTERN.match(line):
+        return ConsoleTone.GIT_WARNING
+    return ConsoleTone.NEUTRAL
+
+
+def result_tone(status: OperationStatus, *, failure_reported: bool = False, expected_stop: bool = False) -> ConsoleTone:
+    """Return the colour of the line that ends an operation, the one classification its console window also reads.
+
+    The end line and the state of the console window (paused or not) both come from here, so they cannot disagree.
+    Green is for an operation that reached its goal and for a verified Abort, which put the repository back as it was.
+    Orange is kept for what waits on the user: a pause, or a stop the caller expected (``expected_stop``, such as a
+    Stash pop stopped on conflicts), and a cancellation. A pause or an Abort that carries a failure cause
+    (``failure_reported``, such as a refused hook) is a real failure, red like everything else.
+    """
+    if status == OperationStatus.SUCCESS:
+        return ConsoleTone.SUCCESS
+    if status == OperationStatus.ABORTED and not failure_reported:
+        return ConsoleTone.SUCCESS
+    if (status == OperationStatus.PAUSED or expected_stop) and not failure_reported:
+        return ConsoleTone.PAUSED
+    if status == OperationStatus.CANCELLED:
+        return ConsoleTone.CANCELLED
+    return ConsoleTone.FAILURE