gitpane 1.0.0__py3-none-any.whl

gitpane/tool/git_executable.py

@@ -0,0 +1,264 @@
+"""Locate the Git installations of this machine, each executable verified before GitPane uses it."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import uuid
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, QTimer, Signal
+
+from gitpane.config import GIT_EXECUTABLE_PROBE_LIMIT_BYTES, GIT_OPEN_TIMEOUT_MS
+from gitpane.history.repository_value import RepositoryFailure, RequestIdentity
+from gitpane.process.process_runner import EXIT_CODE_CAUSE_TEMPLATE, READ_PROFILE, ProcessRequest, ProcessResult, ProcessRunner, ProcessStatus
+from gitpane.tool.git_version import NO_GIT_ANSWER, git_version_answer_line
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+def detect_git_candidates() -> list[str]:
+    """List existing Git candidates in explicit platform order without personal paths."""
+    candidate_filenames = []
+    path_filename = shutil.which("git")
+    if path_filename:
+        candidate_filenames.append(path_filename)
+    if os.name == "nt":
+        for key in ("ProgramFiles", "LOCALAPPDATA"):
+            base_dir = os.environ.get(key)
+            if base_dir:
+                for relative_dir in ("bin", "cmd"):
+                    candidate_filenames.append(os.path.join(base_dir, "Git", relative_dir, "git.exe"))
+    else:
+        candidate_filenames.extend((os.path.join(os.sep, "usr", "bin", "git"), os.path.join(os.sep, "usr", "local", "bin", "git")))
+    result_filenames = []
+    identity_set: set[str] = set()
+    for candidate_filename in candidate_filenames:
+        canonical_filename = os.path.abspath(candidate_filename)
+        identity = os.path.normcase(canonical_filename)
+        if os.path.isfile(canonical_filename) and identity not in identity_set:
+            result_filenames.append(canonical_filename)
+            identity_set.add(identity)
+    return result_filenames
+
+
+def terminal_git_filename(saved_git_filename: str) -> str:
+    """Name the Git whose installation Git Bash and the OpenSSH client are searched in, even before the startup check chose it.
+
+    At first launch the terminal registry is built before the startup check sets the Git, so the saved path is still
+    empty; detect_git_candidates() starts no process and gives the first candidate that check will take.
+    """
+    if saved_git_filename:
+        return saved_git_filename
+    candidate_filenames = detect_git_candidates()
+    if not candidate_filenames:
+        return ""
+    first_candidate_index = 0
+    return candidate_filenames[first_candidate_index]
+
+
+# Folders of a Git for Windows installation, read by the tools that look for its bundled programs.
+GIT_BINARY_DIR_BASENAME = "bin"
+GIT_SHELL_DIR_BASENAME = "usr"
+# cmd\git.exe and bin\git.exe sit one folder below the installation root, <architecture>\bin\git.exe two.
+GIT_ROOT_CLIMB_LIMIT = 2
+GIT_VERSION_ARGUMENT = "--version"
+GIT_EXECUTABLE_PROBE_OPERATION = "Verify Git executable"
+PATH_ENVIRONMENT_NAME = "PATH"
+GIT_EXEC_PATH_ARGUMENT = "--exec-path"
+GIT_TOOLS_FOLDER_PROBE_OPERATION = "Read Git tools folder"
+# Longest piece of an unexpected program output quoted in a cause, whether written to the --log file or shown in
+# Settings: a --version output without a version, or a git --exec-path answer that is not a folder.
+UNKNOWN_OUTPUT_LOG_LIMIT = 200
+# Settings shows one of these under the version of a Git it accepts. Git itself works, but the commands it hands to its
+# own helper programs (HTTPS transport, difftool, mergetool) cannot find them. Apple's Git, started through a link,
+# looks for its helpers beside the link instead of beside the real file.
+GIT_TOOLS_FOLDER_MISSING_TEMPLATE = ("Git tools folder not found: {exec_path}. HTTPS remotes, difftool and mergetool cannot work with this Git. "
+                                     "Choose the real Git executable, not a link to it.")
+GIT_TOOLS_FOLDER_UNREADABLE_TEMPLATE = "Git did not name its tools folder ({cause}). HTTPS remotes, difftool and mergetool may not work with this Git."
+NO_TOOLS_FOLDER_WARNING = ""
+UNEXPECTED_ANSWER_PREFIX = "unexpected answer "
+
+
+def parse_exec_path_answer(output: bytes, decode: Callable[[bytes], str] = os.fsdecode) -> str:
+    """Return the folder of Git's own programs named by a `git --exec-path` answer, or raise ValueError saying why it is not one.
+
+    The folder is a file name, so it is decoded as one: a folder whose name is not UTF-8 stays usable on Linux and
+    macOS, while Windows decodes file names strictly and refuses such bytes. ``decode`` lets a test take either rule
+    on any system. Only one absolute line counts as an answer.
+    """
+    try:
+        exec_path = decode(bytes(output)).rstrip("\r\n")
+    except UnicodeDecodeError as error:
+        raise ValueError(UNEXPECTED_ANSWER_PREFIX + repr(bytes(output)[:UNKNOWN_OUTPUT_LOG_LIMIT])) from error
+    if not exec_path or "\n" in exec_path or not os.path.isabs(exec_path):
+        raise ValueError(UNEXPECTED_ANSWER_PREFIX + repr(exec_path[:UNKNOWN_OUTPUT_LOG_LIMIT]))
+    return os.path.normpath(exec_path)
+
+
+def tools_folder_warning(exec_path: str, isdir: Callable[[str], bool] = os.path.isdir) -> str:
+    """Return the warning for a Git whose tools folder does not exist, or nothing when the folder is there.
+
+    Nothing is worked around: the warning only tells the user which Git to choose instead.
+    """
+    if isdir(exec_path):
+        return NO_TOOLS_FOLDER_WARNING
+    return GIT_TOOLS_FOLDER_MISSING_TEMPLATE.format(exec_path=exec_path)
+
+
+def _tools_folder_answer_warning(result: ProcessResult, output: bytes) -> str:
+    """Turn the outcome of a `git --exec-path` read into the warning Settings shows, or nothing when the folder exists.
+
+    An answer that cannot be read is reported with its cause instead of being kept quiet.
+    """
+    cause = ""
+    if result.status != ProcessStatus.SUCCESS:
+        cause = result.cause or result.status.value
+    elif result.return_code != 0:
+        cause = EXIT_CODE_CAUSE_TEMPLATE.format(return_code=result.return_code)
+    if not cause:
+        try:
+            return tools_folder_warning(parse_exec_path_answer(output))
+        except ValueError as error:
+            cause = str(error)
+    return GIT_TOOLS_FOLDER_UNREADABLE_TEMPLATE.format(cause=cause)
+
+
+@dataclass
+class GitExecutableCheck:
+    """Follow one validation in progress: the file it is about and the version it reported."""
+
+    identity: RequestIdentity
+    git_filename: str
+    version: str = ""
+    # Only Settings asks for the tools folder: the startup and launch checks stay a single process.
+    read_tools_folder: bool = False
+
+
+def _probe_version(result: ProcessResult, output: bytes) -> str:
+    """Return the version line a probe answered, or nothing when its outcome or its answer cannot be trusted."""
+    if result.status != ProcessStatus.SUCCESS or result.return_code != 0:
+        return NO_GIT_ANSWER
+    return git_version_answer_line(output)
+
+
+class GitExecutableValidator(QObject):
+    """Validate a draft executable asynchronously with the shared process limits.
+
+    A validation is one bounded `--version` read of the very file the user chose: its answer alone decides whether
+    that Git is usable, and the chosen file is the one every later command launches. A Settings validation then reads
+    `--exec-path` once the version is accepted, and publishes on ``tools_folder_checked`` the warning for a tools
+    folder that does not exist, just before ``validated``; that warning never refuses the Git.
+    """
+
+    validated = Signal(object, str, str, object)
+    tools_folder_checked = Signal(object, str, str)
+
+    def __init__(self, runner: ProcessRunner) -> None:
+        """Inject the runner so validation shares cancellation and shutdown behavior."""
+        super().__init__(runner)
+        self.runner = runner
+        self.check_by_id: dict[str, GitExecutableCheck] = {}
+        self.output_by_id: dict[str, bytearray] = {}
+        runner.stdout_chunk.connect(self._receive_chunk)
+        runner.finished.connect(self._receive_result)
+
+    def validate(self, git_filename: str, identity: RequestIdentity, *, read_tools_folder: bool = False) -> None:
+        """Check a concrete absolute executable and request its version without a shell; ``read_tools_folder`` also checks the folder of its helper programs."""
+        self.cancel(identity.session_id)
+        cause = ""
+        if not git_filename.strip():
+            cause = "The Git path is empty"
+        elif not os.path.isabs(git_filename):
+            cause = "Choose an absolute path to Git"
+        elif not os.path.isfile(git_filename):
+            cause = "The file does not exist or is not an executable file"
+        elif not os.access(git_filename, os.X_OK):
+            cause = "The file is not executable"
+        if cause:
+            failure = RepositoryFailure("This Git executable cannot be used", "", git_filename, [GIT_VERSION_ARGUMENT], cause)
+            QTimer.singleShot(0, lambda: self.validated.emit(identity, git_filename, "", failure))
+            return
+        git_filename = os.path.abspath(git_filename)
+        check = GitExecutableCheck(identity, git_filename, read_tools_folder=read_tools_folder)
+        self._start_probe(check, GIT_VERSION_ARGUMENT, GIT_EXECUTABLE_PROBE_OPERATION)
+
+    def cancel(self, session_id: str) -> None:
+        """Forget the previous draft before any late process result can validate it.
+
+        What this session was checking is dropped before the runner is asked to cancel, so the outcomes it publishes
+        right away, and the late ones too, have nothing left to act on.
+        """
+        for request_id, check in tuple(self.check_by_id.items()):
+            if check.identity.session_id == session_id:
+                self.check_by_id.pop(request_id, None)
+                self.output_by_id.pop(request_id, None)
+        self.runner.cancel_session(session_id)
+
+    def _start_probe(self, check: GitExecutableCheck, argument: str, operation: str) -> None:
+        """Launch one bounded read of the very file being checked, from its own folder and with GitPane's usual environment."""
+        request_id = uuid.uuid4().hex
+        self.check_by_id[request_id] = check
+        self.output_by_id[request_id] = bytearray()
+        self.runner.start(ProcessRequest(request_id, check.git_filename, [argument], os.path.dirname(check.git_filename), GIT_OPEN_TIMEOUT_MS,
+                                         check.identity.session_id, stdout_limit_bytes=GIT_EXECUTABLE_PROBE_LIMIT_BYTES, operation=operation,
+                                         profile=READ_PROFILE))
+
+    def _finish_check(self, check: GitExecutableCheck, failure: RepositoryFailure | None = None) -> None:
+        """Publish the outcome of one validation: the checked file with its version, or the reason it cannot be used."""
+        self.validated.emit(check.identity, check.git_filename, check.version if failure is None else "", failure)
+
+    def _receive_chunk(self, request: ProcessRequest, output: bytes) -> None:
+        if request.request_id in self.output_by_id:
+            self.output_by_id[request.request_id].extend(output)
+
+    def _receive_result(self, result: ProcessResult) -> None:
+        """End the validation this outcome belongs to, unless it was cancelled or replaced meanwhile."""
+        check = self.check_by_id.pop(result.request.request_id, None)
+        output = self.output_by_id.pop(result.request.request_id, bytearray())
+        if check is None or result.status == ProcessStatus.CANCELLED:
+            return
+        if check.version:
+            self._receive_tools_folder(check, result, output)
+            return
+        self._receive_launcher_version(check, result, output)
+
+    def _receive_launcher_version(self, check: GitExecutableCheck, result: ProcessResult, output: bytes) -> None:
+        """Decide whether the chosen Git is usable: a single clean Git version line accepts it, anything else refuses it."""
+        version = _probe_version(result, output)
+        if not version:
+            cause = result.cause or "The executable did not return a Git version"
+            self._finish_check(check, RepositoryFailure("This Git executable cannot be used", result.request.working_dir, result.request.program_filename,
+                                                        result.request.arguments, cause, result.stderr, result.return_code))
+            return
+        check.version = version
+        if check.read_tools_folder:
+            self._start_probe(check, GIT_EXEC_PATH_ARGUMENT, GIT_TOOLS_FOLDER_PROBE_OPERATION)
+            return
+        self._finish_check(check)
+
+    def _receive_tools_folder(self, check: GitExecutableCheck, result: ProcessResult, output: bytes) -> None:
+        """Publish what the `--exec-path` read says about the helper programs, then the accepted Git it belongs to."""
+        self.tools_folder_checked.emit(check.identity, check.git_filename, _tools_folder_answer_warning(result, output))
+        self._finish_check(check)
+
+
+def git_root_dirs(git_filename: str) -> list[str]:
+    """List the folders that may be the root of the Git installation GitPane runs, nearest first.
+
+    Git Bash and the OpenSSH client shipped with Git for Windows are both searched from these folders. No
+    architecture folder name is written here: the root is simply one or two folders above git.exe.
+    """
+    if not git_filename:
+        return []
+    root_dirs = []
+    current_dir = os.path.dirname(os.path.abspath(git_filename))
+    for _level in range(GIT_ROOT_CLIMB_LIMIT):
+        parent_dir = os.path.dirname(current_dir)
+        if parent_dir == current_dir:
+            break
+        root_dirs.append(parent_dir)
+        current_dir = parent_dir
+    return root_dirs

