gitpane 1.0.0__py3-none-any.whl

gitpane/ui/reference/checkout_dialog.py

@@ -0,0 +1,419 @@
+"""Present captured branches without writing until the explicit Checkout action."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QRect, Qt, Signal
+from PySide6.QtWidgets import QButtonGroup, QDialog, QFrame, QHBoxLayout, QLayout, QLineEdit, QPushButton, QRadioButton, QScrollArea, QVBoxLayout, QWidget
+from shiboken6 import isValid
+
+from gitpane.config import LOCAL_PREFIX, REMOTE_PREFIX, SPACING_SM
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.reference.reference_edit import CheckoutIntent, CheckoutMode, remote_branch_name
+from gitpane.text.typed_text import typed_value
+from gitpane.ui.reference.branch_selector import BranchSelector
+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 SelectionSummaryRow, WrappingLabel
+from gitpane.ui.widget.refresh_advice import refresh_advice_text
+from gitpane.ui.widget.result_label import ResultLabel
+
+if TYPE_CHECKING:
+    from PySide6.QtGui import QCloseEvent
+
+    from gitpane.operation.repository_operation import OperationOutcome
+    from gitpane.reference.reference_snapshot import ReferenceSnapshot
+
+CHECKOUT_WIDTH = 800
+# The height asked before the first show; once shown, the window takes the exact height of its content instead.
+CHECKOUT_HEIGHT = 280
+# The first remote choice: create the local branch, or, when a local branch of that name already exists, move it onto
+# the remote branch the way Git Extensions words it.
+CREATE_SAME_NAME_TEXT = "Create local branch with same name:"
+RESET_LOCAL_BRANCH_TEXT = "Reset local branch with the name:"
+# The orange text under the choices telling how many local commits a reset would lose; the click on Checkout confirms.
+LOST_COMMITS_WARNING_TEMPLATE = "{branch} has {count} commits that are not in {remote}. They will be lost."
+LOST_COMMIT_WARNING_TEMPLATE = "{branch} has 1 commit that is not in {remote}. It will be lost."
+LOST_COMMIT_FAILURE_TEMPLATE = "Commits a reset would lose: unavailable ({cause})"
+
+
+class CheckoutDialog(ContentGrowthMixin, QDialog):
+    """Collect an explicit branch checkout while the reference form controller owns asynchronous Git work.
+
+    Checking out a single commit has its own Checkout revision window; this one only lists branches.
+    """
+
+    selection_changed = Signal(str)
+    # Local commit ID, remote commit ID: asks how many commits the local branch has that the remote one lacks.
+    lost_commit_count_requested = Signal(str, str)
+    checkout_requested = Signal(object)
+
+    def __init__(self, session_id: str, parent: QWidget | None = None) -> None:
+        """Keep actions outside the scrolling content and preserve focus on closure."""
+        super().__init__(parent)
+        self.session_id = session_id
+        self.snapshot: ReferenceSnapshot | None = None
+        self.intent: CheckoutIntent | None = None
+        self.closed = False
+        self.busy = False
+        self.read_generation = 0
+        self.comparison_ready = False
+        # True while the selected remote branch has a local branch of the same name, which the first choice resets.
+        self.resets_local_branch = False
+        # How many commits the reset would lose, None while unknown for the current selection.
+        self.lost_commit_count: int | None = None
+        # Why that count could not be read, shown in orange under the choices and in the comparison tooltip; empty when nothing failed.
+        self.lost_commit_cause = ""
+        self.difference_tooltip = ""
+        self.return_focus = parent.focusWidget() if parent is not None else None
+        self.setWindowTitle("Checkout branch")
+        self.resize(CHECKOUT_WIDTH, CHECKOUT_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)
+        kinds = QHBoxLayout()
+        self.local_radio = QRadioButton("Local branch")
+        self.remote_radio = QRadioButton("Remote branch")
+        self.kind_group = QButtonGroup(self)
+        self.kind_group.addButton(self.local_radio)
+        self.kind_group.addButton(self.remote_radio)
+        self.local_radio.setChecked(True)
+        kinds.addWidget(self.local_radio)
+        kinds.addWidget(self.remote_radio)
+        kinds.addStretch()
+        form.addLayout(kinds)
+        self.branch_selector = BranchSelector()
+        label = WrappingLabel("Select branch")
+        label.setBuddy(self.branch_selector)
+        self.difference_label = WrappingLabel("Commit difference unavailable")
+        self.selection_row = SelectionSummaryRow(label, self.branch_selector, self.difference_label)
+        form.addWidget(self.selection_row)
+        self.target_label = WrappingLabel("Loading references…")
+        self.target_label.setTextFormat(Qt.TextFormat.PlainText)
+        self.target_label.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+        self.target_label.setWordWrap(True)
+        form.addWidget(self.target_label)
+        self.separator = QFrame()
+        self.separator.setFrameShape(QFrame.Shape.HLine)
+        self.separator.setFrameShadow(QFrame.Shadow.Sunken)
+        form.addWidget(self.separator)
+        self.remote_options = QWidget()
+        options = QVBoxLayout(self.remote_options)
+        options.setContentsMargins(0, 0, 0, 0)
+        self.same_radio = QRadioButton(CREATE_SAME_NAME_TEXT)
+        self.same_name_label = WrappingLabel()
+        self.same_name_label.setTextFormat(Qt.TextFormat.PlainText)
+        self.same_name_label.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+        self.same_name_label.setWordWrap(True)
+        same_row = QHBoxLayout()
+        same_row.addWidget(self.same_radio)
+        same_row.addWidget(self.same_name_label, 1)
+        options.addLayout(same_row)
+        self.custom_radio = QRadioButton("Create local branch with custom name:")
+        self.custom_edit = QLineEdit()
+        self.custom_edit.setAccessibleName("Custom local branch name")
+        self.custom_edit.setEnabled(False)
+        custom_row = QHBoxLayout()
+        custom_row.addWidget(self.custom_radio)
+        custom_row.addWidget(self.custom_edit, 1)
+        options.addLayout(custom_row)
+        self.detached_radio = QRadioButton("Checkout the commit (in detached head)")
+        options.addWidget(self.detached_radio)
+        self.lost_commit_label = ResultLabel()
+        self.lost_commit_label.hide()
+        options.addWidget(self.lost_commit_label)
+        self.mode_group = QButtonGroup(self)
+        for radio in (self.same_radio, self.custom_radio, self.detached_radio):
+            self.mode_group.addButton(radio)
+        self.same_radio.setChecked(True)
+        self.remote_options.hide()
+        form.addWidget(self.remote_options)
+        self.status_label = WrappingLabel()
+        self.status_label.setTextFormat(Qt.TextFormat.PlainText)
+        self.status_label.setWordWrap(True)
+        self.status_label.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+        form.addWidget(self.status_label)
+        form.addStretch()
+        self.scroll_area.setWidget(content)
+        # The content changes after the window opened (references read, commit difference, remote choices, orange lost
+        # commit text, error) and the window follows it both ways by the rule it shares with Clone, never below the height
+        # it opened at or the one the user set; once shown, it takes the exact height of the content it opens with,
+        # without empty room under the choices.
+        self.install_content_growth(ScrolledContentMeasure(self.scroll_area), OpeningFit.EXACT, CHECKOUT_HEIGHT)
+        layout.addWidget(self.scroll_area, 1)
+        actions = QHBoxLayout()
+        actions.addStretch()
+        self.checkout_button = QPushButton("Checkout")
+        self.checkout_button.setEnabled(False)
+        self.checkout_button.setAutoDefault(False)
+        self.cancel_button = QPushButton("Cancel")
+        actions.addWidget(self.checkout_button)
+        actions.addWidget(self.cancel_button)
+        layout.addLayout(actions)
+        self.cancel_button.clicked.connect(self.reject)
+        self.checkout_button.clicked.connect(self._submit)
+        self.branch_selector.currentIndexChanged.connect(self._selection_changed)
+        self.local_radio.clicked.connect(lambda: self._select_kind(LOCAL_PREFIX))
+        self.remote_radio.clicked.connect(lambda: self._select_kind(REMOTE_PREFIX))
+        self.mode_group.buttonClicked.connect(self._mode_changed)
+        self.custom_edit.textChanged.connect(self._mode_changed)
+        self.finished.connect(self._closed)
+        self.refresh_metrics()
+
+    def refresh_metrics(self, available: QRect | None = None) -> None:
+        """Apply the shared form metrics and keep the window inside the usable screen area.
+
+        Called when the window is built, shown, and moved to another screen or given another font. The height follows
+        the content through the growth rule shared with Clone, not here.
+        """
+        fit_form(self, available)
+
+    def populate(self, snapshot: ReferenceSnapshot, full_ref: str) -> None:
+        """Publish only the captured selection and begin its independent comparison."""
+        self.snapshot = snapshot
+        self.branch_selector.populate(snapshot, full_ref)
+        self._selection_changed()
+
+    def _select_kind(self, prefix: str) -> None:
+        """Choose an actual reference of the requested kind, or an explicit empty selection."""
+        for index in range(self.branch_selector.count()):
+            full_ref = self.branch_selector.itemData(index)
+            if full_ref and full_ref.startswith(prefix):
+                self.branch_selector.setCurrentIndex(index)
+                return
+        self.branch_selector.setCurrentIndex(-1)
+
+    def _mode_changed(self) -> None:
+        """Update the draft mode without replacing the selected reference or OID comparison."""
+        self.custom_edit.setEnabled(self.custom_radio.isChecked() and not self.busy)
+        self._show_lost_commit_warning()
+        self._make_intent()
+        self._update_checkout_button()
+
+    def _reset_count_pending(self) -> bool:
+        """Tell that the reset of the local branch is chosen while neither the number of commits it loses nor why that number failed has arrived."""
+        return self.resets_local_branch and self.same_radio.isChecked() and self.lost_commit_count is None and not self.lost_commit_cause
+
+    def _update_checkout_button(self) -> None:
+        """Allow Checkout only for a complete choice whose commits were compared, and for a reset only once its lost commits are shown.
+
+        A reset moves the local branch and drops its own commits, so the click must come after the user could read
+        how many there are, or why that number is unknown.
+        """
+        self.checkout_button.setEnabled(self.intent is not None and self.comparison_ready and not self.busy and not self._reset_count_pending())
+
+    def _make_intent(self) -> None:
+        """Build an immutable intention from exact item data and the explicit remote mode.
+
+        The local name is taken without the blanks around it; the field keeps what was typed.
+        """
+        self.intent = None
+        full_ref = self.branch_selector.currentData()
+        if self.snapshot is None or not full_ref:
+            return
+        mode = CheckoutMode.LOCAL
+        if full_ref.startswith(REMOTE_PREFIX):
+            mode = CheckoutMode.CUSTOM if self.custom_radio.isChecked() else CheckoutMode.DETACHED if self.detached_radio.isChecked() else CheckoutMode.RESET_LOCAL if self.resets_local_branch else CheckoutMode.SAME
+        local_name = typed_value(self.custom_edit.text())
+        try:
+            self.intent = CheckoutIntent.capture(self.snapshot, full_ref, refresh_advice=refresh_advice_text, session_id=self.session_id, mode=mode, local_name=local_name)
+            if mode == CheckoutMode.CUSTOM and not local_name:
+                self.intent = None
+        except ValueError as error:
+            self.show_error(str(error))
+
+    def _selection_changed(self) -> None:
+        """Invalidate old comparison output whenever a different reference is selected."""
+        self.intent = None
+        self.comparison_ready = False
+        self.read_generation += 1
+        self.checkout_button.setEnabled(False)
+        self.difference_label.setText("Commit difference unavailable")
+        self._set_difference_tooltip("")
+        self.lost_commit_count = None
+        self.lost_commit_cause = ""
+        self._show_lost_commit_warning()
+        full_ref = self.branch_selector.currentData()
+        if self.snapshot is None or not full_ref:
+            self.remote_options.hide()
+            self.target_label.setText("Select a branch to check out")
+            return
+        remote = full_ref.startswith(REMOTE_PREFIX)
+        self.remote_options.setVisible(remote)
+        self.remote_radio.setChecked(remote)
+        self.local_radio.setChecked(not remote)
+        self.target_label.setText(full_ref)
+        self.resets_local_branch = False
+        if remote:
+            self._show_local_branch_choice(full_ref)
+        self._make_intent()
+        self.difference_label.setText("Comparing commits…")
+        if self.intent is not None:
+            self.selection_changed.emit(self.intent.target_oid)
+        if self.resets_local_branch and self.intent is not None:
+            local_oid = self.snapshot.object_oid_by_name[LOCAL_PREFIX + remote_branch_name(self.snapshot, full_ref)]
+            self.lost_commit_count_requested.emit(local_oid, self.intent.target_oid)
+
+    def show_lost_commits(self, count: int) -> None:
+        """Keep how many commits the reset would lose, show the warning when there are some, and allow Checkout once known."""
+        self.lost_commit_count = count
+        self._show_lost_commit_warning()
+        self._update_checkout_button()
+
+    def show_lost_commit_failure(self, cause: str) -> None:
+        """Show under the choices, in orange, why Git could not count the commits the reset would lose, then allow Checkout.
+
+        The cause also stays in the comparison tooltip. The user has read that the number is unknown, so the click on
+        Checkout is an informed one.
+        """
+        self.lost_commit_cause = cause
+        self._set_difference_tooltip(self.difference_tooltip)
+        self._show_lost_commit_warning()
+        self._update_checkout_button()
+
+    def _show_lost_commit_warning(self) -> None:
+        """Show or hide the orange lost commit text; the window grows to show it whole, never needing to scroll for it."""
+        text = self._lost_commit_warning_text()
+        if text:
+            self.lost_commit_label.show_warning(text)
+            self.lost_commit_label.show()
+        else:
+            self.lost_commit_label.clear()
+            self.lost_commit_label.hide()
+
+    def _lost_commit_warning_text(self) -> str:
+        """Return the orange text while the reset choice is checked: the cause of a failed count, or a known non-zero count; empty otherwise."""
+        if not self.resets_local_branch or not self.same_radio.isChecked():
+            return ""
+        if self.lost_commit_cause:
+            return LOST_COMMIT_FAILURE_TEMPLATE.format(cause=self.lost_commit_cause)
+        count = self.lost_commit_count
+        if not count:
+            return ""
+        full_ref = self.branch_selector.currentData() or ""
+        remote = full_ref.removeprefix(REMOTE_PREFIX)
+        template = LOST_COMMIT_WARNING_TEMPLATE if count == 1 else LOST_COMMITS_WARNING_TEMPLATE
+        return template.format(branch=self.same_name_label.text(), count=count, remote=remote)
+
+    def _set_difference_tooltip(self, text: str) -> None:
+        """Set the comparison tooltip, followed by why the lost commit count is unknown when it failed."""
+        self.difference_tooltip = text
+        lines = [text] if text else []
+        if self.lost_commit_cause:
+            lines.append(LOST_COMMIT_FAILURE_TEMPLATE.format(cause=self.lost_commit_cause))
+        self.difference_label.setToolTip("\n".join(lines))
+
+    def _show_local_branch_choice(self, full_ref: str) -> None:
+        """Word the first remote choice after the local branch of the same name, and choose the reset when that branch exists.
+
+        Git Extensions does the same: checking out ``origin/X`` while ``X`` exists moves ``X`` onto it rather than
+        failing on a name already taken. A branch without a local one keeps whatever choice the user made.
+        """
+        self.same_radio.setText(CREATE_SAME_NAME_TEXT)
+        try:
+            name = remote_branch_name(self.snapshot, full_ref)
+        except ValueError as error:
+            self.same_name_label.setText(str(error))
+            return
+        self.same_name_label.setText(name)
+        if LOCAL_PREFIX + name not in self.snapshot.object_oid_by_name:
+            return
+        self.resets_local_branch = True
+        self.same_radio.setText(RESET_LOCAL_BRANCH_TEXT)
+        self.same_radio.setChecked(True)
+        self.custom_edit.setEnabled(False)
+
+    def show_difference(self, difference: tuple[int, int] | None, cause: str = "") -> None:
+        """Distinguish an unknown comparison from two real zero counts.
+
+        The explanation of a first checkout arrives once the window is open and wraps over several lines at a large text
+        size; the window grows to show it, like it does for the other content arriving late.
+        """
+        if difference is None:
+            self.comparison_ready = False
+            self.difference_label.setText("Commit difference unavailable")
+            self._set_difference_tooltip(cause)
+            self.checkout_button.setEnabled(False)
+            return
+        left, right = difference
+        self.comparison_ready = True
+        self.difference_label.setText(f"−{left} / +{right}")
+        direction = "Commits only in current HEAD / commits only in selected target"
+        if self.snapshot is not None and self.snapshot.head_oid is None:
+            self.difference_label.setText(f"Initial checkout: +{right} commits (HEAD has no commit)")
+            direction = "Commits in the selected target, starting from empty history"
+        self._set_difference_tooltip(direction)
+        self.difference_label.setAccessibleName(direction)
+        self._update_checkout_button()
+
+    def show_error(self, cause: str) -> None:
+        """Expose the real error; the window grows to show it, up to its share of the screen, so ordinary refusals need no scrolling."""
+        self.status_label.setText(cause)
+        self.checkout_button.setEnabled(False)
+
+    def show_outcome(self, outcome: OperationOutcome) -> None:
+        """Close after a successful checkout, give the form back after a refusal it can retry, freeze it after any other result.
+
+        A refused checkout stopped before Git ran, so nothing was written and the form becomes usable again, like
+        Checkout revision, unless its capture no longer matches the repository: a second click would only be refused
+        again, and the console says to reopen the form or refresh. A failed, partial or unknown checkout may have
+        changed files: the request stays visible, greyed, while the console explains what happened.
+        """
+        self.busy = False
+        self.cancel_button.setEnabled(True)
+        self.status_label.clear()
+        if outcome.status == OperationStatus.SUCCESS:
+            self.accept()
+            return
+        if outcome.status == OperationStatus.REFUSED and not outcome.stale_capture:
+            self._set_choices_enabled(True)
+            self._mode_changed()
+        else:
+            self._set_choices_enabled(False)
+            self.checkout_button.setEnabled(False)
+
+    def _set_choices_enabled(self, enabled: bool) -> None:
+        """Enable or disable every choice of the form together; Checkout and Cancel are handled apart."""
+        for widget in (self.branch_selector, self.remote_options, self.local_radio, self.remote_radio):
+            widget.setEnabled(enabled)
+
+    def _submit(self) -> None:
+        """Emit a valid explicit request once without performing Git work in the widget."""
+        if self.closed or self.busy or self.intent is None or not self.checkout_button.isEnabled():
+            return
+        self.busy = True
+        self._set_choices_enabled(False)
+        self.checkout_button.setEnabled(False)
+        self.cancel_button.setEnabled(False)
+        self.status_label.clear()
+        self.checkout_requested.emit(self.intent)
+
+    def reject(self) -> None:
+        """Keep the captured form visible until its native operation finishes."""
+        if not self.busy:
+            super().reject()
+
+    def accept(self) -> None:
+        """Prevent direct acceptance while the native operation still owns the form."""
+        if not self.busy:
+            super().accept()
+
+    def closeEvent(self, event: QCloseEvent) -> None:
+        """Ignore window closure while Git is still using the captured choices."""
+        if self.busy:
+            event.ignore()
+            return
+        super().closeEvent(event)
+
+    def _closed(self) -> None:
+        """Invalidate pending callbacks and return focus to the still-live launching control."""
+        self.closed = True
+        self.read_generation += 1
+        if self.return_focus is not None and isValid(self.return_focus):
+            self.return_focus.setFocus()

gitpane/ui/reference/checkout_revision_dialog.py

@@ -0,0 +1,182 @@
+"""Reproduce the Git Extensions "Checkout revision" window: one commit, an optional force, one Checkout button."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QMargins, QSize, Qt, Signal
+from PySide6.QtWidgets import QCheckBox, QHBoxLayout, QLabel, QVBoxLayout, QWidget
+
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.reference.reference_edit import CheckoutIntent, CheckoutMode
+from gitpane.ui.look.action_icon import action_icon
+from gitpane.ui.look.theme_look import follow_theme
+from gitpane.ui.reference.reference_form import ReferenceFormDialog
+from gitpane.ui.reference.revision_picker import RevisionPicker
+from gitpane.ui.widget.dialog_layout import BandButtonSizing, fit_caption_column, fit_capture_control, install_banded_layout
+from gitpane.ui.widget.refresh_advice import refresh_advice_text
+
+if TYPE_CHECKING:
+    from gitpane.operation.repository_operation import OperationOutcome
+    from gitpane.reference.reference_snapshot import ReferenceSnapshot
+
+CHECKOUT_REVISION_TITLE = "Checkout revision"
+CHECKOUT_REVISION_CAPTION = "Checkout this revision"
+FORCE_CHECKOUT_LABEL = "Force (reset local changes)"
+CHECKOUT_BUTTON_TEXT = "Checkout"
+# Client area of the Git Extensions capture (481 x 131 inside the window borders and title bar).
+CHECKOUT_REVISION_CLIENT_SIZE = QSize(481, 131)
+# Measured on the capture in client pixels at 100 %: white body y 0-89, band line y 90, band y 91-130; caption ink
+# x 18-134 and y 26-34; revision field (145, 17, 260, 23) with its choose button (409, 16, 23, 22) and the "-13" ink
+# from x 442; Force square (145, 49, 13, 13); Checkout button (385, 99, 82, 23) in the band.
+# The body margins put the caption label at x 17 (a label writes its text about 1 px after its edge) and the top of
+# the revision row, whose choose button is its highest control, at y 16. The band sits at the bottom through a final
+# stretch, so enlarging the resizable window only grows the empty body.
+CHECKOUT_REVISION_BODY_MARGINS = QMargins(17, 16, 14, 0)
+# Caption width from its left edge to the revision field (145 - 17); a wider caption text widens it.
+REVISION_CAPTION_WIDTH = 128
+REVISION_FIELD_WIDTH = 260
+# The caption's text sits 2 px below the middle of the revision row in the capture; a top margin twice as high
+# lowers the vertically centered label by that much.
+CAPTION_TEXT_DROP = 2
+# Space between the revision row (y 16-39) and the Force check box, whose square then lands on y 49.
+REVISION_TO_FORCE_SPACE = 6
+CHECKOUT_BUTTON_SIZE = QSize(82, 23)
+
+
+class CheckoutRevisionDialog(ReferenceFormDialog):
+    """Check out one commit in detached HEAD, optionally discarding local changes, like Git Extensions.
+
+    The window only freezes a checkout request; the reference form controller reads the references, counts the commit's position
+    from HEAD and runs Git.
+    """
+
+    checkout_requested = Signal(object)
+
+    def __init__(self, session_id: str, parent: QWidget | None = None) -> None:
+        """Build the caption, the revision field, the Force check box and the button band of the capture."""
+        super().__init__(session_id, parent)
+        self.intent: CheckoutIntent | None = None
+        self.setWindowTitle(CHECKOUT_REVISION_TITLE)
+        layout = QVBoxLayout()
+        layout.setSpacing(0)
+        revision_row = QHBoxLayout()
+        revision_row.setContentsMargins(0, 0, 0, 0)
+        revision_row.setSpacing(0)
+        self.caption_label = QLabel(CHECKOUT_REVISION_CAPTION)
+        self.caption_label.setContentsMargins(0, CAPTION_TEXT_DROP * 2, 0, 0)
+        self.picker = RevisionPicker(REVISION_FIELD_WIDTH)
+        self.caption_label.setBuddy(self.picker.revision_edit)
+        revision_row.addWidget(self.caption_label, 0, Qt.AlignmentFlag.AlignVCenter)
+        revision_row.addWidget(self.picker, 1)
+        layout.addLayout(revision_row)
+        layout.addSpacing(REVISION_TO_FORCE_SPACE)
+        self.force_checkbox = QCheckBox(FORCE_CHECKOUT_LABEL)
+        # Indented by the caption's width, which follows the caption's text.
+        self.force_row = QHBoxLayout()
+        self.force_row.setSpacing(0)
+        self.force_row.addWidget(self.force_checkbox)
+        self.force_row.addStretch(1)
+        layout.addLayout(self.force_row)
+        layout.addStretch(1)
+        self.submit_button.setText(CHECKOUT_BUTTON_TEXT)
+        self.submit_button.setIcon(action_icon("checkout_commit", self.devicePixelRatioF()))
+        self.submit_button.setEnabled(False)
+        # Git Extensions shows this form as a white body over a grey band holding its single button; there is no
+        # Cancel button, Escape and the title bar close it.
+        self.button_band = install_banded_layout(self, layout, [self.submit_button], body_margins=CHECKOUT_REVISION_BODY_MARGINS, button_sizing=BandButtonSizing.WINDOW)
+        # The revision picker laid its own look when it was built; the form only has it laid again at each switch.
+        follow_theme(self, self.apply_theme_look)
+        # Enter runs Checkout from anywhere in the form. The role is set only now, once the button belongs to the
+        # dialog: Qt then records it as the dialog's main default and gives it back whenever the focus moves, instead
+        # of dropping it the first time the button loses the focus.
+        self.submit_button.setDefault(True)
+        self.submit_button.clicked.connect(self._submit)
+        self.force_checkbox.toggled.connect(self._update_intent)
+        # Connected before the reference form controller binds the field, so a new target's position is invalidated before it is
+        # counted again.
+        self.picker.target_changed.connect(self._target_changed)
+        self.resize(CHECKOUT_REVISION_CLIENT_SIZE)
+        self.refresh_metrics()
+        self.picker.revision_edit.setFocus()
+
+    def apply_theme_look(self) -> None:
+        """Lay the light or dark look of the form's own controls, decided on the application palette; called again at each switch.
+
+        The body and the band follow the switch on their own; the revision field, its choose button and its counter are
+        the revision picker's. Only style sheets and palettes change: the revision shown and Force stay as they are.
+        """
+        self.picker.apply_theme_look()
+
+    def fit_capture_controls(self) -> None:
+        """Give the caption and the Checkout button the capture's sizes, or more when their text needs it.
+
+        A wider caption moves the revision field and the Force check box right by the same amount, so they stay lined up.
+        """
+        caption_width = fit_caption_column((self.caption_label,), REVISION_CAPTION_WIDTH)
+        self.force_row.setContentsMargins(caption_width, 0, 0, 0)
+        fit_capture_control(self.submit_button, CHECKOUT_BUTTON_SIZE)
+
+    def populate(self, snapshot: ReferenceSnapshot, target_oid: str) -> None:
+        """Show the commit to check out against the references the window was opened on."""
+        if self.closed or self.busy or self.completed:
+            return
+        self.snapshot = snapshot
+        self.set_target(target_oid)
+        self.picker.revision_edit.setFocus()
+
+    def set_target(self, oid: str, *, rewrite_text: bool = True) -> None:
+        """Target another commit; its short hash replaces the field unless the user's typed text is kept."""
+        if self.closed or self.busy or self.completed:
+            return
+        self.picker.show_revision(oid, rewrite_text=rewrite_text)
+
+    def _target_changed(self, _oid: str | None) -> None:
+        """Drop any position still being counted for the previous target and freeze the new request, if any."""
+        self.position_generation += 1
+        self._update_intent()
+
+    def _update_intent(self) -> None:
+        """Freeze the current commit and Force choice into the request Checkout would send."""
+        self.intent = None
+        target_oid = self.picker.target_oid
+        if self.snapshot is not None and target_oid is not None:
+            try:
+                self.intent = CheckoutIntent.capture(self.snapshot, target_oid, refresh_advice=refresh_advice_text, session_id=self.session_id, mode=CheckoutMode.DETACHED,
+                                                     force_checkout=self.force_checkbox.isChecked())
+            except ValueError as error:
+                self.show_error(str(error))
+                return
+        self.submit_button.setEnabled(self.intent is not None and not self.busy and not self.completed and not self.closed)
+
+    def _submit(self) -> None:
+        """Freeze the form and hand its request to the reference form controller once."""
+        if self.closed or self.busy or self.completed or self.intent is None or not self.submit_button.isEnabled():
+            return
+        self.busy = True
+        self._set_controls_enabled(False)
+        self.checkout_requested.emit(self.intent)
+
+    def show_outcome(self, outcome: OperationOutcome) -> None:
+        """Close after a successful checkout, give the form back after a refusal it can retry, freeze it after any other result.
+
+        A refused checkout stopped before Git ran, so nothing was written and the form becomes usable again, like the
+        other reference forms, unless its capture no longer matches the repository: a second click would only be
+        refused again, and the console says to reopen the form or refresh. A failed, partial or unknown checkout may
+        have changed files: the request stays visible, greyed, while the console explains what happened.
+        """
+        self.busy = False
+        if outcome.status == OperationStatus.SUCCESS:
+            self.accept()
+            return
+        if outcome.status == OperationStatus.REFUSED and not outcome.stale_capture:
+            self._set_controls_enabled(True)
+            self._update_intent()
+            return
+        self.completed = True
+        self._set_controls_enabled(False)
+
+    def _set_controls_enabled(self, enabled: bool) -> None:
+        """Enable or disable every choice of the form together."""
+        for widget in (self.picker, self.force_checkbox, self.submit_button):
+            widget.setEnabled(enabled)