gitpane 1.0.0__py3-none-any.whl

gitpane/controller/console_registry.py

@@ -0,0 +1,38 @@
+"""Keep the operation consoles of GitPane so the ones that reported a pause can close once it is answered."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shiboken6 import isValid
+
+if TYPE_CHECKING:
+    from gitpane.ui.console.operation_dialog import OperationDialog
+    from gitpane.worktree.worktree_snapshot import WorktreeKey
+
+
+class ConsoleRegistry:
+    """The consoles of the reference, rebase and transport operations by operation, and the ones of each worktree that wait for the answer to a pause."""
+
+    def __init__(self) -> None:
+        """Start with no console; the wiring builds the registry after the window activation filter, and the controllers that open consoles receive it."""
+        self.rebase_output_by_id: dict[str, OperationDialog] = {}
+        # Launch, Continue and Abort consoles of a rebase, cherry-pick or revert that published a pause, per worktree, so they can be settled once
+        # the user answered the pause or the operation ended instead of lingering after the pause they reported is gone.
+        self.paused_console_ids_by_key: dict[WorktreeKey, list[str]] = {}
+        self.reference_output_by_id: dict[str, OperationDialog] = {}
+        self.transport_dialog_by_id: dict[str, OperationDialog] = {}
+
+    def settle_paused_consoles(self, key: WorktreeKey) -> None:
+        """Let the consoles that reported a pause of this worktree close by Keep dialog open now that the operation ended."""
+        for operation_id in self.paused_console_ids_by_key.pop(key, []):
+            self.settle_answered_console(operation_id)
+
+    def settle_answered_console(self, operation_id: str) -> None:
+        """Let one console that waited for the user's answer (a paused replay, a refused push) close by Keep dialog open.
+
+        A console already dismissed by the user is simply gone.
+        """
+        output = self.reference_output_by_id.get(operation_id) or self.rebase_output_by_id.get(operation_id) or self.transport_dialog_by_id.get(operation_id)
+        if output is not None and isValid(output):
+            output.settle_pause()

gitpane/controller/emoji_window_controller.py

@@ -0,0 +1,95 @@
+"""Open the emoji keyboard of GitPane where its user left it."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shiboken6 import isValid
+
+from gitpane.config import EMOJI_WINDOW_GEOMETRY_PREFERENCE_KEY
+from gitpane.history.file_history import WindowCapability
+from gitpane.operation.diagnostic import Diagnostic
+from gitpane.ui.emoji.emoji_font import load_emoji_font
+from gitpane.ui.emoji.emoji_window import EmojiWindow
+
+if TYPE_CHECKING:
+    from PySide6.QtCore import QRect
+    from PySide6.QtWidgets import QApplication
+
+    from gitpane.controller.operation_policy import OperationPolicy
+    from gitpane.controller.session_registry import SessionRegistry
+    from gitpane.operation.diagnostic import DiagnosticLog
+    from gitpane.preference.preference_store import PreferenceStore
+
+
+class EmojiWindowController:
+    """The single floating emoji keyboard shared by every repository window, with its saved place and the one-time report of its font."""
+
+    def __init__(self, *, session_registry_controller: SessionRegistry, operation_policy_controller: OperationPolicy, application: QApplication, preference: PreferenceStore, diagnostic_log: DiagnosticLog | None) -> None:
+        """Receive the application, the preferences and the lower controllers the keyboard works with; the wiring builds it after the welcome controller, and the repository windows ask it for the keyboard."""
+        self.session_registry_controller = session_registry_controller
+        self.operation_policy_controller = operation_policy_controller
+        self.application = application
+        self.preference = preference
+        self.diagnostic_log = diagnostic_log
+        self.emoji_window: EmojiWindow | None = None
+        self.emoji_font_reported = False
+
+    def open_emoji_window(self, session_id: str) -> EmojiWindow | None:
+        """Open the single floating emoji keyboard, shared by every repository window, or bring it back.
+
+        It has no Qt parent so that it survives a repository switch in the window that asked for it, and a second
+        request, from any window, brings the same window back instead of opening another one. Without a saved geometry,
+        its first size is computed on the screen of the window that asked, where it opens.
+        """
+        if not self.operation_policy_controller.allows(session_id, WindowCapability.MANAGE):
+            return None
+        if self.emoji_window is not None and isValid(self.emoji_window):
+            self.emoji_window.showNormal()
+            self.emoji_window.raise_()
+            self.emoji_window.activateWindow()
+            return self.emoji_window
+        window = EmojiWindow(self.application.clipboard())
+        self.emoji_window = window
+        window.geometry_saved.connect(self._save_emoji_window_geometry)
+        if not window.restore_saved_geometry(str(self.preference.read(EMOJI_WINDOW_GEOMETRY_PREFERENCE_KEY))):
+            # The keyboard is shared by every window and has no Qt parent; it opens over the window that asked for it.
+            window.placement_anchor = self.session_registry_controller.window_by_session.get(session_id)
+            window.resize_to_whole_grid(self._emoji_window_available_area(session_id))
+        window.showNormal()
+        self.report_emoji_font()
+        return window
+
+    def _emoji_window_available_area(self, session_id: str) -> QRect:
+        """Return the usable area of the screen the keyboard opens on: that of the window that asked, else the primary screen.
+
+        The keyboard has no parent and is not shown yet, so its own screen is still the primary one whatever window asked.
+        """
+        anchor = self.session_registry_controller.window_by_session.get(session_id)
+        screen = anchor.screen() if anchor is not None else self.application.primaryScreen()
+        return screen.availableGeometry()
+
+    def report_emoji_font(self) -> None:
+        """Write once per process, to the --log file, why the bundled colour emoji font is not used.
+
+        The application keeps working with the system fonts, so nothing is shown on screen; only the font warning is
+        written, never a symbol or the message draft. The first symbol area that needs the font triggers the report.
+        """
+        if self.emoji_font_reported:
+            return
+        self.emoji_font_reported = True
+        status = load_emoji_font()
+        if status.warning and self.diagnostic_log is not None:
+            self.diagnostic_log.write_line(status.warning)
+
+    def _save_emoji_window_geometry(self, value: str) -> None:
+        """Keep the floating keyboard's place and size for its next opening, in this session or a later one.
+
+        A refused write only costs the remembered place, so it goes to the --log file and never interrupts the user.
+        """
+        try:
+            self.preference.update({EMOJI_WINDOW_GEOMETRY_PREFERENCE_KEY: value})
+        except (OSError, ValueError, TypeError) as error:
+            diagnostic = Diagnostic("Save emoji keyboard position", "", "", [], str(error)).prepare()
+            if self.diagnostic_log is not None:
+                self.diagnostic_log.write(diagnostic)