gitpane/tool/git_version.py

@@ -0,0 +1,62 @@
+"""Read the version of a Git from what its `git --version` command answers.
+
+The answer gives the version line, by the one rule Settings and Remove from history share, and that line gives the
+release numbers.
+"""
+
+from __future__ import annotations
+
+import re
+
+GIT_VERSION_PREFIX = "git version "
+NO_GIT_ANSWER = ""
+# Major and minor numbers at the start of the version text, then an optional patch number; builds append their own
+# suffix after them (".windows.2", " (Apple Git-157)"), and a Git built between two releases writes "2.45.GIT".
+GIT_VERSION_NUMBER_PATTERN = re.compile(r"(\d+)\.(\d+)(?:\.(\d+))?")
+# A Git built between two releases is built after the major.minor.0 release, so it is at least that release.
+MISSING_PATCH_NUMBER = 0
+
+
+def _probe_line(text: str) -> str:
+    """Return the single line an answer holds, or nothing when it holds none or several.
+
+    Only the trailing line ending is removed; an answer spread over several lines is not answering the question that
+    was asked.
+    """
+    text = text.removesuffix("\n").removesuffix("\r")
+    if not text or "\n" in text or "\r" in text:
+        return NO_GIT_ANSWER
+    return text
+
+
+def git_version_answer_line(output: bytes | bytearray) -> str:
+    """Return the version line of a `git --version` answer, or nothing when the answer is not one clean version line.
+
+    This is the only rule by which GitPane takes an answer for a Git version: Settings applies it to accept a Git, and
+    Remove from history to read the version of its Git again, so the two never disagree on the same answer. The answer
+    must be a single line of valid UTF-8 that starts with the version prefix; what follows the prefix is not judged here.
+    """
+    try:
+        line = _probe_line(bytes(output).decode("utf-8"))
+    except UnicodeDecodeError:
+        return NO_GIT_ANSWER
+    if not line.startswith(GIT_VERSION_PREFIX):
+        return NO_GIT_ANSWER
+    return line
+
+
+def git_version_numbers(version_line: str) -> tuple[int, int, int] | None:
+    """Read major, minor and patch from a `git version …` line, a missing patch number counting as 0.
+
+    None for a line without the exact prefix or without major and minor numbers right after it.
+    """
+    line = version_line.rstrip()
+    if not line.startswith(GIT_VERSION_PREFIX):
+        return None
+    match = GIT_VERSION_NUMBER_PATTERN.match(line[len(GIT_VERSION_PREFIX):])
+    if match is None:
+        return None
+    major, minor, patch = match.groups()
+    if patch is None:
+        return int(major), int(minor), MISSING_PATCH_NUMBER
+    return int(major), int(minor), int(patch)

