gitpane 1.0.0__py3-none-any.whl

gitpane/ui/reference/reset_dialog.py

@@ -0,0 +1,263 @@
+"""Present the reset choices of the current branch for one captured commit."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QRect, Qt, Signal
+from PySide6.QtWidgets import QButtonGroup, QDialog, QGroupBox, QHBoxLayout, QLabel, QLayout, QMessageBox, QPushButton, QRadioButton, QScrollArea, QVBoxLayout, QWidget
+from shiboken6 import isValid
+
+from gitpane.config import LOCAL_PREFIX, SPACING_SM
+from gitpane.history.repository_value import ReferenceKind
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.reference.reference_edit import ResetIntent, ResetMode
+from gitpane.ui.widget.content_growth import ContentGrowthMixin, OpeningFit
+from gitpane.ui.widget.content_measure import ScrolledContentMeasure
+from gitpane.ui.widget.dialog_layout import fit_form
+from gitpane.ui.widget.long_text import WrappingLabel, WrappingRadioButton
+from gitpane.ui.window_control.dialog_modality import open_window_modal, prepare_message_box
+
+if TYPE_CHECKING:
+    from gitpane.operation.repository_operation import OperationOutcome
+    from gitpane.reference.reference_snapshot import ReferenceSnapshot
+    from gitpane.worktree.worktree_snapshot import WorktreeSnapshot
+
+RESET_DIALOG_WIDTH = 640
+RESET_DIALOG_HEIGHT = 640
+RESET_TITLE = "Reset current branch"
+# The band colour of each reset choice: green for the mode that touches no file, red for the one that discards local changes.
+RESET_MODE_COLOR_BY_MODE: dict[ResetMode, str] = {
+    ResetMode.SOFT: "#80ff80",
+    ResetMode.MIXED: "#ffff80",
+    ResetMode.KEEP: "#ffff80",
+    ResetMode.MERGE: "#ffff80",
+    ResetMode.HARD: "#ff8080",
+}
+
+
+class ResetDialog(ContentGrowthMixin, QDialog):
+    """Keep reset choices bound to one branch, commit and local-state capture."""
+
+    reset_requested = Signal(object)
+    preparation_requested = Signal()
+
+    def __init__(self, session_id: str, target_oid: str, parent: QWidget | None = None) -> None:
+        """Build scrolling metadata and five fixed-color choices above permanent actions."""
+        super().__init__(parent)
+        self.session_id = session_id
+        self.target_oid = target_oid
+        self.snapshot: ReferenceSnapshot | None = None
+        self.worktree_snapshot: WorktreeSnapshot | None = None
+        self.working_signature: tuple = ()
+        self.working_paths: tuple[bytes, ...] | None = None
+        self.reset_target_paths: tuple[bytes, ...] = ()
+        self.intent: ResetIntent | None = None
+        self.mode = ResetMode.SOFT
+        self.closed = False
+        self.busy = False
+        self.completed = False
+        self.metadata_ready = False
+        self.confirmation: QMessageBox | None = None
+        self.confirmation_intent: ResetIntent | None = None
+        self.return_focus = parent.focusWidget() if parent is not None else None
+        self.setWindowTitle(RESET_TITLE)
+        self.resize(RESET_DIALOG_WIDTH, RESET_DIALOG_HEIGHT)
+        layout = QVBoxLayout(self)
+        layout.setSizeConstraint(QLayout.SizeConstraint.SetNoConstraint)
+        self.scroll_area = QScrollArea()
+        self.scroll_area.setWidgetResizable(True)
+        content = QWidget()
+        form = QVBoxLayout(content)
+        form.setSpacing(SPACING_SM)
+        self.branch_label = self._label("Loading current branch…")
+        self.branch_label.setAccessibleName("Current branch")
+        form.addWidget(self.branch_label)
+        metadata_box = QGroupBox("Target revision")
+        metadata_layout = QVBoxLayout(metadata_box)
+        self.target_label = self._label(target_oid)
+        self.subject_label = self._label("Loading commit metadata…")
+        font = self.subject_label.font()
+        font.setBold(True)
+        self.subject_label.setFont(font)
+        self.metadata_label = self._label("Loading…")
+        for label in (self.target_label, self.subject_label, self.metadata_label):
+            metadata_layout.addWidget(label)
+        form.addWidget(metadata_box)
+        self.mode_box = QGroupBox("Reset type")
+        mode_layout = QVBoxLayout(self.mode_box)
+        self.mode_group = QButtonGroup(self)
+        self.button_by_mode: dict[ResetMode, QRadioButton] = {}
+        for mode in ResetMode:
+            button = WrappingRadioButton(mode.label)
+            button.setAccessibleName(mode.label)
+            button.setStyleSheet("QRadioButton { background-color: " + RESET_MODE_COLOR_BY_MODE[mode] + "; color: black; padding: " + str(SPACING_SM) + "px; }")
+            button.description_label.setStyleSheet("color: black; background: transparent;")
+            self.mode_group.addButton(button)
+            self.button_by_mode[mode] = button
+            button.setChecked(mode == ResetMode.SOFT)
+            button.toggled.connect(lambda checked, mode=mode: self._select_mode(mode) if checked else None)
+            mode_layout.addWidget(button)
+        form.addWidget(self.mode_box)
+        self.status_label = self._label("")
+        form.addWidget(self.status_label)
+        form.addStretch()
+        self.scroll_area.setWidget(content)
+        # The commit details read by Git, a refusal with its diagnostic and "Running Git…" arrive in the form after the
+        # window opened, and the window follows them both ways by the rule it shares with the other forms, never below
+        # the height it opened at or the one the user set. The starting height was chosen for Windows' smaller system
+        # text: a larger font grows the window once its first show is laid out, the scroll area staying the last resort
+        # for a screen too small for the form, with OK and Cancel always in view under it.
+        self.install_content_growth(ScrolledContentMeasure(self.scroll_area), OpeningFit.GROW_ONLY, RESET_DIALOG_HEIGHT)
+        layout.addWidget(self.scroll_area, 1)
+        actions = QHBoxLayout()
+        actions.addStretch()
+        self.submit_button = QPushButton("OK")
+        self.submit_button.setAutoDefault(False)
+        self.submit_button.setEnabled(False)
+        self.cancel_button = QPushButton("Cancel")
+        actions.addWidget(self.submit_button)
+        actions.addWidget(self.cancel_button)
+        layout.addLayout(actions)
+        self.submit_button.clicked.connect(self._submit)
+        self.cancel_button.clicked.connect(self.reject)
+        self.finished.connect(self._closed)
+        self.refresh_metrics()
+
+    def _label(self, text: str) -> QLabel:
+        """Keep repository text literal and available in full at narrow widths."""
+        label = WrappingLabel(text)
+        label.setTextFormat(Qt.TextFormat.PlainText)
+        label.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+        label.setWordWrap(True)
+        return label
+
+    def refresh_metrics(self, available: QRect | None = None) -> None:
+        """Fit the form to the screen while keeping its actions reachable."""
+        fit_form(self, available)
+
+    def populate(self, snapshot: ReferenceSnapshot, local: WorktreeSnapshot | None = None, signature: tuple = (), paths: tuple[bytes, ...] = (), target_paths: tuple[bytes, ...] = ()) -> None:
+        """Publish the exact branch and local capture without changing the selected mode."""
+        self.snapshot = snapshot
+        self.worktree_snapshot = local
+        self.working_signature = signature
+        self.working_paths = paths
+        self.reset_target_paths = target_paths
+        branch_name = (snapshot.head_ref or "").removeprefix(LOCAL_PREFIX)
+        self.branch_label.setText("Reset branch '" + branch_name + "' to revision:")
+        self._update_intent()
+
+    def show_metadata(self, fields: tuple[str, ...] | None, cause: str = "") -> None:
+        """Distinguish missing metadata from a failed read of the captured commit."""
+        if fields is None:
+            self.metadata_ready = False
+            self.metadata_label.setText("Commit metadata unavailable")
+            self.subject_label.setText("Commit metadata unavailable")
+            self.show_error(cause)
+            return
+        oid, author, _author_date, _committer, commit_date, message = fields
+        if oid != self.target_oid or self.snapshot is None:
+            return
+        subject, _, _body = message.partition("\n")
+        self.subject_label.setText(subject or "n/a")
+        branches: list[str] = []
+        tags: list[str] = []
+        for reference in sorted(self.snapshot.references, key=lambda reference: reference.full_name):
+            if reference.target_oid != oid:
+                continue
+            if reference.kind == ReferenceKind.TAGS:
+                tags.append(reference.full_name.removeprefix(ReferenceKind.TAGS.prefix))
+            else:
+                branches.append(reference.full_name.removeprefix(LOCAL_PREFIX))
+        self.metadata_label.setText("Author: " + (author or "n/a") + "\nCommit date: " + (commit_date or "n/a")
+                                    + "\nBranch(es): " + (", ".join(branches) or "n/a") + "\nTag(s): " + (", ".join(tags) or "n/a"))
+        self.metadata_ready = True
+        self._update_intent()
+
+    def _select_mode(self, mode: ResetMode) -> None:
+        """Prepare file-changing modes on demand while Soft needs only reference authority."""
+        self.mode = mode
+        self._update_intent()
+        if mode != ResetMode.SOFT and self.worktree_snapshot is None:
+            self.preparation_requested.emit()
+
+    def _update_intent(self) -> None:
+        """Enable submission only after complete authority and metadata reads."""
+        self.intent = None
+        if self.snapshot is not None and (self.mode == ResetMode.SOFT or self.worktree_snapshot is not None) and not self.busy and not self.completed:
+            try:
+                local = None if self.mode == ResetMode.SOFT else self.worktree_snapshot
+                self.intent = ResetIntent.capture(self.snapshot, self.target_oid, local, self.working_signature, session_id=self.session_id, mode=self.mode)
+                self.intent = replace(self.intent, working_paths=self.working_paths, reset_target_paths=self.reset_target_paths)
+            except ValueError as error:
+                self.status_label.setText(str(error))
+        self.submit_button.setEnabled(self.intent is not None and self.metadata_ready)
+
+    def _submit(self) -> None:
+        """Emit the displayed reset once; the operation owner retains its native lifetime."""
+        if self.intent is None or self.busy or not self.metadata_ready or self.confirmation is not None:
+            return
+        if self.mode == ResetMode.HARD:
+            question = QMessageBox(QMessageBox.Icon.Warning, RESET_TITLE, "You are about to discard ALL local changes, are you sure?",
+                                   QMessageBox.StandardButton.Yes | QMessageBox.StandardButton.No, self)
+            prepare_message_box(question, RESET_TITLE)
+            question.setTextFormat(Qt.TextFormat.PlainText)
+            question.setDefaultButton(QMessageBox.StandardButton.No)
+            question.setEscapeButton(QMessageBox.StandardButton.No)
+            self.confirmation = question
+            self.confirmation_intent = self.intent
+            question.finished.connect(self._answer_hard)
+            open_window_modal(question)
+            return
+        self._launch()
+
+    def _answer_hard(self, result: int) -> None:
+        """Only explicit Yes authorizes the captured Hard intent, without rereading over it."""
+        question = self.confirmation
+        captured = self.confirmation_intent
+        self.confirmation = None
+        self.confirmation_intent = None
+        if question is not None:
+            question.deleteLater()
+        if self.closed or result != QMessageBox.StandardButton.Yes or captured is None or self.intent != captured:
+            return
+        self.intent = replace(captured, hard_confirmed=True)
+        self._launch()
+
+    def _launch(self) -> None:
+        """Freeze controls after any required confirmation and submit to the common owner."""
+        self.busy = True
+        self.submit_button.setEnabled(False)
+        self.mode_box.setEnabled(False)
+        self.status_label.setText("Running Git…")
+        self.reset_requested.emit(self.intent)
+
+    def show_error(self, cause: str) -> None:
+        """Keep a read error visible without turning it into absent metadata."""
+        self.status_label.setText(cause)
+        self.submit_button.setEnabled(False)
+
+    def show_outcome(self, outcome: OperationOutcome) -> None:
+        """Retain native refusal details and the chosen mode without destructive fallback."""
+        self.busy = False
+        self.completed = outcome.status in (OperationStatus.SUCCESS, OperationStatus.PARTIAL, OperationStatus.UNKNOWN)
+        lines: list[str] = []
+        for step in outcome.steps:
+            lines.append(step.operation + ": " + step.status.value + " — " + step.effect)
+        if outcome.diagnostic is not None:
+            lines.append(outcome.diagnostic.detail)
+        self.status_label.setText("\n".join(lines))
+        self.mode_box.setEnabled(not self.completed)
+        self.cancel_button.setText("Close")
+        self._update_intent()
+        if outcome.status == OperationStatus.SUCCESS:
+            self.accept()
+
+    def _closed(self) -> None:
+        """Invalidate late reads and return keyboard focus to the launching window."""
+        self.closed = True
+        if self.confirmation is not None:
+            self.confirmation.reject()
+        if self.return_focus is not None and isValid(self.return_focus):
+            self.return_focus.setFocus()

gitpane/ui/reference/revision_dialog.py

@@ -0,0 +1,121 @@
+"""Reproduce the Git Extensions "Choose another revision" window, which Cherry-pick shares with the reference forms."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QEvent, QObject, Qt, Signal
+from PySide6.QtWidgets import QDialog, QHBoxLayout, QLabel, QLineEdit, QListWidget, QListWidgetItem, QPushButton, QVBoxLayout, QWidget
+
+from gitpane.config import REPLAY_DIALOG_HEIGHT, REPLAY_DIALOG_WIDTH
+from gitpane.text.typed_text import typed_value
+from gitpane.ui.widget.dialog_layout import fit_form
+from gitpane.ui.widget.long_text import WrappingLabel
+from gitpane.ui.window_control.item_activation import activate_current_row
+
+if TYPE_CHECKING:
+    from gitpane.history.repository_value import Commit
+
+
+class RevisionChoiceDialog(QDialog):
+    """Search the commits already loaded, or take any typed revision, to choose another commit for a form.
+
+    The window never starts Git: a click in the list writes the commit's full ID, and Apply hands the text to its
+    owner, which resolves it and answers with ``accept`` or ``show_error``.
+    """
+
+    revision_requested = Signal(str)
+
+    def __init__(self, commits: list[Commit], parent: QWidget) -> None:
+        """Keep revision validation asynchronous and cancellation independent of its result."""
+        super().__init__(parent)
+        self.setWindowTitle("Choose another revision")
+        self.setModal(True)
+        self.resize(REPLAY_DIALOG_WIDTH, REPLAY_DIALOG_HEIGHT)
+        self.generation = 0
+        self.closed = False
+        self.commits = tuple(commits)
+        layout = QVBoxLayout(self)
+        label = QLabel("Revision or commit hash:")
+        self.revision_edit = QLineEdit()
+        label.setBuddy(self.revision_edit)
+        layout.addWidget(label)
+        layout.addWidget(self.revision_edit)
+        self.commit_list = QListWidget()
+        self.commit_list.setAccessibleName("Available commits")
+        layout.addWidget(self.commit_list)
+        self.status_label = WrappingLabel("")
+        layout.addWidget(self.status_label)
+        actions = QHBoxLayout()
+        actions.addStretch()
+        self.apply_button = QPushButton("Apply")
+        self.apply_button.setDefault(True)
+        self.apply_button.setEnabled(False)
+        self.cancel_button = QPushButton("Cancel")
+        actions.addWidget(self.apply_button)
+        actions.addWidget(self.cancel_button)
+        layout.addLayout(actions)
+        self.revision_edit.textChanged.connect(self._revision_changed)
+        self.commit_list.itemClicked.connect(self._choose_commit)
+        self.commit_list.itemActivated.connect(self._choose_commit)
+        self.commit_list.installEventFilter(self)
+        self.apply_button.clicked.connect(self._apply)
+        self.cancel_button.clicked.connect(self.reject)
+        self.finished.connect(self._closed)
+        self._revision_changed("")
+        fit_form(self)
+        self.revision_edit.setFocus()
+
+    def eventFilter(self, watched: QObject, event: QEvent) -> bool:
+        """Choose the current commit on Enter in the list, then let the key reach the default Apply, on every system.
+
+        Qt for macOS does not activate a list row on Enter, so Apply would read the revision the field held before.
+        """
+        if watched is self.commit_list and activate_current_row(self.commit_list, event):
+            return True
+        return super().eventFilter(watched, event)
+
+    def _revision_changed(self, text: str) -> None:
+        """Invalidate older reads immediately and filter local captions without contacting Git.
+
+        The field holds a revision, not a free search, so the list is filtered on the revision without the blanks
+        around it, the same text Apply asks for.
+        """
+        self.generation += 1
+        self.status_label.setText("")
+        revision = typed_value(text)
+        self.apply_button.setEnabled(bool(revision))
+        self.commit_list.clear()
+        search = revision.casefold()
+        for commit in self.commits:
+            subject, _separator, _body = commit.message.partition("\n")
+            caption = commit.oid + "  " + subject
+            if search in caption.casefold():
+                item = QListWidgetItem(caption)
+                item.setData(Qt.ItemDataRole.UserRole, commit.oid)
+                item.setToolTip(caption)
+                self.commit_list.addItem(item)
+
+    def _choose_commit(self, item: QListWidgetItem) -> None:
+        """Use the full identity of a selected search result, never its caption."""
+        self.revision_edit.setText(item.data(Qt.ItemDataRole.UserRole))
+
+    def _apply(self) -> None:
+        """Request one read while allowing edits or cancellation to invalidate it."""
+        revision = typed_value(self.revision_edit.text())
+        if self.closed or not revision or not self.apply_button.isEnabled():
+            return
+        self.generation += 1
+        self.apply_button.setEnabled(False)
+        self.status_label.setText("Reading revision…")
+        self.revision_requested.emit(revision)
+
+    def show_error(self, cause: str = "Cannot read this local commit. Check the revision or hash and try again.") -> None:
+        """Keep the previous source and allow correction without exposing raw Git output."""
+        self.status_label.setText(cause)
+        self.apply_button.setEnabled(bool(typed_value(self.revision_edit.text())))
+
+    def _closed(self) -> None:
+        """Invalidate outstanding validation when the selector finishes."""
+        self.closed = True
+        self.generation += 1