gitpane/controller/file_action_controller.py

@@ -0,0 +1,479 @@
+"""Act on a file a repository window or Prepare changes shows, outside Git's history."""
+
+from __future__ import annotations
+
+import os
+import sys
+import uuid
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QStandardPaths
+from PySide6.QtWidgets import QFileDialog, QMessageBox, QPushButton
+from shiboken6 import isValid
+
+from gitpane.config import ProcessPriority, SharedText
+from gitpane.history.file_history import FileHistoryAnchor, WindowCapability
+from gitpane.history.repository_value import FilePanel, FileReadIdentity, RequestIdentity, TreeEntry, historical_selection
+from gitpane.operation.diagnostic import Diagnostic, SensitiveTextFilter
+from gitpane.sequencer.conflict import conflict_path_label
+from gitpane.system.qt_folder import writable_folder
+from gitpane.tool.difftool import DifftoolRecipe
+from gitpane.tool.git_executable import terminal_git_filename
+from gitpane.tool.kdiff3_install import status_bar_refusal_text
+from gitpane.tool.system_tool import git_editor_line, git_shell_filename, text_editor_command, text_editor_unavailable_reason, uses_git_editor, worktree_filename
+from gitpane.ui.console.error_dialog import ErrorDialog
+from gitpane.ui.window_control.dialog_modality import open_window_modal, prepare_message_box
+from gitpane.worktree.command_sequence import GitCommand, GitCommandError
+from gitpane.worktree.historical_restore import RESTORE_SELECTED_VERSION_TITLE
+from gitpane.worktree.worktree_snapshot import WorktreeKey
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from gitpane.controller.history_read_controller import HistoryReadController
+    from gitpane.controller.opening_controller import OpeningController
+    from gitpane.controller.operation_policy import OperationPolicy
+    from gitpane.controller.refresh_controller import FullRefreshRead, RefreshController
+    from gitpane.controller.session_registry import SessionRegistry
+    from gitpane.controller.staging_session_registry import StagingSessionRegistry
+    from gitpane.history.repository import GitRepository
+    from gitpane.history.repository_value import RepositoryContext, RevisionEntry
+    from gitpane.operation.diagnostic import DiagnosticLog, PreparedDiagnostic
+    from gitpane.preference.preference_store import PreferenceStore
+    from gitpane.tool.difftool import DifftoolLaunch, DifftoolService
+    from gitpane.tool.system_editor_default import SystemEditorDefault
+    from gitpane.tool.system_tool import OperationResult, SystemToolService, TextEditorCommand, ToolResult
+    from gitpane.tool.terminal_recipe import TerminalDescriptor
+    from gitpane.ui.repository.repository_window import RepositoryWindow
+    from gitpane.worktree.file_action_target import FileActionSelection, FileRestoreTarget
+    from gitpane.worktree.historical_restore import HistoricalRestoreRequest, HistoricalRestoreService
+    from gitpane.worktree.mutation import MutationOutcome
+    from gitpane.worktree.worktree_service import WorktreeService
+
+# Names of the file tools in their start requests: those of Prepare changes are told apart from those of a repository window.
+STAGING_FOLDER_TOOL = "staging-folder"
+STAGING_TEXT_EDITOR_TOOL = "staging-text-editor"
+TEXT_EDITOR_TOOL = "text-editor"
+# Tools started from Prepare changes: their request carries the Git folder, and their failures go to its status area.
+STAGING_TOOL_SET = frozenset((STAGING_FOLDER_TOOL, STAGING_TEXT_EDITOR_TOOL))
+RESTORE_UNCHANGED_TEXT = "'{path}' already matches the selected version. Nothing was restored."
+RESTORE_UNCHANGED_STATUS = "The selected version is already present."
+RESTORED_STATUS = "Selected version restored. The index and HEAD are unchanged."
+
+
+class FileActionController:
+    """The actions on one file of a repository window or of Prepare changes: external tools, file history, restoring a selected version, external comparison and Save as, each checked against the authority of the window that asks."""
+
+    def __init__(self, *, session_registry_controller: SessionRegistry, operation_policy_controller: OperationPolicy, staging_session_registry_controller: StagingSessionRegistry, refresh_controller: RefreshController,
+                 history_read_controller: HistoryReadController, opening_controller: OpeningController, preference: PreferenceStore, repository: GitRepository, difftool: DifftoolService, worktree_service: WorktreeService,
+                 historical_restore: HistoricalRestoreService, diagnostic_log: DiagnosticLog | None, system_tool: SystemToolService, system_editor_default: SystemEditorDefault) -> None:
+        """Receive the services and the lower controllers the file actions work with; the wiring builds it after the emoji keyboard controller, and the repository windows and Prepare changes reach it through the wiring.
+
+        ``system_editor_default`` keeps the text editor the system names, read in the background, which the editor
+        detection follows while no editor choice is saved.
+        """
+        self.session_registry_controller = session_registry_controller
+        self.operation_policy_controller = operation_policy_controller
+        self.staging_session_registry_controller = staging_session_registry_controller
+        self.preference = preference
+        self.repository = repository
+        self.worktree_service = worktree_service
+        self.diagnostic_log = diagnostic_log
+        self.system_tool = system_tool
+        self.system_editor_default = system_editor_default
+        self.refresh_controller = refresh_controller
+        self.history_read_controller = history_read_controller
+        self.opening_controller = opening_controller
+        self.difftool = difftool
+        self.historical_restore = historical_restore
+        # The core.editor value of each repository, read once per repository window in the background, because no
+        # process may start while a file menu is being built.
+        self.git_editor_setting_by_repository_dir: dict[str, str] = {}
+        # The window that asked for each restoration of a selected version, until its result is shown.
+        self.restore_session_by_operation_id: dict[str, str] = {}
+
+    def open_explorer(self, session_id: str) -> bool:
+        """Open the worktree only from a window allowed to invoke external tools."""
+        if not self.operation_policy_controller.allows(session_id, WindowCapability.MANAGE):
+            return False
+        self.system_tool.open_explorer((session_id, "explorer"), self.session_registry_controller.session_by_id[session_id].repository_context.repository_dir)
+        return True
+
+    def launch_terminal(self, session_id: str, descriptor: TerminalDescriptor | None) -> bool:
+        """Reject terminal intents from limited windows even when emitted directly."""
+        if not self.operation_policy_controller.allows(session_id, WindowCapability.MANAGE) or descriptor is None:
+            return False
+        self.system_tool.launch_terminal((session_id, "terminal"), descriptor, self.session_registry_controller.session_by_id[session_id].repository_context.repository_dir)
+        return True
+
+    def _file_action_allowed(self, session_id: str, selection: FileActionSelection) -> bool:
+        """Validate direct intentions as well as menu clicks against the live owning window."""
+        window = self.session_registry_controller.window_by_session.get(session_id)
+        return (self.operation_policy_controller.allows(session_id, WindowCapability.FILE_MENU) and window is not None and isValid(window)
+                and window.file_action_is_current(selection))
+
+    def show_file_folder(self, session_id: str, selection: FileActionSelection) -> None:
+        """Locate the selected historical name in the real working tree without restoring it."""
+        if not self._file_action_allowed(session_id, selection):
+            return
+        session = self.session_registry_controller.session_by_id[session_id]
+        identity = FileReadIdentity(RequestIdentity(session_id, session.generation, oid=selection.commit_oid))
+        chosen = historical_selection(selection.entry, identity)
+        self.system_tool.show_file_location((session_id, "file-folder"), session.repository_context, chosen.path)
+
+    def show_file_in_text_editor(self, session_id: str, selection: FileActionSelection) -> None:
+        """Open the working copy of the selected historical name in the editor, never a version of the commit."""
+        if not self._file_action_allowed(session_id, selection):
+            return
+        session = self.session_registry_controller.session_by_id[session_id]
+        identity = FileReadIdentity(RequestIdentity(session_id, session.generation, oid=selection.commit_oid))
+        chosen = historical_selection(selection.entry, identity)
+        self.launch_text_editor((session_id, TEXT_EDITOR_TOOL), session.repository_context, chosen.path)
+
+    def launch_text_editor(self, request_id: tuple[str, str], context: RepositoryContext, path: bytes) -> None:
+        """Start the chosen editor on the working copy file of a Git path, checking again that it can open.
+
+        The file may have gone, or the editor changed, between the menu and the click; the reason is then shown
+        and nothing starts.
+        """
+        command = self.text_editor_command(context)
+        reason = text_editor_unavailable_reason(context, path, command)
+        if reason or command is None:
+            self._show_text_editor_refusal(request_id, reason)
+            return
+        self.system_tool.launch_text_editor(request_id, command, worktree_filename(context, path))
+
+    def _staging_consultation_failed(self, git_dir: str, cause: str, diagnostic: PreparedDiagnostic | None = None) -> None:
+        """Show why a file action of Prepare changes did not happen, in the status area of that Prepare changes.
+
+        A tool that failed to start passes its prepared diagnostic, so the details name the program that failed.
+        """
+        for key, staging in self.staging_session_registry_controller.staging_by_key.items():
+            if key.git_dir == git_dir:
+                staging._consultation_failed(cause, diagnostic)
+
+    def _show_text_editor_refusal(self, request_id: tuple[str, str], reason: str) -> None:
+        """Show in the requesting window why the editor was not started."""
+        session_id, tool = request_id
+        if tool in STAGING_TOOL_SET:
+            self._staging_consultation_failed(session_id, reason)
+            return
+        window = self.session_registry_controller.window_by_session.get(session_id)
+        if window is not None and isValid(window) and not window.is_closed:
+            window.statusBar().showMessage(reason)
+
+    def text_editor_command(self, context: RepositoryContext) -> TextEditorCommand | None:
+        """Choose the editor for a working copy file with the rule of this platform.
+
+        On Windows: Settings, then what Git would use, then the detected editor. Elsewhere: Settings or the detected
+        editor only, since an editor set for Git is often a terminal editor that shows nothing without a terminal. The
+        detected editor is the one Settings shows while nothing is saved, and it is not saved here either. No process
+        starts: core.editor, only kept on Windows, comes from the value read when the repository window opened, and a
+        read not finished yet counts as unset; the click asks again with the value known by then. The editor the system
+        names for plain text is read in the background the same way: a read not finished yet counts as the system
+        naming nothing.
+        """
+        editor_recipe = self.preference.initialize_editor(repository_dirs=(context.repository_dir,), system_editor_id=self.system_editor_default.system_editor_id)
+        git_editor = git_editor_line(os.environ, self.git_editor_setting_by_repository_dir.get(context.repository_dir, ""))
+        git_utility_dir = str(self.preference.value_by_key["git_utility_dir"])
+        return text_editor_command(editor_recipe, git_editor, lambda: git_shell_filename(git_filename=terminal_git_filename(self.repository.git_filename), git_utility_dir=git_utility_dir),
+                                   saved=self.preference.editor_choice_saved())
+
+    def text_editor_reason(self, session_id: str, selection: FileActionSelection) -> str:
+        """Tell the file menu why the working copy of its file cannot be opened in a text editor, or answer an empty reason."""
+        session = self.session_registry_controller.session_by_id.get(session_id)
+        if session is None:
+            return ""
+        identity = FileReadIdentity(RequestIdentity(session_id, session.generation, oid=selection.commit_oid))
+        chosen = historical_selection(selection.entry, identity)
+        context = session.repository_context
+        return text_editor_unavailable_reason(context, chosen.path, self.text_editor_command(context))
+
+    def read_git_editor_setting(self, context: RepositoryContext) -> None:
+        """Read core.editor once per repository window, in the background, because no process may start while a menu is built.
+
+        Git reads it in the repository itself, so its includes and its ownership check of the repository apply as
+        when Git starts the editor. A failed read keeps the value unset and goes to the --log file. Outside Windows the
+        editor set for Git is never started, so no process is started to read it.
+        """
+        if not uses_git_editor():
+            return
+        if context.is_bare or context.worktree_dir is None:
+            return
+
+        def read() -> Generator[GitCommand, bytes, bytes]:
+            """Ask Git for the value; exit code 1 means it is not set."""
+            output = yield GitCommand(["config", "--get", "core.editor"], accepted_codes=(0, 1))
+            return output
+
+        def complete(value: object, error: Exception | None) -> None:
+            """Keep the value for this repository, or log why it could not be read."""
+            if error is not None:
+                if self.diagnostic_log is not None:
+                    self.diagnostic_log.write_line("Cannot read core.editor of " + context.repository_dir + ": " + str(error))
+                return
+            self.git_editor_setting_by_repository_dir[context.repository_dir] = bytes(value).decode("utf-8", "surrogateescape").strip()
+
+        self.worktree_service.run(context, self.repository.git_filename, read(), complete, priority=ProcessPriority.BACKGROUND)
+
+    def tool_started(self, request_id: tuple[str, str], label: str) -> None:
+        """Mark only the requesting window's tool action as starting."""
+        session_id, tool = request_id
+        window = self.session_registry_controller.window_by_session.get(session_id)
+        if window is not None and isValid(window) and not window.is_closed:
+            window.set_tool_busy(tool, True)
+            window.statusBar().showMessage(f"Opening {label}…")
+
+    def _tool_failure_diagnostic(self, result: ToolResult) -> PreparedDiagnostic:
+        """Prepare the diagnostic of a tool that did not start, naming its program and arguments, and write it to the --log file.
+
+        Prepare changes and the repository window show the same prepared text, so the screen and the log agree.
+        """
+        diagnostic = Diagnostic(f"Open {result.label}", result.repository_dir, result.program_filename, list(result.arguments), result.cause).prepare()
+        if self.diagnostic_log is not None:
+            self.diagnostic_log.write(diagnostic)
+        return diagnostic
+
+    def tool_finished(self, result: ToolResult) -> None:
+        """Release startup controls and show actual system failures in the owning window."""
+        session_id, tool = result.request_id
+        if tool in STAGING_TOOL_SET:
+            if result.cause:
+                self._staging_consultation_failed(session_id, result.cause, self._tool_failure_diagnostic(result))
+            return
+        window = self.session_registry_controller.window_by_session.get(session_id)
+        if window is None or not isValid(window) or window.is_closed:
+            return
+        window.set_tool_busy(tool, False)
+        window.statusBar().clearMessage()
+        if not result.cause:
+            return
+        diagnostic = self._tool_failure_diagnostic(result)
+        dialog = ErrorDialog(diagnostic, window)
+        if tool == "terminal":
+            choose_button = QPushButton(SharedText.TERMINAL_CHOOSE.value, dialog)
+            dialog.layout().addWidget(choose_button)
+            choose_button.clicked.connect(dialog.accept)
+            choose_button.clicked.connect(lambda: window.terminal_menu.popup(window.terminal_button.mapToGlobal(window.terminal_button.rect().bottomLeft())))
+        self.session_registry_controller.dialogs.append(dialog)
+        dialog.finished.connect(lambda: self.session_registry_controller.dialogs.remove(dialog) if dialog in self.session_registry_controller.dialogs else None)
+        dialog.finished.connect(dialog.deleteLater)
+        open_window_modal(dialog)
+
+    def open_file_history(self, session_id: str, entry: RevisionEntry | TreeEntry) -> RepositoryWindow | None:
+        """Create a separately captured read-only session for the chosen historical side."""
+        if not self.operation_policy_controller.allows(session_id, WindowCapability.FILE_MENU):
+            return None
+        source = self.session_registry_controller.session_by_id[session_id]
+        if isinstance(entry, TreeEntry):
+            if entry not in source.tree_entries or source.selected_oid is None:
+                return None
+            anchor = FileHistoryAnchor(source.selected_oid, entry.path, entry.oid)
+        else:
+            if not any(entry in group.entries for group in source.diff_groups):
+                return None
+            anchor = FileHistoryAnchor.from_entry(entry)
+        identity = RequestIdentity(uuid.uuid4().hex, 1)
+        self.session_registry_controller.identity_by_session[identity.session_id] = identity
+        self.repository.context_by_session[identity.session_id] = source.repository_context
+        self.opening_controller.opened(identity, source.repository_context, None, anchor, self.session_registry_controller.window_by_session.get(session_id))
+        return self.session_registry_controller.window_by_session[identity.session_id]
+
+    def restore_historical_file(self, session_id: str, selection: FileActionSelection | None, target: FileRestoreTarget | None = None) -> None:
+        """Restore the viewed commit or its chosen parent, confirming only over a new local addition."""
+        if selection is None or not self.operation_policy_controller.allows(session_id, WindowCapability.RESTORE) or not self._file_action_allowed(session_id, selection):
+            return
+        session = self.session_registry_controller.session_by_id[session_id]
+        context = session.repository_context
+        if context.is_bare or context.worktree_dir is None:
+            return
+        window = self.session_registry_controller.window_by_session[session_id]
+        targets = window.file_restore_targets(selection) or []
+        if target is None:
+            target = next(iter(targets), None)
+        if target is None or target.unavailable or target not in targets:
+            return
+        message = target.message
+
+        def validate() -> bool:
+            """Prevent a closed or reoriented window from authorizing a previous selection."""
+            return self.operation_policy_controller.allows(session_id, WindowCapability.RESTORE) and self._file_action_allowed(session_id, selection)
+
+        def prepared(request: HistoricalRestoreRequest | None, error: Exception | None) -> None:
+            """Publish the prepared source, retaining confirmation when a new local file would be replaced."""
+            if error is not None:
+                if validate():
+                    diagnostic = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic(RESTORE_SELECTED_VERSION_TITLE, context.repository_dir,
+                        self.repository.git_filename, [], str(error)).prepare()
+                    if self.diagnostic_log is not None:
+                        self.diagnostic_log.write(diagnostic)
+                    dialog = ErrorDialog(diagnostic, window)
+                    self.session_registry_controller.dialogs.append(dialog)
+                    dialog.finished.connect(lambda: self.session_registry_controller.dialogs.remove(dialog) if dialog in self.session_registry_controller.dialogs else None)
+                    dialog.finished.connect(dialog.deleteLater)
+                    open_window_modal(dialog)
+                return
+            if not validate():
+                self.historical_restore.cancel(request)
+                return
+            needs_confirmation = request.before.exists and request.snapshot.requires_file_confirmation((request.path,))
+            accepted = not needs_confirmation or window.confirm_historical_restore(request)
+            if not accepted or not validate():
+                self.historical_restore.cancel(request)
+                return
+            self.restore_session_by_operation_id[request.operation_id] = session_id
+            self.historical_restore.restore(request)
+
+        self.historical_restore.prepare(context, self.repository.git_filename, selection, message, session.mode, validate, prepared, source_oid=target.commit_oid)
+
+    def historical_restore_finished(self, outcome: MutationOutcome) -> None:
+        """Refresh affected file views and report the actual retained restoration result.
+
+        A restoration that found the file already at the selected version wrote nothing, which a status bar text alone
+        hides too easily: the window where the user asked also opens a message saying so. The other windows of the
+        worktree only read again.
+        """
+        requesting_session_id = self.restore_session_by_operation_id.pop(outcome.operation_id, None)
+        if outcome.operation_id not in self.historical_restore.outcome_by_id:
+            return
+        shared_by_key: dict[WorktreeKey, FullRefreshRead] = {}
+        for session_id, session in tuple(self.session_registry_controller.session_by_id.items()):
+            if session.is_closed or WorktreeKey.from_context(session.repository_context) != outcome.key:
+                continue
+            window = self.session_registry_controller.window_by_session.get(session_id)
+            if window is None or not isValid(window) or window.is_closed:
+                continue
+            if outcome.diagnostic is not None:
+                dialog = ErrorDialog(outcome.diagnostic, window)
+                self.session_registry_controller.dialogs.append(dialog)
+                dialog.finished.connect(lambda dialog=dialog: self.session_registry_controller.dialogs.remove(dialog) if dialog in self.session_registry_controller.dialogs else None)
+                dialog.finished.connect(dialog.deleteLater)
+                open_window_modal(dialog)
+            else:
+                window.statusBar().showMessage(RESTORE_UNCHANGED_STATUS if outcome.status == "unchanged" else RESTORED_STATUS)
+                if outcome.status == "unchanged" and session_id == requesting_session_id:
+                    self._show_unchanged_restore(window, outcome)
+            self.refresh_controller.refresh(session_id, full_refresh_read=self.refresh_controller.full_refresh_read_for(session, shared_by_key))
+        self.refresh_controller.observe_full_refresh_pauses(shared_by_key)
+
+    def _show_unchanged_restore(self, window: RepositoryWindow, outcome: MutationOutcome) -> None:
+        """Tell the user, over the window that asked, that the file already had the selected version and nothing was written."""
+        path_label = ", ".join(conflict_path_label(path) for path in outcome.completed_paths)
+        message = QMessageBox(QMessageBox.Icon.Information, RESTORE_SELECTED_VERSION_TITLE, RESTORE_UNCHANGED_TEXT.format(path=path_label),
+                              QMessageBox.StandardButton.Ok, window)
+        prepare_message_box(message, RESTORE_SELECTED_VERSION_TITLE)
+        self.session_registry_controller.dialogs.append(message)
+        message.finished.connect(lambda _result, message=message: self.session_registry_controller.dialogs.remove(message) if message in self.session_registry_controller.dialogs else None)
+        message.finished.connect(message.deleteLater)
+        open_window_modal(message)
+
+    def compare_external(self, session_id: str) -> None:
+        """Capture a main-window comparison and preferences only after explicit activation.
+
+        With no diff tool saved, the KDiff3 detected on this system is used and saved at this first use, as Settings shows it.
+        """
+        if not self.operation_policy_controller.allows(session_id, WindowCapability.MANAGE):
+            return
+        session = self.session_registry_controller.session_by_id.get(session_id)
+        window = self.session_registry_controller.window_by_session.get(session_id)
+        if session is None or window is None or session.selected_entry is None:
+            return
+        identity = session.file_identity_by_kind.get(FilePanel.DIFF)
+        entry = session.selected_entry
+        if identity is None or window.diff_panel.selected_entry != entry or not self.history_read_controller.file_is_current(identity):
+            return
+        difftool_filename = self.preference.initialize_difftool()
+        recipe = DifftoolRecipe(difftool_filename, str(self.preference.value_by_key["difftool_command"]))
+        self.difftool.compare(entry, identity, recipe, lambda: self.history_read_controller.file_is_current(identity))
+
+    def difftool_failed(self, launch: DifftoolLaunch, cause: str) -> None:
+        """Report comparison errors without logging templates or historical contents, bold red in the source window's status bar.
+
+        --log keeps the whole cause; the status bar, which shows a single line, gets several install commands as a
+        pointer to Settings › Tools instead.
+
+        A failure reported after the tool exited, such as a refused cleanup of its copies, names the tool and says in
+        its cause the code it closed with, which is not judged: --log neither blames the tool for it nor says it did not start.
+        """
+        if launch.return_code is None:
+            diagnostic = Diagnostic("External comparison", "", "", [], cause).prepare()
+        else:
+            closed_cause = f"{cause} The comparison tool had closed with exit code {launch.return_code}."
+            diagnostic = Diagnostic("External comparison", "", launch.recipe.program_filename, [], closed_cause, ended_before_failure=True).prepare()
+        if self.diagnostic_log is not None:
+            self.diagnostic_log.write(diagnostic)
+        window = self.session_registry_controller.window_by_session.get(launch.selection.selection_identity.request_identity.session_id)
+        if window is not None:
+            window.show_status_failure(status_bar_refusal_text(cause))
+
+    def difftool_closed(self, launch: DifftoolLaunch) -> None:
+        """Tell the still-live source window that the user closed the comparison, and write to --log how the tool ended.
+
+        The exit code is not judged, so the window only says the comparison closed; the --log line keeps the tool, its
+        exit status and how long it ran, which explain a tool that closed at once without showing anything. The line
+        carries neither the arguments nor the names of the historical copies.
+        """
+        if self.diagnostic_log is not None:
+            closed_line = f"External comparison closed: {launch.recipe.program_filename}, exit status {launch.return_code}, ran {launch.run_duration_ms} ms"
+            self.diagnostic_log.write_line(SensitiveTextFilter().redact(closed_line))
+        window = self.session_registry_controller.window_by_session.get(launch.selection.selection_identity.request_identity.session_id)
+        if window is not None:
+            window.statusBar().showMessage("External comparison closed.")
+
+    def difftool_started(self, launch: DifftoolLaunch) -> None:
+        """Confirm startup only to the still-live source window."""
+        window = self.session_registry_controller.window_by_session.get(launch.selection.selection_identity.request_identity.session_id)
+        if window is not None:
+            window.statusBar().showMessage("External comparison opened. Historical copies remain available until it closes.")
+
+    def save_file_as(self, session_id: str, selection: FileActionSelection) -> None:
+        """Confirm the destination while selection is valid, then lock export to its exact blob."""
+        if not self._file_action_allowed(session_id, selection):
+            return
+        session = self.session_registry_controller.session_by_id[session_id]
+        identity = FileReadIdentity(RequestIdentity(uuid.uuid4().hex, 1, oid=selection.commit_oid), FilePanel.EXPORT)
+        chosen = historical_selection(selection.entry, identity)
+        if chosen.mode == "160000":
+            return
+        window = self.session_registry_controller.window_by_session[session_id]
+        suggested_filename = os.path.join(writable_folder(QStandardPaths.StandardLocation.DocumentsLocation, sys.platform), selection.basename())
+        destination_filename, _selected_filter = QFileDialog.getSaveFileName(window, "Save selected as", suggested_filename)
+        if not destination_filename:
+            return
+        if not self._file_action_allowed(session_id, selection):
+            if isValid(window) and not window.is_closed:
+                window.statusBar().showMessage("Saving was cancelled because the file selection changed.")
+            return
+        # A separate read session preserves the accepted blob across subsequent commit changes and Refresh.
+        export_session_id = identity.request_identity.session_id
+        self.repository.context_by_session[export_session_id] = session.repository_context
+        self.repository.identity_by_session[export_session_id] = identity.request_identity
+        self.repository.executable_by_session[export_session_id] = self.repository.executable_by_session[session_id]
+        self.session_registry_controller.export_owner_by_identity[identity] = session_id
+        window.statusBar().showMessage("Saving historical file…")
+        self.system_tool.save_historical_file(identity, session.repository_context, destination_filename,
+                                             lambda consume, completed: self.repository.stream_blob(chosen.blob_oid, identity, consume, completed),
+                                             lambda: self.repository.cancel(export_session_id), overwrite_confirmed=os.path.exists(destination_filename))
+
+    def export_finished(self, result: OperationResult) -> None:
+        """Release export resources and present errors only to a still-live source window."""
+        session_id = self.session_registry_controller.export_owner_by_identity.pop(result.request_id, None)
+        if session_id is None:
+            return
+        export_session_id = result.request_id.request_identity.session_id
+        self.repository.cancel(export_session_id)
+        self.repository.context_by_session.pop(export_session_id, None)
+        window = self.session_registry_controller.window_by_session.get(session_id)
+        if window is None or not isValid(window) or window.is_closed:
+            return
+        if not result.cause:
+            window.statusBar().showMessage("Historical file saved")
+            return
+        diagnostic = Diagnostic("Save selected as", window.context.repository_dir, "", [], result.cause).prepare()
+        if self.diagnostic_log is not None:
+            self.diagnostic_log.write(diagnostic)
+        dialog = ErrorDialog(diagnostic, window)
+        self.session_registry_controller.dialogs.append(dialog)
+        dialog.finished.connect(lambda: self.session_registry_controller.dialogs.remove(dialog) if dialog in self.session_registry_controller.dialogs else None)
+        dialog.finished.connect(dialog.deleteLater)
+        open_window_modal(dialog)