gitpane/tool/kdiff3.py

@@ -0,0 +1,41 @@
+"""Find the standard KDiff3 installation that external comparison shares with conflict resolution.
+
+Windows and Linux install KDiff3 at a fixed file; macOS installs it as an application bundle, whose declared program is
+offered. It lives apart from both tools so the preferences can use it without importing the comparison service.
+"""
+
+from __future__ import annotations
+
+import os
+
+from gitpane.config import KDIFF3_BUNDLE_BASENAMES_BY_PLATFORM, KDIFF3_SUGGESTED_FILENAMES_BY_PLATFORM
+from gitpane.tool.app_bundle import APPLICATION_SEARCH_DIRS, find_application
+
+
+def detect_kdiff3_filename(platform: str, search_dirs: tuple[str, ...] = APPLICATION_SEARCH_DIRS) -> str:
+    """Find the standard KDiff3 installation of ``platform`` without starting it or saving preferences.
+
+    The fixed files of the system come first, and the first executable one is returned. Then the KDiff3 bundles the
+    system lists are searched in ``search_dirs``, in that order, and the program the first readable one declares is
+    returned. A system with neither gets an empty result. The system and the folders are received rather than read here
+    so the three systems can be tested from any of them, without ever reading the real applications folders.
+    """
+    for candidate_filename in KDIFF3_SUGGESTED_FILENAMES_BY_PLATFORM.get(platform, ()):
+        if os.path.isfile(candidate_filename) and os.access(candidate_filename, os.X_OK):
+            return candidate_filename
+    bundle_basenames = KDIFF3_BUNDLE_BASENAMES_BY_PLATFORM.get(platform, ())
+    if not bundle_basenames:
+        return ""
+    bundle = find_application(bundle_basenames, search_dirs)
+    if bundle is None:
+        return ""
+    return bundle.executable_filename
+
+
+def tool_program_usable(program_filename: str) -> bool:
+    """Tell whether a diff or merge tool field leads to a program GitPane can start: an absolute name of an executable file.
+
+    Both tool recipes refuse anything else, and Settings shows how to install KDiff3 under a field that fails it.
+    """
+    return os.path.isabs(program_filename) and os.path.isfile(program_filename) and os.access(program_filename, os.X_OK)
+