gitpane/ui/reference/revision_picker.py

@@ -0,0 +1,227 @@
+"""Show a target commit the way the Git Extensions revision field does: [short hash][choose button] -N."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QEvent, QObject, QSize, Qt, QTimer, Signal
+from PySide6.QtWidgets import QHBoxLayout, QLabel, QLineEdit, QPushButton, QVBoxLayout, QWidget
+
+from gitpane.config import ICON_SIDE, REVISION_INPUT_PAUSE_MS
+from gitpane.text.typed_text import typed_value
+from gitpane.ui.look.action_icon import action_icon
+from gitpane.ui.look.windows_control_look import apply_secondary_text_color, apply_windows_button_look, apply_windows_line_edit_look
+from gitpane.ui.reference.commit_summary import GIT_EXTENSIONS_REVISION_PREFIX_LENGTH
+
+if TYPE_CHECKING:
+    from gitpane.ui.reference.revision_dialog import RevisionChoiceDialog
+
+# The small "choose another revision" button of the Git Extensions forms (visible size, border included) and its name.
+REVISION_BUTTON_SIZE = QSize(23, 22)
+REVISION_CHOICE_NAME = "Choose another revision"
+# Spacing measured on the Checkout revision capture: the button sits 4 px after the field and 1 px higher than it,
+# and the commit counter starts 10 px after the button.
+FIELD_TO_BUTTON_SPACE = 4
+BUTTON_RAISE = 1
+BUTTON_TO_COUNT_SPACE = 10
+
+
+class RevisionPicker(QWidget):
+    """Row that shows one commit as its short hash, a button to choose another one, and its position from HEAD.
+
+    The widget only displays and reports; it never starts Git. The reference form controller resolves what the user types or
+    chooses and answers with ``show_revision`` and ``show_count``.
+
+    Typing does not resolve anything on each key: the text is reported once the user pauses, and again when the
+    field is left with a text that has no proven commit yet. ``revision_edited`` carries the text and whether the
+    field was left. While a typed text is unresolved the widget has no target, so the form cannot act on a commit
+    the field no longer shows. ``resolution_generation`` changes with each key and each shown target, so an answer
+    for an older text can be recognized and dropped. Leaving the field while the text reported at the pause is still
+    being resolved reports nothing more: ``settle_generation`` asks the coming answer to settle the field instead.
+    """
+
+    revision_edited = Signal(str, bool)
+    choose_requested = Signal()
+    target_changed = Signal(object)
+
+    def __init__(self, field_width: int, parent: QWidget | None = None) -> None:
+        """Build the field, the choose button and the counter at the sizes and colors of the reproduced window."""
+        super().__init__(parent)
+        self.target_oid: str | None = None
+        # The "Choose another revision" window the choose button opened, while it is open.
+        self.revision_dialog: RevisionChoiceDialog | None = None
+        # The last commit this field proved, shown again when the user leaves the field with a text that is none.
+        self.last_target_oid: str | None = None
+        self.resolution_generation = 0
+        # The last text the reference form controller answered and its commit, None when that text is not a revision.
+        self.answered_text: str | None = None
+        self.answered_oid: str | None = None
+        # The last text reported at a typing pause, and the resolution generation it was reported under.
+        self.reported_text: str | None = None
+        self.reported_generation: int | None = None
+        # The resolution generation whose answer, still awaited when the field was left, must settle the field.
+        self.settle_generation: int | None = None
+        self.pause_timer = QTimer(self)
+        self.pause_timer.setSingleShot(True)
+        self.pause_timer.setInterval(REVISION_INPUT_PAUSE_MS)
+        self.pause_timer.timeout.connect(self._typing_paused)
+        self.revision_edit = QLineEdit()
+        self.revision_edit.setFixedWidth(field_width)
+        self.revision_edit.setAccessibleName("Revision")
+        self.choose_button = QPushButton()
+        self.choose_button.setIcon(action_icon("choose_revision", self.devicePixelRatioF()))
+        self.choose_button.setIconSize(QSize(ICON_SIDE, ICON_SIDE))
+        self.choose_button.setFixedSize(REVISION_BUTTON_SIZE)
+        self.choose_button.setAccessibleName(REVISION_CHOICE_NAME)
+        self.choose_button.setToolTip(REVISION_CHOICE_NAME)
+        # Only the form's submit button may be the default one; see the Enter handling of the reference forms.
+        self.choose_button.setAutoDefault(False)
+        self.choose_button.clicked.connect(self.choose_requested)
+        self.count_label = QLabel()
+        self.count_label.setAccessibleName("Commits relative to HEAD")
+        self.apply_theme_look()
+        # The field and the counter start one pixel lower than the button, which is how the capture places them.
+        field_column = QVBoxLayout()
+        field_column.setContentsMargins(0, BUTTON_RAISE, 0, 0)
+        field_column.setSpacing(0)
+        field_column.addWidget(self.revision_edit)
+        count_column = QVBoxLayout()
+        count_column.setContentsMargins(0, BUTTON_RAISE, 0, 0)
+        count_column.setSpacing(0)
+        count_column.addWidget(self.count_label)
+        row = QHBoxLayout(self)
+        row.setContentsMargins(0, 0, 0, 0)
+        row.setSpacing(0)
+        row.addLayout(field_column)
+        row.addSpacing(FIELD_TO_BUTTON_SPACE)
+        row.addWidget(self.choose_button, 0, Qt.AlignmentFlag.AlignTop)
+        row.addSpacing(BUTTON_TO_COUNT_SPACE)
+        row.addLayout(count_column)
+        row.addStretch(1)
+        # textEdited only reports the user's own changes: showing a resolved commit never starts another resolution.
+        self.revision_edit.textEdited.connect(self._text_edited)
+        self.revision_edit.editingFinished.connect(self._editing_finished)
+        self.revision_edit.installEventFilter(self)
+
+    def apply_theme_look(self) -> None:
+        """Lay the light or dark look of the field, the choose button and the counter, after the application palette.
+
+        The picker does not follow the theme on its own: it is not in its window yet when it is built, so the form that
+        holds it calls this from its own theme look. Only style sheets and palettes change; the text and target stay.
+        """
+        apply_windows_line_edit_look(self.revision_edit)
+        apply_windows_button_look(self.choose_button)
+        apply_secondary_text_color(self.count_label)
+
+    def show_revision(self, oid: str, *, rewrite_text: bool = True) -> None:
+        """Target a full commit ID and remember it as the last proven one; its position is cleared until counted.
+
+        With ``rewrite_text`` the field shows the commit's first eight digits, all selected so typing replaces them;
+        without it the text the user is typing stays as it is, since the commit only answers a typing pause.
+        """
+        self.pause_timer.stop()
+        self.resolution_generation += 1
+        self.target_oid = oid
+        self.last_target_oid = oid
+        if rewrite_text:
+            self.revision_edit.setText(oid[:GIT_EXTENSIONS_REVISION_PREFIX_LENGTH])
+            self.revision_edit.selectAll()
+        self.answered_text = typed_value(self.revision_edit.text())
+        self.answered_oid = oid
+        self.show_count("")
+        self.target_changed.emit(oid)
+
+    def show_invalid(self) -> None:
+        """Show that the typed text names no commit: no target, no position, and the refusal kept for that text."""
+        self.target_oid = None
+        self.answered_text = typed_value(self.revision_edit.text())
+        self.answered_oid = None
+        self.show_count("")
+        self.target_changed.emit(None)
+
+    def restore_last_target(self) -> None:
+        """Show the last proven commit again, as its short hash, after the field was left with a text naming none."""
+        if self.last_target_oid is None:
+            return
+        self.show_revision(self.last_target_oid)
+
+    def show_count(self, text: str) -> None:
+        """Show the commit's position from HEAD, for example "-13", "+2", "=" or nothing when it is unknown."""
+        self.count_label.setText(text)
+
+    def eventFilter(self, watched: QObject, event: QEvent) -> bool:
+        """Let Enter settle a text that has no commit yet without also running the form's action.
+
+        The field would pass Enter on to the form, whose default button would then act on whatever commit the field
+        had just been settled on, or restored to, while the user was still correcting it. Enter on a proven commit
+        still reaches the form.
+        """
+        if (watched is self.revision_edit and event.type() == QEvent.Type.KeyPress and event.key() in (Qt.Key.Key_Return, Qt.Key.Key_Enter)
+                and self.target_oid is None):
+            self._editing_finished()
+            return True
+        return super().eventFilter(watched, event)
+
+    def _text_edited(self, _text: str) -> None:
+        """Forget the target the field no longer shows and wait for a pause in typing before reporting the text."""
+        self.resolution_generation += 1
+        self.pause_timer.start()
+        if self.target_oid is None:
+            return
+        self.target_oid = None
+        self.show_count("")
+        self.target_changed.emit(None)
+
+    def _typing_paused(self) -> None:
+        """Report the typed text once the user has stopped typing, unless it is the text answered last.
+
+        Typing a character and erasing it gives back a text whose answer is already known: that answer is shown again
+        without asking the reference form controller, so no Git process is started for a text resolved a moment ago.
+        """
+        text = typed_value(self.revision_edit.text())
+        if text != self.answered_text:
+            self.reported_text = text
+            self.reported_generation = self.resolution_generation
+            self.revision_edited.emit(text, False)
+            return
+        if self.answered_oid is not None:
+            self.show_revision(self.answered_oid, rewrite_text=False)
+
+    def _editing_finished(self) -> None:
+        """Settle the field when the user leaves it or presses Enter.
+
+        A commit already proven for the typed text is shown as its short hash, like Git Extensions does. A text still
+        without a commit is reported as final, so the reference form controller either takes it or restores the last commit. That
+        report is remembered like a pause's report, so leaving the field right after Enter waits for its answer instead
+        of resolving the same text a second time.
+        """
+        self.pause_timer.stop()
+        text = typed_value(self.revision_edit.text())
+        if self.target_oid is None and text == self.answered_text and self.answered_oid is not None:
+            self.show_revision(self.answered_oid)
+            return
+        if self.target_oid is not None:
+            # Only the text changes: the target, and the position already shown or still being counted, stay.
+            short_text = self.target_oid[:GIT_EXTENSIONS_REVISION_PREFIX_LENGTH]
+            if text != short_text:
+                self.revision_edit.setText(short_text)
+                self.answered_text = short_text
+            return
+        if self.is_awaiting_answer(text):
+            # The text reported at the pause is still being resolved: its answer settles the field when it arrives, so
+            # the same text is never resolved a second time.
+            self.settle_generation = self.resolution_generation
+            return
+        self.resolution_generation += 1
+        self.reported_text = text
+        self.reported_generation = self.resolution_generation
+        self.settle_generation = self.resolution_generation
+        self.revision_edited.emit(text, True)
+
+    def is_awaiting_answer(self, text: str) -> bool:
+        """Tell whether this text was reported at the last typing pause and its answer has not arrived yet.
+
+        Any key typed since, and any target shown since, changes the resolution generation, so an older report never
+        counts as awaited.
+        """
+        return text == self.reported_text and self.reported_generation == self.resolution_generation and text != self.answered_text