gitpane 1.0.0__py3-none-any.whl

gitpane/preference/preference_location.py

@@ -0,0 +1,40 @@
+"""Name the per-user INI file that holds GitPane's preferences.
+
+It is the only location, so a pip or pipx install, whose package folder does not belong to the user, keeps the same preferences.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from gitpane.config import APPLICATION_NAME, WINDOWS_PLATFORM
+from gitpane.system.xdg_session import xdg_config_home
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+PREFERENCE_BASENAME = "gitpane.ini"
+APPDATA_ENVIRONMENT_NAME = "APPDATA"
+# Where APPDATA points by default under the user's home folder, used when the variable is missing.
+WINDOWS_ROAMING_DIR_PARTS = ("AppData", "Roaming")
+PREFERENCE_FILE_LOG_TEXT = "Preferences file: {filename}"
+
+
+def user_preference_dir(platform: str, environment_by_name: Mapping[str, str], home_dir: str) -> str:
+    """Name the per-user folder that holds the preferences file.
+
+    A relative XDG_CONFIG_HOME is ignored, as the XDG specification asks, so the file never lands in the current folder.
+    """
+    if platform == WINDOWS_PLATFORM:
+        roaming_dir = environment_by_name.get(APPDATA_ENVIRONMENT_NAME, "") or os.path.join(home_dir, *WINDOWS_ROAMING_DIR_PARTS)
+        return os.path.join(roaming_dir, APPLICATION_NAME)
+    return os.path.join(xdg_config_home(environment_by_name, home_dir), APPLICATION_NAME)
+
+
+def user_preference_filename(platform: str, environment_by_name: Mapping[str, str], home_dir: str) -> str:
+    """Name the only preferences file GitPane uses when no file is given to it.
+
+    The system, the environment and the home folder are parameters, so every system's rule is testable from any machine.
+    """
+    return os.path.join(user_preference_dir(platform, environment_by_name, home_dir), PREFERENCE_BASENAME)

gitpane/preference/preference_store.py

@@ -0,0 +1,590 @@
+"""Persist only changed preferences so separate launches can share storage."""
+
+from __future__ import annotations
+
+import ntpath
+import os
+import posixpath
+import sys
+from enum import Enum
+from typing import TYPE_CHECKING, Self
+
+from PySide6.QtCore import QObject, QSettings, Signal
+
+from gitpane.config import (
+    ACCOUNT_SIGN_IN_METHOD_PREFERENCE_KEY,
+    AUTHENTICATION_PREFERENCE_KEY,
+    CLONE_DESTINATION_LIMIT,
+    EMOJI_WINDOW_GEOMETRY_PREFERENCE_KEY,
+    LINUX_PLATFORM,
+    MACOS_PLATFORM,
+    OPERATION_KEEP_OPEN_PREFERENCE_KEY,
+    PUSH_TRACKING_PREFERENCE_KEY,
+    RECENT_LIMIT,
+    STAGING_PROPORTION_BY_KEY,
+    WINDOWS_PLATFORM,
+)
+from gitpane.recent.mount_table import case_insensitive_path_key
+from gitpane.reference.stash import STASH_DEFAULT_BY_KEY
+from gitpane.system.path_identity import on_disk_path
+from gitpane.tool.editor_recipe import (
+    EDITOR_ARGUMENT_PREFERENCE_KEY,
+    EDITOR_DEFAULT_BY_KEY,
+    EDITOR_FILENAME_PREFERENCE_KEY,
+    EDITOR_INITIAL_PATH,
+    EDITOR_PLATFORM,
+    EDITOR_PRESET_PREFERENCE_KEY,
+    EditorRecipe,
+    build_editor_arguments,
+    detect_editor_recipe,
+)
+from gitpane.tool.kdiff3 import detect_kdiff3_filename
+from gitpane.tool.mergetool_recipe import MERGETOOL_COMMAND_PREFERENCE_KEY, MERGETOOL_DEFAULT_BY_KEY, MERGETOOL_FILENAME_PREFERENCE_KEY, MergetoolRecipe, parse_mergetool_command
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from types import ModuleType
+
+
+FETCH_DEFAULT_PREFERENCE_KEY = "fetch_default"
+
+
+class FetchMode(Enum):
+    """What a Fetch does: fetch the one remote of the current branch, or fetch every remote and prune what they deleted.
+
+    The value is the word saved in the preferences file, which every system and older GitPane versions read; the label
+    is the text of the Fetch menus, which list the modes in this order.
+    """
+
+    FETCH = ("fetch", "Fetch")
+    PRUNE_ALL = ("prune-all", "Fetch and prune all")
+
+    def __new__(cls, value: str, label: str) -> Self:
+        """Keep the saved word as the value and the menu text beside it."""
+        member = object.__new__(cls)
+        member._value_ = value
+        member.label = label
+        return member
+
+
+FETCH_INITIAL_MODE = FetchMode.PRUNE_ALL
+
+
+def fetch_mode_preference(value: object) -> FetchMode:
+    """Read a saved default Fetch, falling back to the initial mode for a word this version does not know, an empty value or another type.
+
+    The file may have been edited by hand or written by a later GitPane: the Fetch button must still have a mode.
+    """
+    try:
+        return FetchMode(value)
+    except ValueError:
+        return FETCH_INITIAL_MODE
+
+
+# Parent folders of the last clones that really started, the most recent first, offered by the next clone form.
+CLONE_DESTINATION_DIRS_PREFERENCE_KEY = "clone_destination_dirs"
+CONFLICT_PROMPT_PREFERENCE_KEY = "conflict_prompt_suppressed"
+REBASE_PROMPT_PREFERENCE_KEY = "rebase_prompt_suppressed"
+# Shown by Open repository and Settings, and raised by every refused save: they name the file and say what to do, nothing else.
+PREFERENCE_UNREADABLE_TEXT = "The preferences file cannot be read: {filename}. Fix or delete it, then restart GitPane. Nothing is saved until then."
+PREFERENCE_UNWRITABLE_TEXT = "The preferences file cannot be saved: {filename}. Check that the file is not read-only and that its folder accepts new files."
+
+PREFERENCE_DEFAULT_BY_KEY: dict[str, object] = {
+    "git_filename": "", "terminal_id": "", "terminal_label": "", "terminal_filename": "", "recent_dirs": [],
+    "difftool_filename": "", "difftool_command": '"$LOCAL" "$REMOTE"',
+    "ssh_filename": "", "git_utility_dir": "",
+    OPERATION_KEEP_OPEN_PREFERENCE_KEY: True,
+    FETCH_DEFAULT_PREFERENCE_KEY: FETCH_INITIAL_MODE.value,
+    CLONE_DESTINATION_DIRS_PREFERENCE_KEY: [],
+    CONFLICT_PROMPT_PREFERENCE_KEY: False,
+    REBASE_PROMPT_PREFERENCE_KEY: False,
+    "diff_splitter_state": "", "tree_splitter_state": "", "file_history_splitter_state": "", "diff_show_entire_file": False,
+    EMOJI_WINDOW_GEOMETRY_PREFERENCE_KEY: "",
+    AUTHENTICATION_PREFERENCE_KEY: '{"accounts": [], "global": {}, "repository": {}}',
+    ACCOUNT_SIGN_IN_METHOD_PREFERENCE_KEY: "{}",
+    PUSH_TRACKING_PREFERENCE_KEY: "{}",
+    **STAGING_PROPORTION_BY_KEY,
+    **STASH_DEFAULT_BY_KEY,
+    **MERGETOOL_DEFAULT_BY_KEY,
+    **EDITOR_DEFAULT_BY_KEY,
+}
+# Folder lists and the number of folders each keeps, the most recent first.
+DIR_LIST_LIMIT_BY_KEY = {"recent_dirs": RECENT_LIMIT, CLONE_DESTINATION_DIRS_PREFERENCE_KEY: CLONE_DESTINATION_LIMIT}
+# How each system writes, folds and recognizes absolute paths: Windows from a drive letter or a network share with
+# backslashes, Linux and macOS from the root with forward slashes. A system missing here is refused, never guessed.
+PATH_MODULE_BY_PLATFORM = {WINDOWS_PLATFORM: ntpath, LINUX_PLATFORM: posixpath, MACOS_PLATFORM: posixpath}
+# Diagnostic log line for a folder of a saved list that another system wrote: the preferences file may be shared between
+# systems, so the folder stays in the file for that system and is only left out of the lists shown here.
+FOREIGN_DIR_LOG_TEXT = "Folder written by another system kept in {key} and not used here: {folder}"
+
+
+def _path_module(platform: str) -> ModuleType:
+    """Return the path rules of ``platform``, raising OSError for a system GitPane does not know rather than guessing its rules."""
+    path_module = PATH_MODULE_BY_PLATFORM.get(platform)
+    if path_module is None:
+        raise OSError("No path rules are known for " + platform)
+    return path_module
+
+
+def saved_recent_identity(recent_dir: str, platform: str = sys.platform) -> str:
+    """Return the key that tells whether two entries of the recent history name the same repository, without touching the disk.
+
+    The history is saved with its paths already resolved, so its entries compare as normalized text: a path written
+    differently (trailing separator, ``.`` segment, other case on Windows) still matches. On macOS another letter case
+    or Unicode form (composed or decomposed accents) is the same entry too, as on its disks by default; Linux compares
+    the paths as written. The key stays text: resolving each entry again would open its folder, and a disconnected
+    network drive in the history would freeze the window while the system waits. A system without known path rules
+    raises OSError.
+    """
+    path_module = _path_module(platform)
+    absolute_dir = path_module.abspath(recent_dir)
+    if platform == MACOS_PLATFORM:
+        return case_insensitive_path_key(absolute_dir)
+    return path_module.normcase(absolute_dir)
+
+
+def split_dir_entries(value: list[str], platform: str = sys.platform) -> tuple[list[str], list[str]]:
+    """Split saved folders into those of ``platform``, absolute by its own path rules, and those another system wrote.
+
+    A preferences file can be shared between Windows, Linux and macOS: a Windows folder such as ``E:\\work`` is not an
+    absolute path on macOS and must never be read as a folder below the current one, and a POSIX folder is not absolute
+    on Windows. A relative entry is absolute on no system and goes with the other system's entries. Both parts keep the
+    saved order; nothing is read on disk. A system without known path rules raises OSError.
+    """
+    path_module = _path_module(platform)
+    own_dirs = []
+    foreign_dirs = []
+    for folder in value:
+        if path_module.isabs(folder):
+            own_dirs.append(folder)
+        else:
+            foreign_dirs.append(folder)
+    return own_dirs, foreign_dirs
+
+
+def saved_dir_entries(value: object) -> list[str]:
+    """Return a saved folder list as a list of folder texts, raising TypeError or ValueError when it cannot be one.
+
+    The INI file gives an empty list back as None and a one-folder list as plain text, both taken back as lists here.
+    """
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value] if value else []
+    if not isinstance(value, list):
+        raise TypeError("Unreadable folder list")
+    for folder in value:
+        if not isinstance(folder, str) or not folder:
+            raise ValueError("Unreadable folder path")
+    return list(value)
+
+
+def foreign_saved_dirs(value: object, platform: str = sys.platform) -> list[str]:
+    """Return the folders of a saved folder list that another system wrote, in saved order, or none when the list is unreadable.
+
+    An unreadable list has its own warning, so it gives no foreign folder; a system without known path rules raises OSError.
+    """
+    try:
+        entries = saved_dir_entries(value)
+    except (TypeError, ValueError):
+        return []
+    return split_dir_entries(entries, platform)[1]
+
+
+def normalized_dir_list(value: object, limit: int, platform: str = sys.platform) -> list[str]:
+    """Check a saved folder list and return the folders of this system, normalized, without repeats, cut to ``limit``, without touching the disk.
+
+    Folders another system wrote are left out, never normalized: making them absolute would join them to the current
+    folder. Folders compare by the key of saved_recent_identity, and the first spelling of a folder is kept with its
+    place: the list is saved most recent first, so two spellings of one folder merge into the most recent one.
+    """
+    own_dirs, _foreign_dirs = split_dir_entries(saved_dir_entries(value), platform)
+    path_module = _path_module(platform)
+    normalized_dirs = []
+    identity_set: set[str] = set()
+    for folder in own_dirs:
+        normalized_dir = path_module.abspath(folder)
+        identity = saved_recent_identity(normalized_dir, platform)
+        if identity not in identity_set:
+            normalized_dirs.append(normalized_dir)
+            identity_set.add(identity)
+    return normalized_dirs[:limit]
+
+
+def saved_recent_dir(repository_dir: str) -> str:
+    """Return the form in which a repository is saved in the recent history: absolute, spelled as the disk spells it.
+
+    On macOS that is the letter case and Unicode form the disk keeps, whatever was typed, so the history and the
+    window title name the folder the same way; elsewhere it is the path with its links resolved, as before. Paired with
+    saved_recent_identity, it gives a repository that is not read from the history, such as the one a window shows,
+    the same key as its saved entry, so the switch menu lists it once. It touches the disk, so it is only for a path
+    known to be reachable, never for each entry of the history.
+    """
+    return on_disk_path(os.path.abspath(repository_dir))
+
+
+class PreferenceStore(QObject):
+    """Read fresh settings and synchronize individual changes to local storage."""
+
+    changed = Signal(object)
+    warning_raised = Signal(str)
+
+    def __init__(self, setting: QSettings) -> None:
+        """Use injected storage to keep application preferences independently testable."""
+        super().__init__()
+        self.setting = setting
+        self.value_by_key = dict(PREFERENCE_DEFAULT_BY_KEY)
+        self.warning = ""
+        # One diagnostic line per saved folder another system wrote, refreshed with the values: the launch writes them
+        # to the --log file, never to a window, since the folder is only kept for that other system.
+        self.foreign_dir_lines: list[str] = []
+        # Whether the file was found read-only, checked only at launch and after a refused save, never on each read: Qt
+        # tests it by opening the file for writing outside its own lock, which can make another GitPane's save fail.
+        self.unwritable = False
+        self.refresh()
+        self._check_writable()
+
+    def refresh(self) -> None:
+        """Merge external changes without discarding valid keys when another is unreadable.
+
+        Folders another system wrote in the folder lists are left out of the values and listed in ``foreign_dir_lines``;
+        reading never rewrites the file, so they stay in it.
+        """
+        self.setting.sync()
+        try:
+            self._check_status()
+        except OSError as error:
+            self._warn(str(error))
+            return
+        changed_value_by_key = {}
+        self.warning = ""
+        if self.unwritable:
+            self._warn(self._unwritable_text())
+        foreign_dir_lines = []
+        for key, default in PREFERENCE_DEFAULT_BY_KEY.items():
+            value = self.setting.value(key, default)
+            if key in DIR_LIST_LIMIT_BY_KEY:
+                for foreign_dir in foreign_saved_dirs(value):
+                    foreign_dir_lines.append(FOREIGN_DIR_LOG_TEXT.format(key=key, folder=foreign_dir))
+            try:
+                value = self._validate(key, value)
+            except (TypeError, ValueError):
+                self._warn(f"Unreadable preference ignored : {key}.")
+                continue
+            if self.value_by_key[key] != value:
+                self.value_by_key[key] = value
+                changed_value_by_key[key] = value
+        self.foreign_dir_lines = foreign_dir_lines
+        if changed_value_by_key:
+            self.changed.emit(changed_value_by_key)
+
+    def read(self, key: str, default: object = "") -> object:
+        """Import changes made by other processes before returning a preference."""
+        self.refresh()
+        value = self.value_by_key.get(key, default)
+        return list(value) if isinstance(value, list) else value
+
+    def read_saved(self, key: str) -> object:
+        """Return the value stored right now for this key, read and checked again, never this store's copy in memory.
+
+        ``read`` keeps showing the last good copy when the stored value cannot be read (written by another GitPane version,
+        say) or the storage cannot be synchronized. That is fine to show, but a value rewritten from that copy would undo
+        what another window saved meanwhile, so this raises OSError or ValueError instead.
+        """
+        self.setting.sync()
+        self._check_status()
+        value = self.setting.value(key, PREFERENCE_DEFAULT_BY_KEY.get(key))
+        try:
+            value = self._validate(key, value)
+        except TypeError as error:
+            raise ValueError(str(error)) from error
+        return list(value) if isinstance(value, list) else value
+
+    def contains_saved(self, key: str) -> bool:
+        """Distinguish absent keys from saved empty values without hiding synchronization errors."""
+        self.setting.sync()
+        try:
+            self._check_status()
+            saved = self.setting.contains(key)
+            self._check_status()
+        except OSError as error:
+            self._warn(str(error))
+            raise
+        return saved
+
+    def initialize_difftool(self, *, save: bool = True) -> str:
+        """Return the diff tool executable a comparison starts: the saved one, or else the KDiff3 detected on this system.
+
+        Settings shows that same detected KDiff3 while no diff tool is saved, so what it shows is what a comparison uses.
+        The detected executable is saved, with the arguments in effect, only when ``save`` is set, which the comparison
+        itself does: opening Settings writes nothing. A refused write is reported and the detected KDiff3 is still used.
+        """
+        self.refresh()
+        saved_filename = str(self.value_by_key["difftool_filename"])
+        if saved_filename:
+            return saved_filename
+        detected_filename = detect_kdiff3_filename(sys.platform)
+        if not detected_filename or not save:
+            return detected_filename
+        try:
+            self.update({"difftool_filename": detected_filename, "difftool_command": str(self.value_by_key["difftool_command"])})
+        except OSError as error:
+            self._warn(f"Cannot save the detected external diff tool: {error}")
+        return detected_filename
+
+    def initialize_mergetool(self, *, save_detected: bool = True) -> str:
+        """Return the merge tool executable conflict resolution uses, choosing a KDiff3 on first use.
+
+        A saved merge path, even an emptied one, or saved arguments alone are kept as they are. Otherwise a KDiff3 saved as
+        the diff tool is saved as the merge tool too, and failing that the KDiff3 detected on this system is used. That
+        detected one is saved, with the default arguments, only when ``save_detected`` is set, which the conflict action
+        does: starting GitPane or opening Settings writes nothing for it.
+        """
+        self.refresh()
+        filename = str(self.value_by_key[MERGETOOL_FILENAME_PREFERENCE_KEY])
+        try:
+            if self.contains_saved(MERGETOOL_FILENAME_PREFERENCE_KEY) or self.contains_saved(MERGETOOL_COMMAND_PREFERENCE_KEY):
+                return filename
+            candidate_filename = str(self.value_by_key["difftool_filename"])
+            if os.path.basename(candidate_filename).casefold() not in ("kdiff3", "kdiff3.exe"):
+                detected_filename = detect_kdiff3_filename(sys.platform)
+                if not detected_filename:
+                    return filename
+                if not save_detected:
+                    return detected_filename
+                candidate_filename = detected_filename
+            filename = candidate_filename
+            recipe = MergetoolRecipe(filename)
+            try:
+                recipe.validate()
+            except ValueError:
+                return filename
+            self.update({MERGETOOL_FILENAME_PREFERENCE_KEY: filename, MERGETOOL_COMMAND_PREFERENCE_KEY: recipe.command})
+        except OSError as error:
+            self._warn(f"Cannot initialize the external merge tool: {error}")
+        return filename
+
+    def editor_recipe(self) -> EditorRecipe:
+        """Read the common editor choice as one recipe after refreshing persisted values."""
+        self.refresh()
+        return EditorRecipe(str(self.value_by_key[EDITOR_PRESET_PREFERENCE_KEY]), str(self.value_by_key[EDITOR_FILENAME_PREFERENCE_KEY]), str(self.value_by_key[EDITOR_ARGUMENT_PREFERENCE_KEY]))
+
+    def editor_choice_saved(self) -> bool:
+        """Tell whether Settings holds an editor choice, which then comes before any detected editor.
+
+        One saved editor key is enough, even an empty one: the user chose it. A settings file that cannot be read counts
+        as saved, so what it holds is kept rather than replaced by a detection; the problem is already reported.
+        """
+        try:
+            for key in EDITOR_DEFAULT_BY_KEY:
+                if self.contains_saved(key):
+                    return True
+        except OSError:
+            return True
+        return False
+
+    def initialize_editor(self, *, platform: str = EDITOR_PLATFORM, search_path: str = EDITOR_INITIAL_PATH, repository_dirs: tuple[str, ...] = (),
+                          flatpak_dirs: tuple[str, ...] | None = None, system_editor_id: str = "") -> EditorRecipe:
+        """Answer the saved editor choice, or else the editor detected on this system, which is used as it is and never saved.
+
+        Settings shows the detected editor and Show in text editor opens it without a Save; only the user's Save writes
+        an editor choice. ``system_editor_id`` is the editor the system names for plain text, read elsewhere and off the
+        window's thread; it only steers the detection and is never saved here either. Without ``flatpak_dirs``, the
+        detection looks in the session's Flatpak installations.
+        """
+        previous = self.editor_recipe()
+        try:
+            if self.editor_choice_saved():
+                return previous
+            return detect_editor_recipe(platform=platform, search_path=search_path, repository_dirs=repository_dirs, flatpak_dirs=flatpak_dirs, system_editor_id=system_editor_id)
+        except OSError as error:
+            self._warn(f"Cannot initialize the external editor: {error}")
+            return previous
+
+    def update(self, changed_value_by_key: Mapping[str, object]) -> None:
+        """Write only the supplied keys and report storage failures immediately.
+
+        A folder list is written as this system's folders followed by the folders another system wrote, read again from
+        the file right before the write and each part cut to the list limit: the file may be shared with that system, so
+        none of its folders is ever dropped here. The values kept in memory and emitted hold this system's folders only.
+        """
+        self.refresh()
+        self._check_status()
+        accepted_value_by_key = {}
+        written_value_by_key = {}
+        previous_value_by_key = {}
+        for key, value in changed_value_by_key.items():
+            accepted_value = self._validate(key, value)
+            previous_value = self.setting.value(key)
+            accepted_value_by_key[key] = accepted_value
+            previous_value_by_key[key] = previous_value
+            written_value_by_key[key] = accepted_value
+            if key in DIR_LIST_LIMIT_BY_KEY:
+                written_value_by_key[key] = [*accepted_value, *foreign_saved_dirs(previous_value)[:DIR_LIST_LIMIT_BY_KEY[key]]]
+        for key, value in written_value_by_key.items():
+            self.setting.setValue(key, value)
+        self.setting.sync()
+        try:
+            self._check_status()
+        except OSError:
+            # QSettings buffers failed writes; restore them so a later sync cannot publish a rejected draft.
+            for key, previous_value in previous_value_by_key.items():
+                if previous_value is None:
+                    self.setting.remove(key)
+                else:
+                    self.setting.setValue(key, previous_value)
+            self.setting.sync()
+            self._check_writable()
+            raise
+        # A save that went through proves the file is writable again, so the read-only warning goes.
+        if self.unwritable:
+            self.unwritable = False
+            if self.warning == self._unwritable_text():
+                self.warning = ""
+        actual_value_by_key = {}
+        for key, value in accepted_value_by_key.items():
+            if self.value_by_key[key] != value:
+                self.value_by_key[key] = value
+                actual_value_by_key[key] = value
+        if actual_value_by_key:
+            self.changed.emit(actual_value_by_key)
+
+    def read_recent(self) -> list[str]:
+        """Return successful repository paths in persisted recency order."""
+        return self.read("recent_dirs", [])
+
+    def remember(self, repository_dir: str) -> None:
+        """Move a successful repository to the front without overwriting other keys; repositories another system saved stay in the file."""
+        recent_dirs = [saved_recent_dir(repository_dir), *self.read_recent()]
+        self.update({"recent_dirs": recent_dirs})
+
+    def read_clone_destinations(self) -> list[str]:
+        """Return the parent folders of the last started clones, the most recent first, as saved: none is looked at on disk."""
+        return self.read(CLONE_DESTINATION_DIRS_PREFERENCE_KEY, [])
+
+    def remember_clone_destination(self, parent_dir: str) -> None:
+        """Put the parent folder of a clone that really started at the front of the destination list, without other keys changing.
+
+        The same folder written differently moves to the front instead of being listed twice, and the oldest folder
+        beyond the limit is dropped. The folder is saved as typed, made absolute, never resolved on disk. Folders another
+        system saved stay in the file.
+        """
+        destination_dirs = [os.path.abspath(parent_dir), *self.read_clone_destinations()]
+        self.update({CLONE_DESTINATION_DIRS_PREFERENCE_KEY: destination_dirs})
+
+    def forget(self, repository_dirs: list[str]) -> None:
+        """Remove these repositories from the recent history, for example folders that no longer exist.
+
+        Only the saved list changes, in one write: the folders themselves are never touched. The paths are compared as
+        saved, never resolved on disk, since they usually come from the history itself and name folders that may be
+        unreachable. Nothing is emitted when none of them is in the history, and a storage refusal raises OSError with
+        the previous list kept. Repositories another system saved are never removed from the file.
+        """
+        forgotten_identity_set: set[str] = set()
+        for repository_dir in repository_dirs:
+            forgotten_identity_set.add(saved_recent_identity(repository_dir))
+        kept_dirs = []
+        for recent_dir in self.read_recent():
+            if saved_recent_identity(recent_dir) not in forgotten_identity_set:
+                kept_dirs.append(recent_dir)
+        self.update({"recent_dirs": kept_dirs})
+
+    def _validate(self, key: str, value: object) -> object:
+        """Reject malformed values per key and normalize only folder lists.
+
+        The recent history and the clone destinations are normalized as text, never resolved on disk: every read of any
+        preference validates them, and an unreachable network folder in them would freeze the window each time.
+        ``remember`` resolves the one path it saves, so the saved history entries are already resolved.
+        """
+        if key not in PREFERENCE_DEFAULT_BY_KEY:
+            raise ValueError(f"Unknown preference : {key}")
+        if key == AUTHENTICATION_PREFERENCE_KEY:
+            from gitpane.account.authentication import validate_selection_json
+            return validate_selection_json(value)
+        if key == ACCOUNT_SIGN_IN_METHOD_PREFERENCE_KEY:
+            from gitpane.account.authentication import validate_sign_in_method_json
+            return validate_sign_in_method_json(value)
+        if key == PUSH_TRACKING_PREFERENCE_KEY:
+            from gitpane.transport.push_tracking import validate_push_tracking_json
+            return validate_push_tracking_json(value)
+        if key == FETCH_DEFAULT_PREFERENCE_KEY:
+            # Only the saved word is accepted, never a member: Qt would write an object to the file in a form no other
+            # system or GitPane version can read.
+            if isinstance(value, str):
+                try:
+                    FetchMode(value)
+                    return value
+                except ValueError:
+                    pass
+            raise ValueError("Choose Fetch or Fetch and prune all as the default.")
+        if key in STAGING_PROPORTION_BY_KEY:
+            if not isinstance(value, (list, tuple)) or len(value) != len(STAGING_PROPORTION_BY_KEY[key]):
+                raise TypeError(f"Unreadable preference : {key}")
+            sizes: list[int] = []
+            for size in value:
+                # INI storage reads each list item back as text after a fresh process opens the file.
+                if isinstance(size, str) and size.isdigit():
+                    size = int(size)
+                if type(size) is not int or size <= 0:
+                    raise ValueError(f"Unreadable preference : {key}")
+                sizes.append(size)
+            return sizes
+        if key in {"diff_show_entire_file", OPERATION_KEEP_OPEN_PREFERENCE_KEY, CONFLICT_PROMPT_PREFERENCE_KEY, REBASE_PROMPT_PREFERENCE_KEY} or key in STASH_DEFAULT_BY_KEY:
+            if type(value) is bool:
+                return value
+            # INI storage reads booleans as strings after a fresh process opens the file.
+            if value in ("true", "false"):
+                return value == "true"
+            raise TypeError(f"Unreadable preference : {key}")
+        if key in DIR_LIST_LIMIT_BY_KEY:
+            try:
+                return normalized_dir_list(value, DIR_LIST_LIMIT_BY_KEY[key])
+            except TypeError as error:
+                raise TypeError(f"Unreadable preference : {key}") from error
+        if not isinstance(value, str):
+            raise TypeError(f"Unreadable preference : {key}")
+        if key == MERGETOOL_COMMAND_PREFERENCE_KEY:
+            parse_mergetool_command(value, "base", "local", "remote", "merged")
+        if key in EDITOR_DEFAULT_BY_KEY and "\0" in value:
+            raise ValueError("External editor settings cannot contain a null character.")
+        if key == EDITOR_ARGUMENT_PREFERENCE_KEY:
+            build_editor_arguments(value, os.path.abspath("editor-file"))
+        return value
+
+    def _check_writable(self) -> None:
+        """Look once whether the settings file can be saved, and warn when it cannot, so a read-only file is named before a save fails.
+
+        Only called at launch and after a refused save: a readable status is required first, since a file Qt could not
+        read already has its own warning.
+        """
+        if self.setting.status() != QSettings.Status.NoError:
+            return
+        self.unwritable = not self.setting.isWritable()
+        if self.unwritable:
+            self._warn(self._unwritable_text())
+
+    def _unwritable_text(self) -> str:
+        """Say that the settings file cannot be saved, naming it."""
+        return PREFERENCE_UNWRITABLE_TEXT.format(filename=self._display_filename())
+
+    def _warn(self, warning: str) -> None:
+        """Keep the latest problem for the windows that show it when they open, and announce it to live listeners."""
+        self.warning = warning
+        self.warning_raised.emit(warning)
+
+    def _check_status(self) -> None:
+        """Raise OSError naming the settings file when Qt could not parse it or could not save it.
+
+        A file Qt could not parse stays in that state for the whole session, so every later save is refused: writing
+        would replace the file with the few keys Qt understood and lose what the user edited by hand.
+        """
+        status = self.setting.status()
+        if status == QSettings.Status.NoError:
+            return
+        if status == QSettings.Status.FormatError:
+            raise OSError(PREFERENCE_UNREADABLE_TEXT.format(filename=self._display_filename()))
+        raise OSError(self._unwritable_text())
+
+    def _display_filename(self) -> str:
+        """Return the settings file path the way the system writes it, since Qt reports it with forward slashes."""
+        return os.path.abspath(self.setting.fileName())