gitpane/tool/kdiff3_install.py

@@ -0,0 +1,162 @@
+"""Say how to install KDiff3 on a system.
+
+The line of each system comes from GitPane's own tables, never from anything read on the machine, so a text the user
+copies into a terminal can only be one GitPane wrote. Under Linux, the distribution family and the precise distribution
+read from os-release only pick members of ``Kdiff3InstallText``, and a family never receives the command of another
+family's package manager: a command that does not exist on the user's system does not work and teaches a wrong command.
+"""
+
+from __future__ import annotations
+
+from enum import Enum, unique
+
+from gitpane.config import KDIFF3_INSTALL_LINE_BY_PLATFORM, LINUX_PLATFORM
+from gitpane.system.linux_distribution import DistributionFamily, DistributionRelease
+
+KDIFF3_RUN_PREFIX = "To install KDiff3, run:"
+DNF_INSTALL_COMMAND = "sudo dnf install kdiff3"
+# Fedora's official address of the EPEL release package; ``$(rpm -E %rhel)`` is left for the user's shell to expand,
+# so GitPane never reads the major version of the system.
+EPEL_RELEASE_COMMAND = "sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-$(rpm -E %rhel).noarch.rpm"
+# Joins the lines of a distribution that needs several commands, so that each can be copied alone.
+INSTALL_LINE_SEPARATOR = "\n"
+
+
+@unique
+class Kdiff3InstallText(Enum):
+    """A line of the KDiff3 install help under Linux, as Settings and a refused comparison or merge show it.
+
+    ``@unique`` because two members with the same text would silently become one member under two names.
+    """
+
+    DEBIAN = KDIFF3_RUN_PREFIX + " sudo apt install kdiff3"
+    """The line of the Debian family, Ubuntu and its derivatives included."""
+    FEDORA = KDIFF3_RUN_PREFIX + " " + DNF_INSTALL_COMMAND
+    """The line of the Fedora family."""
+    SUSE = KDIFF3_RUN_PREFIX + " sudo zypper install kdiff3"
+    """The line of the SUSE family, openSUSE and SUSE Linux Enterprise alike."""
+    ARCH = KDIFF3_RUN_PREFIX + " sudo pacman -S kdiff3"
+    """The line of the Arch family."""
+    GENTOO = KDIFF3_RUN_PREFIX + " sudo emerge --ask kde-misc/kdiff3"
+    """The line of the Gentoo family, which builds KDiff3 from its category of KDE tools."""
+    VOID = KDIFF3_RUN_PREFIX + " sudo xbps-install -S kdiff3"
+    """The line of Void Linux, both variants."""
+    ALPINE = "To install KDiff3, enable the community repository in /etc/apk/repositories, then run as root: apk add kdiff3"
+    """The line of Alpine, whose KDiff3 package lives in the community repository and which may have no sudo."""
+    SOLUS = KDIFF3_RUN_PREFIX + " sudo eopkg install kdiff3"
+    """The line of Solus."""
+    NIXOS = ("To install KDiff3, add kdiff3 to environment.systemPackages in /etc/nixos/configuration.nix, run sudo nixos-rebuild switch, "
+             "then choose /run/current-system/sw/bin/kdiff3 with Browse…")
+    """The line of NixOS, where KDiff3 is declared in the system configuration and never lands at the path GitPane looks at first."""
+    UNKNOWN_HOW = "You need to install KDiff3. GitPane does not know how to do it for your distribution: ask your favorite AI."
+    """The line of a distribution GitPane has no way to install KDiff3 on: Guix, which has no kdiff3 package, and any distribution GitPane does not know.
+
+    It names no package manager and no address, so it never teaches a command that does not exist on the user's system.
+    """
+    RUN_INTRO = KDIFF3_RUN_PREFIX
+    """Introduces the commands of a distribution that needs several, each on its own line."""
+    EPEL_RELEASE = EPEL_RELEASE_COMMAND
+    """Installs EPEL, the repository of Fedora packages rebuilt for the RHEL family, where KDiff3 comes from there."""
+    CRB_ENABLE = "sudo crb enable"
+    """Turns on the CRB repository through the script epel-release installs on Rocky Linux and AlmaLinux."""
+    RHEL_CODEREADY = "sudo subscription-manager repos --enable codeready-builder-for-rhel-$(rpm -E %rhel)-$(arch)-rpms"
+    """Turns on Red Hat's CodeReady Builder repository, which EPEL packages need, through the subscription."""
+    CENTOS_CRB = "sudo dnf config-manager --set-enabled crb"
+    """Turns on the CRB repository of CentOS Stream, which EPEL packages need."""
+    ORACLE_EPEL = "sudo dnf install oracle-epel-release-el$(rpm -E %rhel)"
+    """Installs EPEL from Oracle's own repositories."""
+    ORACLE_CODEREADY = "sudo dnf config-manager --set-enabled ol$(rpm -E %rhel)_codeready_builder"
+    """Turns on Oracle's CodeReady Builder repository, which EPEL packages need."""
+    DNF_INSTALL = DNF_INSTALL_COMMAND
+    """Installs KDiff3 through dnf, once the repositories before it are turned on."""
+    SEE_SETTINGS_TOOLS = "To install KDiff3, see the commands in Settings › Tools."
+    """Replaces several install commands where only one line can be shown, as in the status bar of the repository window."""
+
+
+# Rocky Linux and AlmaLinux get their CRB through the script of epel-release, so EPEL comes first there; this order is
+# also given to any RHEL derivative without a row of its own.
+ROCKY_OR_ALMA_INSTALL = (Kdiff3InstallText.RUN_INTRO, Kdiff3InstallText.EPEL_RELEASE, Kdiff3InstallText.CRB_ENABLE, Kdiff3InstallText.DNF_INSTALL)
+
+# Keyed by the family read from os-release; the value is text of Settings and of the refusal messages, another layer
+# than the family, like the install table of the Git Credential Manager. A family missing from the table is told GitPane
+# does not know how.
+LINUX_KDIFF3_INSTALL_BY_FAMILY: dict[DistributionFamily, tuple[Kdiff3InstallText, ...]] = {
+    DistributionFamily.DEBIAN: (Kdiff3InstallText.DEBIAN,),
+    # Kept for the whole family by choice, although dnf cannot install into the read-only system image of Kinoite,
+    # Silverblue or Bazzite: telling them apart would mean reading VARIANT_ID, and those users know their own way
+    # (rpm-ostree, a toolbox), while any other line would name a tool the rest of the family does not use.
+    DistributionFamily.FEDORA: (Kdiff3InstallText.FEDORA,),
+    DistributionFamily.RHEL: ROCKY_OR_ALMA_INSTALL,
+    # One line for SUSE Linux Enterprise too, where kdiff3 only comes from SUSE Package Hub once it is turned on.
+    DistributionFamily.SUSE: (Kdiff3InstallText.SUSE,),
+    DistributionFamily.ARCH: (Kdiff3InstallText.ARCH,),
+    DistributionFamily.GENTOO: (Kdiff3InstallText.GENTOO,),
+    DistributionFamily.VOID: (Kdiff3InstallText.VOID,),
+    DistributionFamily.ALPINE: (Kdiff3InstallText.ALPINE,),
+    DistributionFamily.NIXOS: (Kdiff3InstallText.NIXOS,),
+    DistributionFamily.SOLUS: (Kdiff3InstallText.SOLUS,),
+    DistributionFamily.UNKNOWN: (Kdiff3InstallText.UNKNOWN_HOW,),
+}
+# Keyed by the precise distribution read from os-release's exact ID, and read before the family table: these
+# distributions install differently from the rest of their family.
+LINUX_KDIFF3_INSTALL_BY_RELEASE: dict[DistributionRelease, tuple[Kdiff3InstallText, ...]] = {
+    DistributionRelease.RHEL: (Kdiff3InstallText.RUN_INTRO, Kdiff3InstallText.RHEL_CODEREADY, Kdiff3InstallText.EPEL_RELEASE, Kdiff3InstallText.DNF_INSTALL),
+    DistributionRelease.CENTOS_STREAM: (Kdiff3InstallText.RUN_INTRO, Kdiff3InstallText.CENTOS_CRB, Kdiff3InstallText.EPEL_RELEASE, Kdiff3InstallText.DNF_INSTALL),
+    DistributionRelease.ROCKY_OR_ALMA: ROCKY_OR_ALMA_INSTALL,
+    DistributionRelease.ORACLE_LINUX: (Kdiff3InstallText.RUN_INTRO, Kdiff3InstallText.ORACLE_EPEL, Kdiff3InstallText.ORACLE_CODEREADY, Kdiff3InstallText.DNF_INSTALL),
+    # Guix shares the NixOS family but has no kdiff3 package and no nixos-rebuild.
+    DistributionRelease.GUIX: (Kdiff3InstallText.UNKNOWN_HOW,),
+}
+
+
+def linux_kdiff3_install_lines(family: DistributionFamily, release: DistributionRelease) -> tuple[str, ...]:
+    """Write the KDiff3 install lines of a Linux distribution: its own when it has a row, otherwise its family's, otherwise the line saying GitPane does not know how.
+
+    The family and the distribution are received rather than read here, so the lines of each can be tested from any
+    system.
+    """
+    install_texts = LINUX_KDIFF3_INSTALL_BY_RELEASE.get(release)
+    if install_texts is None:
+        install_texts = LINUX_KDIFF3_INSTALL_BY_FAMILY.get(family, (Kdiff3InstallText.UNKNOWN_HOW,))
+    lines = []
+    for install_text in install_texts:
+        lines.append(install_text.value)
+    return tuple(lines)
+
+
+def kdiff3_install_line(platform: str, family: DistributionFamily = DistributionFamily.UNKNOWN, release: DistributionRelease = DistributionRelease.OTHER) -> str:
+    """Say how to install KDiff3 on ``platform``, or return an empty text for a system that has no line.
+
+    Under Linux the text depends on the distribution ``family`` and ``release``; elsewhere they are not read. The system,
+    the family and the distribution are received rather than read here, so the line of each can be tested from any system.
+    """
+    if platform == LINUX_PLATFORM:
+        return INSTALL_LINE_SEPARATOR.join(linux_kdiff3_install_lines(family, release))
+    return KDIFF3_INSTALL_LINE_BY_PLATFORM.get(platform, "")
+
+
+def with_kdiff3_install_line(text: str, platform: str, family: DistributionFamily = DistributionFamily.UNKNOWN, release: DistributionRelease = DistributionRelease.OTHER) -> str:
+    """Follow a message about a missing comparison or merge tool with the way to install KDiff3 on ``platform``, when the system has one.
+
+    A single line follows the message after a space; several lines start on a line of their own, so each command can be
+    copied alone.
+    """
+    install_line = kdiff3_install_line(platform, family, release)
+    if not install_line:
+        return text
+    if INSTALL_LINE_SEPARATOR in install_line:
+        return text + INSTALL_LINE_SEPARATOR + install_line
+    return text + " " + install_line
+
+
+def status_bar_refusal_text(cause: str) -> str:
+    """Fit a refusal into the single line of a status bar: several install commands become a pointer to Settings › Tools.
+
+    The status bar paints one line and cannot be copied from, so commands meant to be copied one by one would only
+    show as a cut line there; Settings lists them in a selectable label. A cause with a single line is kept as it is.
+    """
+    if INSTALL_LINE_SEPARATOR not in cause:
+        return cause
+    first_line_index = 0
+    first_line = cause.split(INSTALL_LINE_SEPARATOR)[first_line_index]
+    return first_line + " " + Kdiff3InstallText.SEE_SETTINGS_TOOLS.value

