gitpane 1.0.0__py3-none-any.whl

gitpane/commit/commit_write.py

@@ -0,0 +1,830 @@
+"""Create native Git commits, reporting success only once their actual effects are checked."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import tempfile
+import uuid
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, QTimer, Signal
+
+from gitpane.config import COMMIT_IDLE_TIMEOUT_MS, DETACHED_HEAD_NAME, GIT_COMMIT_TIMEOUT_MS, REFERENCE_ROOT_PREFIX, SENSITIVE_VALUE_MIN_LENGTH, SUBMODULE_RECURSION_OFF_ARGUMENTS, SharedText
+from gitpane.history.history_parse import parse_commit
+from gitpane.history.repository_value import validate_oid
+from gitpane.operation.diagnostic import MASKED_VALUE, Diagnostic
+from gitpane.operation.launch_signature import LaunchSignature, sign_launch_paths, verify_launch_signature, worktree_location_paths
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.operation.repository_operation import GITPANE_CLOSING_TEXT, OperationAction, OperationIntent
+from gitpane.process.process_runner import LOCAL_WRITE_PROFILE, READ_PROFILE, ProcessRequest, ProcessResult, ProcessStatus
+from gitpane.sequencer.conflict import conflict_path_label
+from gitpane.sequencer.merge_state import read_merge_in_progress
+from gitpane.text.typed_text import typed_value
+from gitpane.worktree.command_sequence import FileTask, GitCommand, GitCommandError, ReadBatch
+from gitpane.worktree.worktree_snapshot import StagingSide, WorktreeKey, read_fingerprints, read_index
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.operation.diagnostic import PreparedDiagnostic
+    from gitpane.process.process_runner import ProcessRunner
+    from gitpane.sequencer.rebase_state import NativeMetadata
+    from gitpane.worktree.mutation import MutationService
+    from gitpane.worktree.worktree_service import WorktreeService
+    from gitpane.worktree.worktree_snapshot import WorktreeSnapshot
+
+HOOK_SAMPLE_SUFFIX = ".sample"
+POST_COMMIT_HOOK_BASENAME = "post-commit"
+PRE_COMMIT_HOOK_BASENAME = "pre-commit"
+# Git for Windows also runs a hook saved as a program with this suffix.
+WINDOWS_PROGRAM_SUFFIX = ".exe"
+# Windows has no executable permission, so Git for Windows runs any hook file that exists; elsewhere Git skips a hook
+# file without it.
+HOOK_EXECUTABLE_BIT_USED = os.name != "nt"
+# The neutral notice a commit leaves in the repository windows when files changed during it without any active commit hook.
+COMMIT_CREATED_NOTICE_PREFIX = "Commit created. "
+CHANGED_AFTER_COMMIT_NOTICE_TEMPLATE = "{subject} changed right after the commit; another program may have modified {pronoun}."
+INDEX_NOTICE_SUBJECT = "The index"
+COUNTED_FILES_NOTICE_SUBJECT_TEMPLATE = "{count} files"
+SINGLE_NOTICE_PRONOUN = "it"
+PLURAL_NOTICE_PRONOUN = "them"
+# Beyond this many files, the notice counts them instead of naming them, so it stays one line.
+NOTICE_NAMED_FILE_LIMIT = 3
+# The grouped HEAD read ends with the branch HEAD names, or with the detached HEAD word. That read gives bytes, so the
+# two values are encoded from their one text form instead of being written again here.
+DETACHED_HEAD_NAME_BYTES = DETACHED_HEAD_NAME.encode("ascii")
+REFERENCE_ROOT_PREFIX_BYTES = REFERENCE_ROOT_PREFIX.encode("ascii")
+# The lines of the grouped read: HEAD, its tree, one line per parent (none for a root commit), then the branch line.
+GROUPED_HEAD_MINIMUM_LINE_COUNT = 3
+HEAD_DESCRIPTION_ERROR = "Git described HEAD in an unexpected form"
+COMMIT_LAUNCH_CHANGED_CAUSE = "HEAD, references, configuration or the index changed before commit. Refresh before writing."
+COMMIT_LAUNCH_UNREADABLE_CAUSE = "The files checked before commit could not be read again. Refresh before writing."
+# The plain first sentences of a commit result that is not the requested commit; the object IDs and change flags go to
+# the details only.
+COMMIT_CHANGED_ELSEWHERE_CAUSE = "Commit created, but it also contains changes made by a hook or another program."
+# The plain first sentence of a commit Git did not create while files, the index or the branch changed: it says who
+# refused it when an active pre-commit hook did, and what changed. Files are named when few, otherwise counted.
+PRE_COMMIT_HOOK_REFUSED_NAMED_FILES_TEMPLATE = "Commit refused by your pre-commit hook. It also changed: {subject}."
+PRE_COMMIT_HOOK_REFUSED_TEMPLATE = "Commit refused by your pre-commit hook. It also changed {subject}."
+COMMIT_FAILED_NAMED_FILES_TEMPLATE = "Commit failed, and files changed: {subject}. Click {details} for full information."
+COMMIT_FAILED_TEMPLATE = "Commit failed, and {subject} changed. Click {details} for full information."
+NO_COMMIT_INDEX_SUBJECT = "the index"
+NO_COMMIT_BRANCH_SUBJECT = "the current branch"
+NO_COMMIT_FOUND_CAUSE = "Git reported success, but no new commit was found."
+SUCCESS_WITH_CHANGES_LOG_CAUSE = "Commit created as requested; files or the index changed around it."
+PRE_COMMIT_HOOK_CONTENT_LOG_CAUSE = "Commit created with files an active pre-commit hook added or changed."
+REVIEW_BEFORE_RETRY_TEXT = "Review the changes before retrying."
+GIT_CAUSE_DETAIL_PREFIX = "Git: "
+
+
+@dataclass(frozen=True)
+class CommitHeadFacts:
+    """HEAD, its tree, its parents in their order and the branch HEAD names, as read together by Git.
+
+    The branch keeps the exact bytes symbolic-ref prints, line end included; a detached HEAD has empty bytes. Without
+    any commit, HEAD has no object ID, the tree is empty and there are no parents.
+    """
+
+    head_oid: str | None
+    tree_oid: str
+    parent_oids: tuple[str, ...]
+    ref_target: bytes
+
+
+def parse_commit_head(output: bytes) -> CommitHeadFacts:
+    """Split the grouped HEAD read by position, accepting only full object IDs and a branch name or the detached marker.
+
+    Every line but the last is an object ID, so the last line alone can be the branch; an answer where it is not one
+    is refused rather than guessed, and the caller then reads each fact separately.
+    """
+    lines = output.removesuffix(b"\n").split(b"\n")
+    if len(lines) < GROUPED_HEAD_MINIMUM_LINE_COUNT:
+        raise ValueError(HEAD_DESCRIPTION_ERROR)
+    head_line, tree_line, *parent_lines, reference_line = lines
+    try:
+        head_oid = validate_oid(head_line.decode("ascii"))
+        tree_oid = validate_oid(tree_line.decode("ascii"))
+        parent_oids = []
+        for parent_line in parent_lines:
+            parent_oids.append(validate_oid(parent_line.decode("ascii")))
+    except (UnicodeDecodeError, ValueError) as error:
+        raise ValueError(HEAD_DESCRIPTION_ERROR) from error
+    if reference_line == DETACHED_HEAD_NAME_BYTES:
+        ref_target = b""
+    elif reference_line.startswith(REFERENCE_ROOT_PREFIX_BYTES):
+        # Restore the line end symbolic-ref prints, so both reads give the same bytes for the same branch.
+        ref_target = reference_line + b"\n"
+    else:
+        raise ValueError(HEAD_DESCRIPTION_ERROR)
+    return CommitHeadFacts(head_oid, tree_oid, tuple(parent_oids), ref_target)
+
+
+def read_commit_head() -> Generator[GitCommand | ReadBatch, object, CommitHeadFacts]:
+    """Read HEAD, its tree, its parents and its branch with one Git process on the normal path.
+
+    When Git refuses the grouped read, as it does without any commit, or answers in a form that cannot be split with
+    certainty, the facts are read again separately. A read that timed out, was cancelled or could not start stays an
+    error: its partial output is never taken for an answer.
+    """
+    try:
+        output = yield GitCommand(["rev-parse", "HEAD", "HEAD^{tree}", "HEAD^@", "--symbolic-full-name", "HEAD"])
+    except GitCommandError as error:
+        # Only a failed process ran to its end and refused: timeouts, cancellations and failed starts say nothing about
+        # the repository and must never be answered by another read.
+        if error.process_status != ProcessStatus.FAILED:
+            raise
+        return (yield from _read_commit_head_separately())
+    try:
+        return parse_commit_head(output)
+    except ValueError:
+        return (yield from _read_commit_head_separately())
+
+
+def _read_commit_head_separately() -> Generator[GitCommand | ReadBatch, object, CommitHeadFacts]:
+    """Verify HEAD on its own, read its tree and parents by that object ID, and read the branch HEAD names.
+
+    A HEAD without a commit is accepted only when HEAD names a branch, which is the only way Git can have no commit
+    yet: a detached HEAD always points at an object, so an empty answer for both is an error.
+    """
+    head_output, ref_target = yield ReadBatch((GitCommand(["rev-parse", "--verify", "--quiet", "HEAD"], accepted_codes=(0, 1)),
+                                               GitCommand(["symbolic-ref", "--quiet", "HEAD"], accepted_codes=(0, 1))))
+    head_text = head_output.strip().decode("ascii", "replace")
+    if not head_text:
+        if not ref_target:
+            raise ValueError("HEAD names neither a commit nor a branch; Refresh to inspect the repository")
+        return CommitHeadFacts(None, "", (), ref_target)
+    head_oid = validate_oid(head_text)
+    identity_output = yield GitCommand(["rev-parse", head_oid + "^{tree}", head_oid + "^@"])
+    tree_line, *parent_lines = identity_output.removesuffix(b"\n").split(b"\n")
+    tree_oid = validate_oid(tree_line.decode("ascii", "replace"))
+    parent_oids = []
+    for parent_line in parent_lines:
+        parent_oids.append(validate_oid(parent_line.decode("ascii", "replace")))
+    return CommitHeadFacts(head_oid, tree_oid, tuple(parent_oids), ref_target)
+
+
+def reduced_merge_parent_oids(parent_oids: tuple[str, ...]) -> Generator[GitCommand, object, tuple[str, ...]]:
+    """Answer the parents Git records when it concludes a merge that may drop redundant ones, in Git's order.
+
+    Without --no-ff, git commit removes every parent that another parent already contains, and duplicates, keeping the
+    others in their order. Git lists the parents to keep; their order is taken from ``parent_oids``, never from its output.
+    """
+    output = yield GitCommand(["merge-base", "--independent", *parent_oids], profile=READ_PROFILE)
+    independent_set = set()
+    for line in output.decode("ascii").split():
+        independent_set.add(validate_oid(line))
+    reduced_oids = []
+    for oid in parent_oids:
+        if oid in independent_set and oid not in reduced_oids:
+            reduced_oids.append(oid)
+    return tuple(reduced_oids)
+
+
+def capture_commit_launch_signature(context: RepositoryContext, index_filename: str) -> LaunchSignature:
+    """Sign the index, every file and folder the reference signature covers, and the files and folders that name this worktree.
+
+    The reference files include HEAD, the branches, packed and table references and the configuration of every
+    related worktree. The Git directories, the index folder and the worktree root are containing folders, compared
+    by identity only; a linked worktree's pointer files are signed like any other file.
+    """
+    from gitpane.reference.reference_edit import reference_signature_paths
+
+    reference_filenames, watched_dirs = reference_signature_paths(context)
+    location_filenames, location_parent_dirs = worktree_location_paths(context)
+    filenames = [*reference_filenames, index_filename, *location_filenames]
+    parent_dirs = [os.path.dirname(index_filename), *location_parent_dirs]
+    return sign_launch_paths(filenames, watched_dirs, parent_dirs)
+
+
+def prove_commit_launch(context: RepositoryContext, index_filename: str, expected_index_content: bytes | None, expected_reference_signature: tuple) -> LaunchSignature:
+    """Compare the index and reference contents with the checked ones between two signatures of the same paths.
+
+    The reference contents are compared with the signature taken before the checks started, so a change made by
+    another program meanwhile is refused instead of adopted. The signature handed back describes exactly the state
+    these comparisons accepted; it is the only thing the launch callback checks again.
+    """
+    from gitpane.reference.reference_edit import reference_signature
+
+    before = capture_commit_launch_signature(context, index_filename)
+    if read_index(index_filename) != expected_index_content:
+        raise ValueError("The index changed before commit. Refresh before writing.")
+    if reference_signature(context) != expected_reference_signature:
+        raise ValueError("HEAD or repository references changed before commit. Refresh before writing.")
+    after = capture_commit_launch_signature(context, index_filename)
+    if after != before:
+        raise ValueError("HEAD, references, configuration or the index changed while the commit was checked. Refresh before writing.")
+    return after
+
+
+def commit_hook_exists(hooks_dir: str) -> bool:
+    """Tell whether the hooks directory Git resolved for a worktree holds anything that could run during a commit.
+
+    Every file except Git's own samples counts, whatever its name or mode: Git runs more hooks than the commit ones,
+    and a helper could live under any name. Only a path that is not a directory, or a complete listing without such a
+    file, answers False; any error raised while inspecting it answers True, so a doubt keeps the full byte checks.
+    """
+    try:
+        if not os.path.isdir(hooks_dir):
+            return False
+        with os.scandir(hooks_dir) as entries:
+            for entry in entries:
+                if entry.name.endswith(HOOK_SAMPLE_SUFFIX):
+                    continue
+                if entry.is_file():
+                    return True
+    except OSError:
+        return True
+    return False
+
+
+def git_hook_active(hooks_dir: str, hook_basename: str, *, executable_bit_used: bool = HOOK_EXECUTABLE_BIT_USED) -> bool:
+    """Tell whether Git would run the hook with this name from the hooks directory it resolved for a worktree.
+
+    Git looks for a file with the hook's name and, on Linux and macOS, runs it only when it may be executed. Git for
+    Windows does not use that permission: the file, or the same name with .exe, only has to exist. A folder with
+    that name is not run, and a directory that cannot be read answers False: the commit result then only loses the
+    knowledge that the user's own hook explains a change.
+    """
+    candidate_basenames = [hook_basename]
+    if not executable_bit_used:
+        candidate_basenames.append(hook_basename + WINDOWS_PROGRAM_SUFFIX)
+    for basename in candidate_basenames:
+        hook_filename = os.path.join(hooks_dir, basename)
+        if not os.path.isfile(hook_filename):
+            continue
+        if not executable_bit_used or os.access(hook_filename, os.X_OK):
+            return True
+    return False
+
+
+def changed_working_paths(before: CommitState, after: CommitState) -> list[bytes]:
+    """List, sorted, the files hashed at both commit boundaries whose bytes differ between them."""
+    paths = []
+    for path, fingerprint in before.working_by_path.items():
+        if after.working_by_path.get(path) != fingerprint:
+            paths.append(path)
+    return sorted(paths)
+
+
+def noticed_paths(before: CommitState, after: CommitState) -> list[bytes]:
+    """List, sorted, the files a commit notice names: changed bytes, and files Git lists after the commit whose earlier bytes are unknown.
+
+    A file hashed for the first time after the commit only because a hook appeared is not named: nothing says it changed.
+    """
+    listed_path_set: set[bytes] = set()
+    for entry in after.snapshot.entries:
+        listed_path_set.update(entry.paths)
+    paths = changed_working_paths(before, after)
+    for path in after.working_by_path.keys() - before.working_by_path.keys():
+        if path in listed_path_set:
+            paths.append(path)
+    return sorted(paths)
+
+
+def changed_files_subject(paths: list[bytes]) -> tuple[str, bool]:
+    """Name the changed files the way every commit sentence does, and tell whether the answer names them.
+
+    Up to three files are named in sorted order (« a.txt », « a.txt and b.txt », « a.txt, b.txt and c.txt »), more
+    are counted (« 4 files ») so the sentence stays one line. Without any file the subject is empty.
+    """
+    labels = []
+    for path in sorted(paths):
+        labels.append(conflict_path_label(path))
+    if not labels:
+        return "", False
+    if len(labels) == 1:
+        return labels[0], True
+    if len(labels) <= NOTICE_NAMED_FILE_LIMIT:
+        last_label = labels.pop()
+        return ", ".join(labels) + " and " + last_label, True
+    return COUNTED_FILES_NOTICE_SUBJECT_TEMPLATE.format(count=len(labels)), False
+
+
+def commit_change_notice(paths: list[bytes], index_changed: bool) -> str:
+    """Build the one neutral sentence telling the user which files, or the index, changed right after a commit.
+
+    Up to three files are named in order, more are counted; the index is named only when no file changed. Without
+    any change the answer is empty.
+    """
+    subject, _names_files = changed_files_subject(paths)
+    if not subject and not index_changed:
+        return ""
+    if not subject:
+        subject, pronoun = INDEX_NOTICE_SUBJECT, SINGLE_NOTICE_PRONOUN
+    elif len(paths) == 1:
+        pronoun = SINGLE_NOTICE_PRONOUN
+    else:
+        pronoun = PLURAL_NOTICE_PRONOUN
+    return COMMIT_CREATED_NOTICE_PREFIX + CHANGED_AFTER_COMMIT_NOTICE_TEMPLATE.format(subject=subject, pronoun=pronoun)
+
+
+def no_commit_change_cause(paths: list[bytes], index_changed: bool, refused_by_pre_commit_hook: bool) -> str:
+    """Build the warning of a commit Git did not create while something changed: who refused it, and what changed.
+
+    A user who clicked Commit must not read that nothing happened. When Git refused and an active pre-commit hook
+    explains the refusal, the sentence blames that hook; otherwise it says the commit failed and points at the details,
+    where Git's own message stays. Files are named or counted; with no file to name, the index or the current branch is.
+    """
+    subject, names_files = changed_files_subject(paths)
+    if not subject:
+        subject = NO_COMMIT_INDEX_SUBJECT if index_changed else NO_COMMIT_BRANCH_SUBJECT
+    if refused_by_pre_commit_hook:
+        template = PRE_COMMIT_HOOK_REFUSED_NAMED_FILES_TEMPLATE if names_files else PRE_COMMIT_HOOK_REFUSED_TEMPLATE
+    else:
+        template = COMMIT_FAILED_NAMED_FILES_TEMPLATE if names_files else COMMIT_FAILED_TEMPLATE
+    # The label of the Show details button of Prepare changes, read from the one shared value so the sentence names the real button.
+    return template.format(subject=subject, details=SharedText.RESULT_DETAILS.value)
+
+
+def index_records_by_path(index_entries: bytes) -> dict[bytes, list[bytes]]:
+    """Group the records of ls-files --stage -z by path, so a path with several conflict stages keeps all of them."""
+    records_by_path: dict[bytes, list[bytes]] = {}
+    for record in index_entries.split(b"\0"):
+        if not record:
+            continue
+        _metadata, _separator, path = record.partition(b"\t")
+        records_by_path.setdefault(path, []).append(record)
+    return records_by_path
+
+
+def changed_staged_paths(before: CommitState, after: CommitState) -> list[bytes]:
+    """List, sorted, the paths whose index entries differ between two commit boundaries: added, changed or removed.
+
+    It tells which files a hook staged during the commit, without asking Git again.
+    """
+    before_records_by_path = index_records_by_path(before.index_entries)
+    after_records_by_path = index_records_by_path(after.index_entries)
+    paths = []
+    for path in before_records_by_path.keys() | after_records_by_path.keys():
+        if sorted(before_records_by_path.get(path, [])) != sorted(after_records_by_path.get(path, [])):
+            paths.append(path)
+    return sorted(paths)
+
+
+def describe_commit_boundaries(before: CommitState, after: CommitState) -> str:
+    """Describe in English, for the details and the --log file, what changed around a commit, with the Git identities.
+
+    The commit message is never part of it; the caller still masks it, as for any text a commit diagnostic shows.
+    """
+    changed_labels = []
+    for path in changed_working_paths(before, after):
+        changed_labels.append(conflict_path_label(path))
+    unverified_labels = []
+    for path in sorted(after.working_by_path.keys() - before.working_by_path.keys()):
+        unverified_labels.append(conflict_path_label(path))
+    post_commit_hook_active = before.post_commit_hook_active or after.post_commit_hook_active
+    pre_commit_hook_active = before.pre_commit_hook_active or after.pre_commit_hook_active
+    lines = [
+        "A post-commit hook is active." if post_commit_hook_active else "No active post-commit hook was found.",
+        "A pre-commit hook is active." if pre_commit_hook_active else "No active pre-commit hook was found.",
+        f"Index changed: {'yes' if before.index_entries != after.index_entries else 'no'}",
+    ]
+    staged_labels = []
+    for path in changed_staged_paths(before, after):
+        staged_labels.append(conflict_path_label(path))
+    if staged_labels:
+        lines.append(f"Staged files changed during the commit: {', '.join(staged_labels)}")
+    lines.append(f"Working files changed: {', '.join(changed_labels) or 'none'}")
+    if unverified_labels:
+        lines.append(f"Files whose previous bytes were not captured ({len(unverified_labels)}): {', '.join(unverified_labels)}")
+    lines.append(f"HEAD before: {before.snapshot.head_oid or 'unborn'}; HEAD after: {after.snapshot.head_oid or 'unborn'}")
+    lines.append(f"Tree: {after.tree_oid or 'none'}; parents: {', '.join(after.parent_oids) or 'none'}")
+    return "\n".join(lines)
+
+
+def mask_commit_message(message: str, text: str) -> str:
+    """Hide every line of the commit message, and the whole message, wherever it appears in ``text``.
+
+    A line shorter than the length diagnostics ever hide is left alone, and a line is only hidden where it is not glued
+    to a letter or digit on either side: otherwise a message line such as "a" or "12" would also be replaced inside the
+    commit IDs the details show, which are exactly what lets the user find the commit again. Each line is also hidden
+    without its trailing blanks, the form Git writes once its cleanup has run on the message.
+    """
+    hidden_set = {message}
+    for line in message.splitlines():
+        hidden_set.add(line)
+        hidden_set.add(line.rstrip())
+    for line in sorted(hidden_set, key=len, reverse=True):
+        if len(line.strip()) < SENSITIVE_VALUE_MIN_LENGTH:
+            continue
+        text = re.sub(r"(?<![0-9A-Za-z])" + re.escape(line) + r"(?![0-9A-Za-z])", MASKED_VALUE, text)
+    return text
+
+
+@dataclass(frozen=True)
+class CommitRequest:
+    """Freeze the intended index, HEAD and complete UTF-8 message for one explicit action."""
+
+    operation_id: str
+    key: WorktreeKey
+    expected_head_oid: str | None
+    index_fingerprint: str
+    amend: bool
+    message: bytes
+    snapshot: WorktreeSnapshot
+    expected_head_ref: str | None = None
+    rebase_capture: tuple[NativeMetadata | None, ...] | None = None
+
+    @classmethod
+    def capture(cls, snapshot: WorktreeSnapshot, message: str, amend: bool = False) -> CommitRequest:
+        """Capture the currently displayed preparation without including working files.
+
+        The message is sent exactly as typed and Git applies the repository's ``commit.cleanup`` setting: by default it
+        drops blank lines at both ends and trailing blanks of each line while keeping the indentation of the first line,
+        and ``verbatim`` keeps the message exactly. Cleaning the message in GitPane before Git would override that
+        setting. Commit and Commit & push both capture here, and the draft the caller holds stays as typed. Diagnostics
+        mask the sent message and its lines as Git writes them.
+        """
+        operation_id = uuid.uuid4().hex
+        intent = OperationIntent.capture(operation_id, snapshot.context, snapshot.git_filename)
+        return cls(operation_id, snapshot.key, snapshot.head_oid, snapshot.index_fingerprint, amend, message.encode("utf-8"), snapshot,
+                   rebase_capture=intent.rebase_capture)
+
+
+@dataclass(frozen=True)
+class CommitState:
+    """Keep observed Git identities and working fingerprints separate from the user's intent.
+
+    ``post_commit_hook_active`` and ``pre_commit_hook_active`` tell whether Git would run that hook from the hooks
+    directory of this boundary; both are False when that directory is unknown.
+    """
+
+    snapshot: WorktreeSnapshot
+    tree_oid: str
+    parent_oids: tuple[str, ...]
+    index_entries: bytes
+    working_by_path: dict[bytes, str]
+    ref_target: bytes
+    post_commit_hook_active: bool = False
+    pre_commit_hook_active: bool = False
+
+
+@dataclass(frozen=True)
+class CommitOutcome:
+    """Retain observed before/after state even when the native command reports failure.
+
+    ``commit_created`` tells that the read after the write proved a new commit, whatever the status. ``notice`` is a
+    neutral sentence for the repository windows, and ``log_diagnostic`` the details written only to the --log file,
+    for a commit that succeeded although files changed around it.
+    """
+
+    operation_id: str
+    key: WorktreeKey
+    status: OperationStatus
+    before: CommitState | None
+    after: CommitState | None
+    diagnostic: PreparedDiagnostic | None
+    process_status: ProcessStatus | None = None
+    commit_created: bool = False
+    notice: str = ""
+    log_diagnostic: PreparedDiagnostic | None = None
+
+
+@dataclass
+class _CommitOperation:
+    """Own the reservation and captured message until reconciliation has completed.
+
+    ``merge_parent_oids`` are the commits a merge waiting at launch adds after HEAD, as Git listed them then; they are
+    the only parents beyond HEAD a Commit accepts. ``merge_expected_parent_oids`` are the parents the commit concluding
+    that merge must have: HEAD then those commits, less the ones Git drops as already contained in another parent.
+    """
+
+    request: CommitRequest
+    before: CommitState | None = None
+    expected_tree_oid: str = ""
+    merge_parent_oids: tuple[str, ...] = ()
+    merge_expected_parent_oids: tuple[str, ...] = ()
+    reference_signature: tuple = ()
+    launch_signature: LaunchSignature | None = None
+    reconciling: bool = False
+
+
+class CommitService(QObject):
+    """Reserve GitPane writes while letting native Git own its own index and ref locks."""
+
+    finished = Signal(object)
+    waiting = Signal(object)
+
+    def __init__(self, runner: ProcessRunner, worktree_service: WorktreeService, mutation: MutationService, parent: QObject | None = None) -> None:
+        """Inject the existing process, read and mutation owners for shared lifetime control."""
+        super().__init__(parent)
+        self.runner = runner
+        self.worktree_service = worktree_service
+        self.mutation = mutation
+        self.repository_operation = mutation.repository_operation
+        self.active_by_id: dict[str, _CommitOperation] = {}
+        self.outcome_by_id: dict[str, CommitOutcome] = {}
+        runner.finished.connect(self._process_finished)
+        runner.stop_requested.connect(self._stopping)
+
+    def submit(self, request: CommitRequest) -> str:
+        """Validate and reserve exactly one user request without retrying rejected writes.
+
+        A refusal says first that GitPane is closing, since no write is accepted any more whatever else is wrong; then it
+        gives the write policy's reason, or else the real reason the reservation was refused, worked out right away so it
+        describes the state that refused it.
+        """
+        if request.operation_id in self.active_by_id or request.operation_id in self.outcome_by_id:
+            return request.operation_id
+        commit_action = OperationAction.AMEND if request.amend else OperationAction.COMMIT
+        action = OperationAction.COMMIT_PUSH if request.expected_head_ref is not None else commit_action
+        intent = OperationIntent.capture(request.operation_id, request.snapshot.context, request.snapshot.git_filename, action=action, rebase_capture=request.rebase_capture,
+                                         operation=commit_action.commit_label)
+        reason = GITPANE_CLOSING_TEXT if self.repository_operation.closed else self.repository_operation.policy_diagnostic(intent)
+        if reason or not self.mutation.acquire(request.snapshot, request.operation_id, action=action, operation=commit_action.commit_label):
+            diagnostic = self._diagnostic(request, reason or self.mutation.acquire_refusal_cause(request.snapshot, request.operation_id, action=action, operation=commit_action.commit_label))
+            outcome = CommitOutcome(request.operation_id, request.key, OperationStatus.REFUSED, None, None, diagnostic)
+            self.outcome_by_id[request.operation_id] = outcome
+            QTimer.singleShot(0, lambda: self.finished.emit(outcome))
+            return request.operation_id
+        operation = _CommitOperation(request)
+        self.active_by_id[request.operation_id] = operation
+
+        def prepared(value: object, error: Exception | None) -> None:
+            """Launch the native write only after every captured precondition still matches."""
+            if error is not None:
+                self._finish(operation, OperationStatus.REFUSED, None, self._diagnostic(request, str(error)))
+                return
+            snapshot = request.snapshot
+            arguments = [*SUBMODULE_RECURSION_OFF_ARGUMENTS, "commit", "--file=-"]
+            if request.amend:
+                arguments.append("--amend")
+
+            def validate_launch() -> None:
+                """Recheck the current owner, write policy and authority, then only the metadata the launch proof covered.
+
+                The index and reference contents were compared by a file worker when the preparation ended; here, on
+                the Qt thread, their metadata alone says whether anything moved while the commit waited to start.
+                """
+                self.mutation.validate_write(request.key)
+                if operation.launch_signature is None:
+                    raise ValueError("The commit launch was not checked. Refresh before writing.")
+                verify_launch_signature(operation.launch_signature, COMMIT_LAUNCH_CHANGED_CAUSE, COMMIT_LAUNCH_UNREADABLE_CAUSE)
+
+            process_request = ProcessRequest(request.operation_id, snapshot.git_filename, arguments, snapshot.context.repository_dir, GIT_COMMIT_TIMEOUT_MS,
+                                             session_id="commit:" + request.key.git_dir, stdin=request.message, idle_timeout_ms=COMMIT_IDLE_TIMEOUT_MS,
+                                             operation="Amend" if request.amend else "Commit", wait_for_exit_on_stop=True, profile=LOCAL_WRITE_PROFILE, operation_id=request.operation_id,
+                                             before_start=validate_launch)
+            try:
+                self.runner.start(process_request)
+            except (ValueError, RuntimeError) as failure:
+                self._process_finished(ProcessResult(process_request, ProcessStatus.START_FAILED, None, str(failure), b""))
+
+        self.worktree_service.run(request.snapshot.context, request.snapshot.git_filename, self._prepare(operation), prepared, operation_id=request.operation_id)
+        return request.operation_id
+
+    def _prepare(self, operation: _CommitOperation) -> Generator:
+        """Check freshness, compute the expected tree with a private index copy, then prove what the launch will check.
+
+        The displayed read is checked against fresh Git reads rather than read again in full. Once the tree is known,
+        a file worker compares the index and reference contents with the checked ones and leaves a metadata signature,
+        which is all the launch callback reads again on the Qt thread.
+
+        A merge waiting for its commit is read from its files by a file worker, not by Git: its commits become the
+        expected parents after HEAD, and it may be concluded with nothing staged, since keeping HEAD's side of every
+        file is a valid resolution Git accepts.
+        """
+        from gitpane.reference.reference_edit import reference_signature
+
+        request = operation.request
+        snapshot = request.snapshot
+        if not snapshot.fresh or request.key != snapshot.key or request.key != WorktreeKey.from_context(snapshot.context):
+            raise ValueError("Preparation is stale; refresh the changes")
+        if request.expected_head_oid != snapshot.head_oid or request.index_fingerprint != snapshot.index_fingerprint:
+            raise ValueError("Commit intention does not match the displayed preparation")
+        if not typed_value(request.message.decode("utf-8")) or b"\0" in request.message:
+            raise ValueError("Enter a nonblank commit message without NUL characters")
+        if request.amend and request.expected_head_oid is None:
+            raise ValueError("There is no HEAD commit to amend")
+        # Capture before the native identity reads so a queued launch cannot adopt newer ref storage.
+        operation.reference_signature = yield FileTask(lambda: reference_signature(snapshot.context))
+        before = yield from self._read_state(snapshot)
+        if request.expected_head_ref is not None and before.ref_target.decode("utf-8", "surrogateescape").strip() != request.expected_head_ref:
+            raise ValueError("The current branch changed after Commit & push was captured; refresh the changes")
+        # The state before the write carries the displayed read itself, which _read_state has just proven current: the
+        # identity, the index path and bytes, HEAD and the configuration and attributes were compared with fresh Git
+        # reads. Equal index bytes and HEAD give the same staged entries and the same conflict stages, so the entries
+        # below describe the index the commit will record.
+        if any(entry.conflict_stages for entry in before.snapshot.entries):
+            raise ValueError("Resolve all conflicts before committing")
+        if not request.amend:
+            git_dir = snapshot.context.git_dir
+            merge = yield FileTask(lambda: read_merge_in_progress(git_dir))
+            if merge is not None:
+                operation.merge_parent_oids = merge.parent_oids
+                head_parents = (request.expected_head_oid,) if request.expected_head_oid else ()
+                operation.merge_expected_parent_oids = (*head_parents, *merge.parent_oids)
+                if not merge.keeps_every_parent and len(operation.merge_expected_parent_oids) > 1:
+                    operation.merge_expected_parent_oids = yield from reduced_merge_parent_oids(operation.merge_expected_parent_oids)
+        if not request.amend and not operation.merge_parent_oids and not any(entry.side == StagingSide.STAGED for entry in before.snapshot.entries):
+            raise ValueError("Stage changes before committing")
+        recovery = self.mutation.recover(snapshot.context, snapshot.index_filename, operation_id=request.operation_id)
+        if recovery:
+            raise ValueError(recovery)
+        operation.before = before
+        # write-tree may update cached index metadata, so compute against a private copy.
+        with tempfile.TemporaryDirectory(prefix="gitpane-commit-", dir=snapshot.context.git_dir) as temporary_dir:
+            index_filename = os.path.join(temporary_dir, "index")
+            if before.snapshot.index_content is not None:
+                yield FileTask(lambda: shutil.copy2(snapshot.index_filename, index_filename))
+            tree = yield GitCommand([*SUBMODULE_RECURSION_OFF_ARGUMENTS, "write-tree"], environment_by_name={"GIT_INDEX_FILE": index_filename}, profile=LOCAL_WRITE_PROFILE)
+            operation.expected_tree_oid = tree.strip().decode("ascii")
+        # HEAD and the branch are among the reference files, so this proof also covers what separate HEAD reads checked.
+        reference = operation.reference_signature
+        operation.launch_signature = yield FileTask(lambda: prove_commit_launch(snapshot.context, snapshot.index_filename, snapshot.index_content, reference))
+
+    def _read_state(self, snapshot: WorktreeSnapshot, previous: CommitState | None = None) -> Generator:
+        """Establish Git identities and the working bytes a commit could change, at one commit boundary.
+
+        Before the write, without a previous state, the displayed snapshot is not read again: WorktreeService.verify
+        compares its identity, index path and bytes, HEAD, configuration and attributes with fresh Git reads, and the
+        state carries that same snapshot. After the write, with the previous state, a complete capture is read.
+
+        HEAD, its tree, its parents and its branch are read at both ends of the boundary, around the file reads, and
+        must not move, nor may the index bytes. Files Git lists, files of the displayed preparation and files already
+        hashed at the previous boundary are always hashed. Every other tracked file, hidden index entries included, is
+        hashed only when the hooks directory of this boundary holds a hook, since only a hook runs inside the commit and
+        can rewrite a file Git still reports as clean. A snapshot that did not resolve its hooks directory keeps the
+        full hashing.
+        """
+        if previous is None:
+            yield from self.worktree_service.verify(snapshot, ())
+            current = snapshot
+        else:
+            current = yield from self.worktree_service.capture(snapshot.context, snapshot.git_filename, snapshot.generation)
+        facts = yield from read_commit_head()
+        hook_present = True
+        post_commit_hook_active = False
+        pre_commit_hook_active = False
+        if current.hooks_dir is not None:
+            hooks_dir = current.hooks_dir
+            hook_present, post_commit_hook_active, pre_commit_hook_active = yield FileTask(lambda: (commit_hook_exists(hooks_dir), git_hook_active(hooks_dir, POST_COMMIT_HOOK_BASENAME),
+                                                                                                   git_hook_active(hooks_dir, PRE_COMMIT_HOOK_BASENAME)))
+        index_entries = current.index_entries
+        if index_entries is None:
+            index_entries = yield GitCommand(["ls-files", "--stage", "-z"])
+        paths = list(snapshot.fingerprint_by_path)
+        tracked_paths = []
+        for record in index_entries.split(b"\0"):
+            if record:
+                _metadata, separator, path = record.partition(b"\t")
+                if not separator:
+                    raise ValueError("Malformed Git index entry output")
+                tracked_paths.append(path)
+        if hook_present:
+            # Equal metadata can hide a same-size rewrite with restored timestamps, even when Git reports a clean file.
+            paths.extend(current.hidden_index_paths)
+            paths.extend(tracked_paths)
+        if previous is not None:
+            paths.extend(previous.working_by_path)
+        for entry in current.entries:
+            paths.extend(entry.paths)
+        working_by_path = yield from read_fingerprints(snapshot.context, tuple(paths))
+        after_facts = yield from read_commit_head()
+        index = yield FileTask(lambda: read_index(current.index_filename))
+        if facts.head_oid != current.head_oid or after_facts != facts or index != current.index_content:
+            raise ValueError("Repository changed during commit verification; Refresh to inspect the result")
+        return CommitState(current, facts.tree_oid, facts.parent_oids, index_entries, working_by_path, facts.ref_target, post_commit_hook_active, pre_commit_hook_active)
+
+    def _stopping(self, process_request: ProcessRequest, cause: str) -> None:
+        """Explain an exceeded budget while the native Git process still owns its hooks."""
+        operation = self.active_by_id.get(process_request.request_id)
+        if operation is not None:
+            self.waiting.emit(self._diagnostic(operation.request, cause + ". Waiting for Git and its hooks to exit; no second commit will start"))
+
+    def _process_finished(self, result: ProcessResult) -> None:
+        """Reconcile a single terminal process response while retaining the write reservation."""
+        operation = self.active_by_id.get(result.request.request_id)
+        if operation is None or operation.reconciling:
+            return
+        operation.reconciling = True
+        request = operation.request
+
+        def inspected(after: CommitState | None, error: Exception | None) -> None:
+            """Classify the result from the states read before and after the write.
+
+            The commit that was asked for, with its expected tree, parents and branch, is a success even when files or
+            the index changed around it: a hook or another program changed them, not the commit. Those details go to
+            the --log file; only when neither a pre-commit nor a post-commit hook is active to explain them does a
+            neutral notice also name the changed files. A new commit with the expected parents and branch whose tree differs only because an active
+            pre-commit hook added or changed files is the user's own program at work: a success with nothing on screen,
+            the details in the --log file. Any other new commit, or a change without one, is partial and starts with a plain sentence:
+            Git's own cause when Git did not succeed but a commit exists, or when Git never started, the object IDs
+            always in the details. A HEAD that moved while Git never started is not a commit this request created.
+            When Git ran but no commit exists while something changed, the sentence names the changed files and blames
+            the pre-commit hook only when Git ended with a refusal and such a hook is active; the hook's own message
+            stays in the details.
+            """
+            before = operation.before
+            if error is not None:
+                cause = result.cause + ". " if result.cause else ""
+                cause += "Commit result could not be verified; Refresh. " + str(error)
+                self._finish(operation, OperationStatus.UNKNOWN, None, self._diagnostic(request, cause, result.stderr, result.return_code), result.status)
+                return
+            head_parents = (request.expected_head_oid,) if request.expected_head_oid else ()
+            expected_parents = operation.merge_expected_parent_oids if operation.merge_parent_oids else head_parents
+            if request.amend:
+                expected_parents = before.parent_oids
+            new_head_with_expected_parents = after.snapshot.head_oid is not None and (request.amend or after.snapshot.head_oid != request.expected_head_oid) and after.parent_oids == expected_parents
+            expected_tree = after.tree_oid == operation.expected_tree_oid
+            same_branch = before.ref_target == after.ref_target
+            unchanged_local = before.index_entries == after.index_entries and before.working_by_path == after.working_by_path and same_branch
+            # Whatever moved in the repository while Git never started was not this commit's doing.
+            git_ran = result.status != ProcessStatus.START_FAILED
+            commit_created = git_ran and after.snapshot.head_oid is not None and after.snapshot.head_oid != before.snapshot.head_oid
+            requested = new_head_with_expected_parents and expected_tree and same_branch
+            pre_commit_hook_active = before.pre_commit_hook_active or after.pre_commit_hook_active
+            if result.status == ProcessStatus.SUCCESS and requested:
+                log_diagnostic = None
+                notice = ""
+                if not unchanged_local:
+                    log_diagnostic = self._diagnostic(request, SUCCESS_WITH_CHANGES_LOG_CAUSE, result.stderr, result.return_code, describe_commit_boundaries(before, after))
+                    # An active pre-commit or post-commit hook is the user's own program, expected to change files around
+                    # every commit; only a change no such hook explains is worth a notice.
+                    post_commit_hook_active = before.post_commit_hook_active or after.post_commit_hook_active
+                    if not post_commit_hook_active and not pre_commit_hook_active:
+                        notice = commit_change_notice(noticed_paths(before, after), before.index_entries != after.index_entries)
+                self._finish(operation, OperationStatus.SUCCESS, after, None, result.status, commit_created=True, notice=notice, log_diagnostic=log_diagnostic)
+                return
+            if result.status == ProcessStatus.SUCCESS and commit_created and new_head_with_expected_parents and same_branch and pre_commit_hook_active:
+                # The tree differs from what was staged, but the user's own pre-commit hook explains it: nothing to warn about.
+                log_diagnostic = self._diagnostic(request, PRE_COMMIT_HOOK_CONTENT_LOG_CAUSE, result.stderr, result.return_code, describe_commit_boundaries(before, after))
+                self._finish(operation, OperationStatus.SUCCESS, after, None, result.status, commit_created=True, notice="", log_diagnostic=log_diagnostic)
+                return
+            changed = before.snapshot.head_oid != after.snapshot.head_oid or not unchanged_local
+            # Another commit than the one asked for, or none while files changed: partial, a warning to look at.
+            status = OperationStatus.PARTIAL if changed else OperationStatus.REFUSED
+            if commit_created:
+                cause = COMMIT_CHANGED_ELSEWHERE_CAUSE if result.status == ProcessStatus.SUCCESS else result.cause or COMMIT_CHANGED_ELSEWHERE_CAUSE
+            elif changed and git_ran:
+                refused_by_pre_commit_hook = result.status == ProcessStatus.FAILED and pre_commit_hook_active
+                cause = no_commit_change_cause(noticed_paths(before, after), before.index_entries != after.index_entries, refused_by_pre_commit_hook)
+            elif result.cause:
+                cause = result.cause
+            elif changed:
+                cause = no_commit_change_cause(noticed_paths(before, after), before.index_entries != after.index_entries, False)
+            else:
+                cause = NO_COMMIT_FOUND_CAUSE
+            technical_detail = describe_commit_boundaries(before, after) + "\n" + REVIEW_BEFORE_RETRY_TEXT
+            if result.cause and result.cause != cause:
+                technical_detail = GIT_CAUSE_DETAIL_PREFIX + result.cause + "\n" + technical_detail
+            diagnostic = self._diagnostic(request, cause, result.stderr, result.return_code, technical_detail)
+            self._finish(operation, status, after, diagnostic, result.status, commit_created=commit_created)
+
+        # Both branches name the displayed snapshot: the state before the write carries it once it was verified. It only
+        # seeds the list of files hashed after the write, next to every file hashed before it and every file the new
+        # capture lists; a file that appears only in that capture has no earlier bytes and is reported as not verified.
+        baseline = operation.before.snapshot if operation.before is not None else request.snapshot
+        self.worktree_service.run(request.snapshot.context, request.snapshot.git_filename, self._read_state(baseline, operation.before), inspected, operation_id=request.operation_id)
+
+    def read_amend_message(self, snapshot: WorktreeSnapshot) -> Generator:
+        """Decode the full commit object the displayed snapshot names, then check once that HEAD still names it.
+
+        The object is asked for by its ID, which never changes, so HEAD moving before the read cannot change what is
+        read: the single check at the end refuses the message instead.
+        """
+        if snapshot.head_oid is None:
+            raise ValueError("There is no HEAD commit to amend")
+        head_oid = validate_oid(snapshot.head_oid)
+        raw = yield GitCommand(["cat-file", "commit", head_oid])
+        commit = parse_commit(head_oid, raw, head_oid)
+        after = yield GitCommand(["rev-parse", "--verify", "--quiet", "HEAD"], accepted_codes=(0, 1))
+        if after.strip().decode("ascii", "replace") != head_oid:
+            raise ValueError("HEAD changed; Refresh and load Amend again")
+        return head_oid, commit.message
+
+    def _diagnostic(self, request: CommitRequest, cause: str, stderr: bytes = b"", return_code: int | None = None, technical_detail: str = "") -> PreparedDiagnostic:
+        """Remove echoed message text as well as credentials before any output surface sees it.
+
+        The technical details, which only the details and the --log file show, are masked the same way.
+        """
+        message = request.message.decode("utf-8", "replace")
+        cause = mask_commit_message(message, cause)
+        text = mask_commit_message(message, stderr.decode("utf-8", "replace"))
+        technical_detail = mask_commit_message(message, technical_detail)
+        arguments = ["commit", "--file=-"]
+        if request.amend:
+            arguments.append("--amend")
+        action = OperationAction.AMEND if request.amend else OperationAction.COMMIT
+        return Diagnostic(action.commit_label, request.snapshot.context.repository_dir, request.snapshot.git_filename, arguments, cause, text.encode("utf-8"), return_code,
+                          technical_detail=technical_detail).prepare()
+
+    def _finish(self, operation: _CommitOperation, status: OperationStatus, after: CommitState | None, diagnostic: PreparedDiagnostic | None, process_status: ProcessStatus | None = None, *,
+                commit_created: bool = False, notice: str = "", log_diagnostic: PreparedDiagnostic | None = None) -> None:
+        """Release only this completed operation and publish one retained outcome."""
+        request = operation.request
+        if self.active_by_id.pop(request.operation_id, None) is None:
+            return
+        self.mutation.release(request.snapshot.key, request.operation_id)
+        self._publish(CommitOutcome(request.operation_id, request.key, status, operation.before, after, diagnostic, process_status, commit_created, notice, log_diagnostic))
+
+    def _publish(self, outcome: CommitOutcome) -> None:
+        """Retain outcomes independently of any view and notify interested repository windows."""
+        if outcome.operation_id in self.outcome_by_id:
+            return
+        self.outcome_by_id[outcome.operation_id] = outcome
+        self.finished.emit(outcome)