gitpane/tool/launch_services_text_editor.py

@@ -0,0 +1,104 @@
+"""Name the application macOS opens for a plain text file, read from the user's LaunchServices handlers only.
+
+LaunchServices keeps the default applications the user chose (Finder's Get Info, "Open with", "Change All…") in one
+property list of the user's preferences: a list of handlers, each naming a content type or a URL scheme, with the
+identifier of the application that opens it for a role, written in lower case. Only the handler of plain text
+(``public.plain-text``) is looked at, the type of the default text editor that ``open -t`` opens. When no handler names
+plain text, or the list cannot be read, macOS opens plain text with TextEdit, so TextEdit's identifier is answered. The
+identifier found only picks one of GitPane's known editor presets; nothing of the application it names is read or
+started, and no process is started to read it.
+
+The rule reads only the data, the home folder and the file reader it is given, so it can be checked from any system
+without touching the real preferences; only the last function reads the session's own preferences.
+"""
+
+from __future__ import annotations
+
+import os
+import plistlib
+from typing import TYPE_CHECKING
+
+from gitpane.tool.app_bundle import PLIST_READ_ERRORS, TEXTEDIT_BUNDLE_IDENTIFIER
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+# Where LaunchServices keeps the user's default applications, under the home folder.
+LAUNCH_SERVICES_HANDLER_PARTS = ("Library", "Preferences", "com.apple.LaunchServices", "com.apple.launchservices.secure.plist")
+HANDLER_LIST_KEY = "LSHandlers"
+HANDLER_CONTENT_TYPE_KEY = "LSHandlerContentType"
+PLAIN_TEXT_CONTENT_TYPE = "public.plain-text"
+# The roles a handler may name an application for, the editor's first: the editor role is the closer answer to "which
+# application edits plain text", the role for all uses is what Finder's "Change All…" writes. The viewer role is no
+# editor and is not read.
+EDITOR_HANDLER_ROLE_KEYS = ("LSHandlerRoleEditor", "LSHandlerRoleAll")
+# The application macOS opens plain text with when the user chose none.
+SYSTEM_DEFAULT_TEXT_EDITOR_IDENTIFIER = TEXTEDIT_BUNDLE_IDENTIFIER
+
+
+def launch_services_handler_filename(home_dir: str) -> str:
+    """Answer the path of the property list where LaunchServices keeps the user's default applications."""
+    return os.path.join(home_dir, *LAUNCH_SERVICES_HANDLER_PARTS)
+
+
+def _handler_application_identifier(handler: dict[object, object]) -> str:
+    """Answer the application one plain text handler names for editing, or an empty text when it names none."""
+    for role_key in EDITOR_HANDLER_ROLE_KEYS:
+        identifier = handler.get(role_key)
+        if isinstance(identifier, str) and identifier.strip():
+            return identifier.strip()
+    return ""
+
+
+def plain_text_handler_identifier(preference_data: object) -> str:
+    """Answer the identifier of the application the user's handlers name for plain text, or an empty text when none does.
+
+    ``preference_data`` is the property list as plistlib reads it. The first handler of plain text that names an
+    application for editing decides, in the order of the list; the content type is compared without case, as macOS
+    compares type identifiers. Data of another shape names nothing instead of raising.
+    """
+    if not isinstance(preference_data, dict):
+        return ""
+    handlers = preference_data.get(HANDLER_LIST_KEY)
+    if not isinstance(handlers, list):
+        return ""
+    for handler in handlers:
+        if not isinstance(handler, dict):
+            continue
+        content_type = handler.get(HANDLER_CONTENT_TYPE_KEY)
+        if not isinstance(content_type, str) or content_type.casefold() != PLAIN_TEXT_CONTENT_TYPE:
+            continue
+        identifier = _handler_application_identifier(handler)
+        if identifier:
+            return identifier
+    return ""
+
+
+def launch_services_text_editor_id(home_dir: str, read_property_list: Callable[[str], object | None]) -> str:
+    """Answer the identifier of the application macOS opens plain text with for this user.
+
+    The user's own choice when the handlers name one, otherwise TextEdit's, which is what macOS itself opens then.
+    ``read_property_list`` answers None for a file it cannot read, which counts as no choice.
+    """
+    identifier = plain_text_handler_identifier(read_property_list(launch_services_handler_filename(home_dir)))
+    if identifier:
+        return identifier
+    return SYSTEM_DEFAULT_TEXT_EDITOR_IDENTIFIER
+
+
+def read_property_list(filename: str) -> object | None:
+    """Read an XML or binary property list, or answer None when it is missing, unreadable or broken."""
+    try:
+        with open(filename, "rb") as stream:
+            return plistlib.load(stream)
+    except PLIST_READ_ERRORS:
+        return None
+
+
+def session_launch_services_text_editor_id() -> str:
+    """Answer the application macOS opens plain text with for this session's user, read from the real preferences.
+
+    The home folder may sit on a network share that stops answering: call it on a thread of its own only, never on the
+    window's thread.
+    """
+    return launch_services_text_editor_id(os.path.expanduser("~"), read_property_list)