gitpane 1.0.0__py3-none-any.whl

gitpane/account/credential_manager.py

@@ -0,0 +1,480 @@
+"""Locate a usable official Git Credential Manager on this machine, with the reason each refused candidate is refused.
+
+Everything here is blocking and free of Qt objects: the search starts short processes, so it runs away from the
+window's thread.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import tempfile
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from gitpane.account.credential_manager_install import distribution_gcm_install_lines
+from gitpane.account.ssh import GIT_FOR_WINDOWS_SOURCE_TEXT, PATH_SOURCE_TEXT, absolute_executable_available
+from gitpane.config import (
+    CREDENTIAL_MANAGER_PLATFORM_BY_NAME,
+    GCM_ENVIRONMENT_PREFIX,
+    GCM_MINIMUM_VERSION,
+    GCM_REQUIRED_TEXT,
+    GCM_VERSION_TIMEOUT_MS,
+    GIT_OPEN_TIMEOUT_MS,
+    MILLISECONDS_PER_SECOND,
+    WINDOWS_PLATFORM,
+)
+from gitpane.system.linux_distribution import DistributionFamily
+from gitpane.system.network_folder import network_directory
+from gitpane.tool.git_executable import GIT_BINARY_DIR_BASENAME, GIT_EXEC_PATH_ARGUMENT, PATH_ENVIRONMENT_NAME, UNKNOWN_OUTPUT_LOG_LIMIT, parse_exec_path_answer
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from gitpane.account.credential_manager_install import GcmArchiveArchitecture
+    from gitpane.config import CredentialManagerPlatform
+
+GCM_VERSION_ARGUMENT = "--version"
+GIT_EXEC_PATH_ENVIRONMENT_NAME = "GIT_EXEC_PATH"
+GCM_VERSION_PATTERN = re.compile(r"(\d+)\.(\d+)\.(\d+)")
+STANDARD_LOCATION_SOURCE_TEXT = "Standard location"
+# Result written to --log for a candidate that is listed but never started.
+NETWORK_SHARE_SKIP_TEXT = "network share"
+OTHER_TOOLCHAIN_SKIP_TEXT = "another toolchain folder of the Git in use"
+
+
+class CredentialManagerProblem(Enum):
+    """Say why no usable Git Credential Manager was found; NONE when the detection names a usable one."""
+
+    NONE = "none"
+    MISSING = "missing"
+    TOO_OLD = "too_old"
+    UNREADABLE_VERSION = "unreadable_version"
+    NOT_STARTING = "not_starting"
+    UNSUPPORTED_PLATFORM = "unsupported_platform"
+
+
+# When no candidate is usable, the reason kept is the one that tells the user best what to do: an old version names
+# what to update, an unreadable version or a program that does not start says the installation itself is wrong, and
+# absence comes last.
+MOST_USEFUL_FIRST_REFUSAL_PROBLEMS = (CredentialManagerProblem.TOO_OLD, CredentialManagerProblem.UNREADABLE_VERSION,
+                                      CredentialManagerProblem.NOT_STARTING, CredentialManagerProblem.MISSING)
+
+# Each refusal has one constant sentence, defined here only: the refused operation shows it in red, and the window that
+# explains how to install the credential manager recognises it. Each sentence starts with words of its own, so a reader
+# of a failure cause can tell them apart line by line. The path of the refused credential manager ends the sentence when
+# there is one, so the user knows which file to update or remove.
+CREDENTIAL_MANAGER_MISSING_TEXT = "Git credential manager not found."
+CREDENTIAL_MANAGER_TOO_OLD_TEXT = "Git credential manager {version} is too old, {minimum} or later is required: {filename}"
+CREDENTIAL_MANAGER_UNREADABLE_VERSION_TEXT = "Could not read the Git credential manager version: {filename}"
+CREDENTIAL_MANAGER_NOT_STARTING_TEXT = "Git credential manager did not start: {filename}"
+CREDENTIAL_MANAGER_UNSUPPORTED_SYSTEM_TEXT = "Git credential manager is not supported on this system: {platform}"
+REFUSAL_TEXT_BY_PROBLEM: dict[CredentialManagerProblem, str] = {
+    CredentialManagerProblem.MISSING: CREDENTIAL_MANAGER_MISSING_TEXT,
+    CredentialManagerProblem.TOO_OLD: CREDENTIAL_MANAGER_TOO_OLD_TEXT,
+    CredentialManagerProblem.UNREADABLE_VERSION: CREDENTIAL_MANAGER_UNREADABLE_VERSION_TEXT,
+    CredentialManagerProblem.NOT_STARTING: CREDENTIAL_MANAGER_NOT_STARTING_TEXT,
+    CredentialManagerProblem.UNSUPPORTED_PLATFORM: CREDENTIAL_MANAGER_UNSUPPORTED_SYSTEM_TEXT,
+}
+# The refusals that leave the user something to install, so they open the window explaining how. A system missing from
+# the platform table has no official credential manager to offer, so its refusal only shows its red line.
+INSTALL_WINDOW_PROBLEM_SET: frozenset[CredentialManagerProblem] = frozenset({CredentialManagerProblem.MISSING, CredentialManagerProblem.TOO_OLD,
+                                                                            CredentialManagerProblem.UNREADABLE_VERSION, CredentialManagerProblem.NOT_STARTING})
+# First line of the install window for a credential manager that is too old. The path stays in the red line of the
+# refused operation and in Settings, so this line names only the versions.
+CREDENTIAL_MANAGER_TOO_OLD_HEADER_TEXT = "Your Git credential manager ({version}) is too old, {minimum} or later is required"
+# Short line of the install window when a new search finds the same refusal the window already explains, a missing
+# credential manager or the same version still too old alike.
+CREDENTIAL_MANAGER_STILL_REFUSED_TEXT = "Still not good. (what did you expect? 😂)"
+# Read-only line of Settings: the version and path of the credential manager in use, or its absence.
+CREDENTIAL_MANAGER_FOUND_TEXT = "{version} — {filename}"
+CREDENTIAL_MANAGER_NOT_FOUND_TEXT = "not found"
+
+
+@dataclass(frozen=True)
+class CredentialManagerDetection:
+    """Name the credential manager to use with the version read and where it was found, or say why none is usable.
+
+    ``exec_path`` is the folder of the Git in use; every direct start of the credential manager must receive it so the
+    credential manager finds Git without the PATH. It is empty when Git did not tell it.
+    """
+
+    filename: str = ""
+    version: str = ""
+    source: str = ""
+    problem: CredentialManagerProblem = CredentialManagerProblem.MISSING
+    exec_path: str = ""
+
+
+@dataclass(frozen=True)
+class CredentialManagerCandidate:
+    """Name one file to try and where it comes from.
+
+    ``skip_reason`` is not empty when the file is only listed to be written to --log as skipped: it is never started.
+    """
+
+    filename: str
+    source: str
+    skip_reason: str = ""
+
+
+def _other_toolchain_bin_dir(path_dir: str, installation_dir: str, git_bin_dir: str) -> bool:
+    """Say whether ``path_dir`` is a second-level folder of the Git installation other than the bin folder of the Git in use.
+
+    All three paths are compared normalized and case-folded the way the system compares them.
+    """
+    path_key = os.path.normcase(os.path.normpath(path_dir))
+    grandparent_key = os.path.dirname(os.path.dirname(path_key))
+    if grandparent_key != os.path.normcase(os.path.normpath(installation_dir)):
+        return False
+    return path_key != os.path.normcase(os.path.normpath(git_bin_dir))
+
+
+@dataclass(frozen=True)
+class BoundedCommandAnswer:
+    """Keep what a short command answered: its exit code and standard output, or why it gave no answer at all."""
+
+    exit_code: int | None = None
+    output: bytes = b""
+    failure: str = ""
+
+
+def run_bounded_command(arguments: list[str], environment_by_name: Mapping[str, str], working_dir: str, timeout_ms: int) -> BoundedCommandAnswer:
+    """Run one short read-only command of an external program within a time limit, and never raise.
+
+    Its input is closed, so a program that waits for input fails instead of hanging, and on Windows no console window
+    opens. The console flag is chosen by os.name and not by a simulated platform, because it only exists on Windows.
+    The error output is dropped without being read: a warning written there never decides the version. The time limit
+    holds even when the program leaves children behind.
+    """
+    # Workaround: a pipe stays open as long as a child of the program keeps it. On Windows, subprocess.run reads the
+    # pipes again after killing the program at the time limit, so it waits for such a child (a launcher, or the warning
+    # stand-in that starts the real credential manager); on every system a program that answered and then left a child
+    # would look like it never answered. A file has no end to wait for, so the time limit bounds the call everywhere
+    # and only the started program is killed and waited for.
+    try:
+        with tempfile.TemporaryFile() as output_file:
+            completed = subprocess.run(arguments, stdin=subprocess.DEVNULL, stdout=output_file, stderr=subprocess.DEVNULL, cwd=working_dir,
+                                       env=dict(environment_by_name), timeout=timeout_ms / MILLISECONDS_PER_SECOND, check=False,
+                                       creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0)
+            output_file.seek(0)
+            output = output_file.read()
+    except subprocess.TimeoutExpired:
+        return BoundedCommandAnswer(failure=f"no answer within {timeout_ms / MILLISECONDS_PER_SECOND:g} s")
+    except (OSError, ValueError) as error:
+        return BoundedCommandAnswer(failure=type(error).__name__ + ": " + str(error))
+    return BoundedCommandAnswer(completed.returncode, output)
+
+
+def ignore_line(text: str) -> None:
+    """Write nothing: the log used when the caller keeps no --log file."""
+
+
+@dataclass(frozen=True)
+class ProbeVerdict:
+    """Say what one --version answer means: the problem it shows (NONE when usable), the version read and the --log result."""
+
+    problem: CredentialManagerProblem
+    version: str
+    result_text: str
+
+
+def _version_numbers(output: bytes) -> tuple[int, int, int] | None:
+    """Read the first three numbers of the first non-empty line of a --version output, or None when there are none."""
+    for line in output.decode("utf-8", errors="replace").splitlines():
+        if not line.strip():
+            continue
+        match = GCM_VERSION_PATTERN.search(line)
+        if match is None:
+            return None
+        major, minor, patch = match.groups()
+        return int(major), int(minor), int(patch)
+    return None
+
+
+def _version_text(numbers: tuple[int, int, int]) -> str:
+    """Write a version as X.Y.Z, the form shown to the user whatever build suffix the program printed."""
+    major, minor, patch = numbers
+    return f"{major}.{minor}.{patch}"
+
+
+def credential_manager_refusal_text(detection: CredentialManagerDetection, platform: str) -> str:
+    """Write the sentence of one refusal, ending with the path of the refused credential manager when there is one.
+
+    ``platform`` names the system only for the refusal of a system the search does not support.
+    """
+    return REFUSAL_TEXT_BY_PROBLEM[detection.problem].format(filename=detection.filename, version=detection.version,
+                                                             minimum=_version_text(GCM_MINIMUM_VERSION), platform=platform)
+
+
+def credential_manager_check_again_text(shown: CredentialManagerDetection, found: CredentialManagerDetection, platform: str) -> str:
+    """Write what the install window says after a new search that still refuses.
+
+    The short line only when the window would explain the refusal ``found`` with the very lines it already shows for
+    ``shown``; any other refusal, including the same reason with another version or file, gives its own sentence, path
+    included, and the window then shows that refusal's text.
+    """
+    if _install_header_lines(found, platform) == _install_header_lines(shown, platform):
+        return CREDENTIAL_MANAGER_STILL_REFUSED_TEXT
+    return credential_manager_refusal_text(found, platform)
+
+
+def credential_manager_setting_text(detection: CredentialManagerDetection, platform: str) -> str:
+    """Write the Settings line: the version and path of the credential manager in use, ``not found`` for an absence, the refusal sentence otherwise."""
+    if detection.problem == CredentialManagerProblem.NONE:
+        return CREDENTIAL_MANAGER_FOUND_TEXT.format(version=detection.version, filename=detection.filename)
+    if detection.problem == CredentialManagerProblem.MISSING:
+        return CREDENTIAL_MANAGER_NOT_FOUND_TEXT
+    return credential_manager_refusal_text(detection, platform)
+
+
+class CredentialManagerRefusal(ValueError):
+    """Raised when the credential manager GitPane looked for cannot be used; its message is the constant sentence of that refusal.
+
+    An operation that stops on it started no Git process for the refused destination, so its console reads it as a
+    refusal before launch. It keeps the detection too, so the window explaining how to install the credential manager
+    knows the reason and the version without reading the sentence back.
+    """
+
+    def __init__(self, detection: CredentialManagerDetection, platform: str) -> None:
+        """Build the refusal sentence of ``detection`` and keep the detection itself."""
+        super().__init__(credential_manager_refusal_text(detection, platform))
+        self.detection = detection
+
+
+def _install_header_lines(detection: CredentialManagerDetection, platform: str) -> tuple[str, ...]:
+    """Write the lines that open the install window for this refusal, saying why it is refused when there is more to say than its absence.
+
+    The too-old line names only the version, so the same old version found in another file opens the window the same way.
+    """
+    if detection.problem == CredentialManagerProblem.TOO_OLD:
+        return (CREDENTIAL_MANAGER_TOO_OLD_HEADER_TEXT.format(version=detection.version, minimum=_version_text(GCM_MINIMUM_VERSION)),)
+    if detection.problem == CredentialManagerProblem.MISSING:
+        return ()
+    return (credential_manager_refusal_text(detection, platform),)
+
+
+def platform_install_lines(entry: CredentialManagerPlatform, problem: CredentialManagerProblem) -> tuple[str, ...]:
+    """Pick the install lines of one refusal: the system's lines for that reason when it has its own, else its general lines.
+
+    A missing credential manager and one that is too old may need different advice (install versus upgrade); a system
+    that gives no lines of its own for a reason shows its general install lines for it.
+    """
+    reason_lines_by_problem = {CredentialManagerProblem.MISSING: entry.missing_install_lines, CredentialManagerProblem.TOO_OLD: entry.too_old_install_lines}
+    reason_lines = reason_lines_by_problem.get(problem, ())
+    if reason_lines:
+        return reason_lines
+    return entry.install_lines
+
+
+def _probe_verdict(answer: BoundedCommandAnswer) -> ProbeVerdict:
+    """Classify one --version answer.
+
+    A non-zero exit code means the program does not start properly even when it printed a version. An output without
+    a version is kept apart from a program that does not start, and only a cut, single-line form of it is logged,
+    since it comes from an unknown program.
+    """
+    if answer.failure:
+        return ProbeVerdict(CredentialManagerProblem.NOT_STARTING, "", "did not start: " + answer.failure)
+    if answer.exit_code != 0:
+        return ProbeVerdict(CredentialManagerProblem.NOT_STARTING, "", f"did not start: exit code {answer.exit_code}")
+    numbers = _version_numbers(answer.output)
+    if numbers is None:
+        output_text = answer.output.decode("utf-8", errors="replace")[:UNKNOWN_OUTPUT_LOG_LIMIT]
+        return ProbeVerdict(CredentialManagerProblem.UNREADABLE_VERSION, "", "unreadable version: " + repr(output_text))
+    version = _version_text(numbers)
+    if numbers < GCM_MINIMUM_VERSION:
+        return ProbeVerdict(CredentialManagerProblem.TOO_OLD, version, f"too old ({version})")
+    return ProbeVerdict(CredentialManagerProblem.NONE, version, f"accepted ({version})")
+
+
+class CredentialManagerLocator:
+    """Find the official Git Credential Manager for a Git executable and keep only usable answers for the session.
+
+    Blocking and free of Qt objects: it starts short processes and may wait up to its time limit for each candidate,
+    so callers run it away from the window's thread. Its search never raises. A credential manager installed after a
+    refusal is found by the next search, since refusals are never kept.
+    """
+
+    def __init__(self, platform: str, environment_by_name: Mapping[str, str], *, log_line: Callable[[str], None] = ignore_line,
+                 timeout_ms: int = GCM_VERSION_TIMEOUT_MS, platform_entry_by_name: Mapping[str, CredentialManagerPlatform] = CREDENTIAL_MANAGER_PLATFORM_BY_NAME,
+                 available: Callable[[str], bool] = absolute_executable_available, network: Callable[[str], bool] = network_directory,
+                 distribution_family: DistributionFamily = DistributionFamily.UNKNOWN, architecture: GcmArchiveArchitecture | None = None) -> None:
+        """Keep what the search needs; the distribution family and the processor only choose the Linux install lines.
+
+        Their defaults read nothing from the machine and give the lines of an unknown distribution on an unknown
+        processor; the composition root passes the ones of the running session.
+        """
+        self.platform = platform
+        self.distribution_family = distribution_family
+        self.architecture = architecture
+        self.environment_by_name = environment_by_name
+        self.log_line = log_line
+        self.timeout_ms = timeout_ms
+        self.platform_entry_by_name = platform_entry_by_name
+        self.available = available
+        self.network = network
+        self.detection_by_git_filename: dict[str, CredentialManagerDetection] = {}
+        # Several background tasks may need the credential manager at the same time (fetch, push, clone, accounts):
+        # one search at a time keeps them from starting the same probes twice and from mixing their --log lines.
+        self.lock = threading.Lock()
+
+    def refusal_install_lines(self, problem: CredentialManagerProblem) -> tuple[str, ...]:
+        """Write what to install for a refusal: the lines of this search's distribution and processor where the system's entry says they depend on them, else the entry's lines for that refusal.
+
+        On Linux, a credential manager too old, unreadable or not starting gets the same lines as a missing one: a
+        second extraction of the archive, or a second install of the package, replaces its files.
+        """
+        entry = self.platform_entry_by_name[self.platform]
+        if entry.install_lines_by_distribution:
+            return distribution_gcm_install_lines(self.distribution_family, self.architecture)
+        return platform_install_lines(entry, problem)
+
+    def install_lines(self, detection: CredentialManagerDetection) -> tuple[str, ...]:
+        """Write the lines of the install window for a refusal of this search: why it is refused when there is more to say than its absence, then what to install.
+
+        The install lines come from refusal_install_lines, read from this search's own platform table, the one it
+        searched with, and follow the reason of the refusal. Called only for a refusal of INSTALL_WINDOW_PROBLEM_SET,
+        which a system missing from that table never gives.
+        """
+        return (*_install_header_lines(detection, self.platform), GCM_REQUIRED_TEXT, *self.refusal_install_lines(detection.problem))
+
+    def _git_exec_path(self, git_filename: str) -> str:
+        """Ask the Git in use for the folder of its own programs, or return "" and log why it is unknown.
+
+        An inherited GIT_EXEC_PATH is removed first: Git would answer that variable instead of its own folder. Only one
+        absolute line counts as an answer; the search goes on without it otherwise.
+        """
+        environment_by_name = dict(self.environment_by_name)
+        environment_by_name.pop(GIT_EXEC_PATH_ENVIRONMENT_NAME, None)
+        answer = run_bounded_command([git_filename, GIT_EXEC_PATH_ARGUMENT], environment_by_name, os.path.dirname(git_filename), GIT_OPEN_TIMEOUT_MS)
+        cause = answer.failure
+        if not cause and answer.exit_code != 0:
+            cause = f"exit code {answer.exit_code}"
+        if not cause:
+            # Read as a file name, a folder whose name is not UTF-8 reaches the credential manager unchanged in
+            # GIT_EXEC_PATH.
+            try:
+                return parse_exec_path_answer(answer.output)
+            except ValueError as error:
+                cause = str(error)
+        self.log_line(f"Git exec path not read for {git_filename}: {cause}")
+        return ""
+
+    def _probe_environment(self, exec_path: str) -> dict[str, str]:
+        """Return the environment of a --version probe: the user's credential manager settings removed, Git's folder given.
+
+        A setting such as a debugger wait would make a sound credential manager look broken, and without Git's folder
+        the credential manager cannot find Git when Git is not on the PATH.
+        """
+        environment_by_name = dict(self.environment_by_name)
+        for name in tuple(environment_by_name):
+            if name.startswith(GCM_ENVIRONMENT_PREFIX):
+                environment_by_name.pop(name)
+        if exec_path:
+            environment_by_name[GIT_EXEC_PATH_ENVIRONMENT_NAME] = exec_path
+        return environment_by_name
+
+    def _candidates(self, entry: CredentialManagerPlatform, exec_path: str) -> list[CredentialManagerCandidate]:
+        """List the files to try with where each comes from, each file once, in search order.
+
+        The installation of the Git in use comes first when the system has one to search, then the PATH, then the
+        fixed locations of the system. Skipped candidates stay in the list at their place, so the search writes them in
+        order and stops before them once a credential manager is accepted.
+        """
+        windows = self.platform == WINDOWS_PLATFORM
+        listed_candidates: list[CredentialManagerCandidate] = []
+        installation_dir = ""
+        git_bin_dir = ""
+        if entry.searches_git_installation and exec_path:
+            # Git for Windows answers --exec-path with <prefix>/libexec/git-core, where <prefix> is the toolchain folder
+            # of this installation; that folder changes with the version and the architecture. Its credential manager
+            # sits in <prefix>/bin. No folder name is written here, so a later move is followed by itself, and the
+            # warning stand-in left in another toolchain folder is never taken, neither here nor from the PATH below.
+            prefix_dir = os.path.dirname(os.path.dirname(exec_path))
+            git_bin_dir = os.path.join(prefix_dir, GIT_BINARY_DIR_BASENAME)
+            installation_dir = os.path.dirname(prefix_dir)
+            listed_candidates.append(CredentialManagerCandidate(os.path.join(git_bin_dir, entry.executable_basename), GIT_FOR_WINDOWS_SOURCE_TEXT))
+        # The PATH is read here instead of with shutil.which, which on Windows looks in the current folder first: a
+        # program dropped there, or in a relative PATH entry, must never be started and handed account secrets.
+        for path_dir in self.environment_by_name.get(PATH_ENVIRONMENT_NAME, "").split(os.pathsep):
+            if not os.path.isabs(path_dir):
+                continue
+            filename = os.path.join(path_dir, entry.executable_basename)
+            if windows and self.network(path_dir):
+                listed_candidates.append(CredentialManagerCandidate(filename, PATH_SOURCE_TEXT, skip_reason=NETWORK_SHARE_SKIP_TEXT))
+                continue
+            # The Git for Windows install option that adds its Unix tools to the PATH puts there the bin folder of
+            # another toolchain folder of the same installation. The credential manager found there is the warning
+            # stand-in that starts the real one and adds a warning to every call. It is skipped even when the credential
+            # manager of the Git in use is refused or missing, otherwise it would be accepted and kept for the session.
+            if installation_dir and _other_toolchain_bin_dir(path_dir, installation_dir, git_bin_dir):
+                listed_candidates.append(CredentialManagerCandidate(filename, PATH_SOURCE_TEXT, skip_reason=OTHER_TOOLCHAIN_SKIP_TEXT))
+                continue
+            listed_candidates.append(CredentialManagerCandidate(filename, PATH_SOURCE_TEXT))
+        for fixed_filename in entry.fixed_filenames:
+            listed_candidates.append(CredentialManagerCandidate(fixed_filename, STANDARD_LOCATION_SOURCE_TEXT))
+        candidates: list[CredentialManagerCandidate] = []
+        identity_set: set[str] = set()
+        for candidate in listed_candidates:
+            identity = os.path.normcase(os.path.abspath(candidate.filename))
+            if identity in identity_set:
+                continue
+            identity_set.add(identity)
+            candidates.append(candidate)
+        return candidates
+
+    def locate(self, git_filename: str) -> CredentialManagerDetection:
+        """Return the usable credential manager for this Git, or the most useful reason none is usable; never raises.
+
+        Candidates are tried in search order and the first accepted one wins. When none is accepted, the refusal kept
+        is the most useful one; between equal reasons the first candidate seen keeps its file and version. A success
+        is kept for this Git and returned again without starting anything while its file and Git's folder still exist.
+        """
+        with self.lock:
+            entry = self.platform_entry_by_name.get(self.platform)
+            if entry is None:
+                self.log_line(f"Credential manager not searched: unsupported system {self.platform}")
+                return CredentialManagerDetection(problem=CredentialManagerProblem.UNSUPPORTED_PLATFORM)
+            kept = self.detection_by_git_filename.get(git_filename)
+            if kept is not None:
+                # An update of Git for Windows can move its programs folder while the credential manager file stays.
+                if self.available(kept.filename) and (not kept.exec_path or os.path.isdir(kept.exec_path)):
+                    return kept
+                del self.detection_by_git_filename[git_filename]
+                self.log_line(f"Kept credential manager is gone, searching again: {kept.filename}")
+            detection = self._search(entry, git_filename)
+            if detection.problem == CredentialManagerProblem.NONE:
+                self.detection_by_git_filename[git_filename] = detection
+            return detection
+
+    def _search(self, entry: CredentialManagerPlatform, git_filename: str) -> CredentialManagerDetection:
+        """Try every candidate for this Git and return the first accepted one, or the most useful refusal."""
+        exec_path = self._git_exec_path(git_filename)
+        probe_environment_by_name = self._probe_environment(exec_path)
+        refusal = CredentialManagerDetection(exec_path=exec_path)
+        for candidate in self._candidates(entry, exec_path):
+            if candidate.skip_reason:
+                self.log_line(f"Credential manager candidate {candidate.filename} ({candidate.source}): skipped, {candidate.skip_reason}")
+                continue
+            if not self.available(candidate.filename):
+                self.log_line(f"Credential manager candidate {candidate.filename} ({candidate.source}): not found")
+                continue
+            answer = run_bounded_command([candidate.filename, GCM_VERSION_ARGUMENT], probe_environment_by_name, os.path.dirname(candidate.filename), self.timeout_ms)
+            verdict = _probe_verdict(answer)
+            self.log_line(f"Credential manager candidate {candidate.filename} ({candidate.source}): {verdict.result_text}")
+            detection = CredentialManagerDetection(os.path.abspath(candidate.filename), verdict.version, candidate.source, verdict.problem, exec_path)
+            if verdict.problem == CredentialManagerProblem.NONE:
+                self.log_line(f"Credential manager detected: {detection.filename} ({candidate.source}, {verdict.version})")
+                return detection
+            if MOST_USEFUL_FIRST_REFUSAL_PROBLEMS.index(verdict.problem) < MOST_USEFUL_FIRST_REFUSAL_PROBLEMS.index(refusal.problem):
+                refusal = detection
+        conclusion = "Credential manager not usable: " + refusal.problem.value
+        if refusal.filename:
+            conclusion += " " + refusal.filename + (f" ({refusal.version})" if refusal.version else "")
+        self.log_line(conclusion)
+        return refusal

gitpane/account/credential_manager_install.py

@@ -0,0 +1,171 @@
+"""Write the commands that install the Git Credential Manager on a Linux distribution.
+
+Each family of distributions has its own row in the table, 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. Only
+constants of GitPane and the table of processors fill the commands: nothing read from the machine (os-release, the
+processor name) ever enters a command, it only picks a family or an architecture, members of an enum.
+"""
+
+from __future__ import annotations
+
+import platform
+from dataclasses import dataclass
+from enum import Enum
+
+from gitpane.config import GCM_ARCHIVE_VERSION, GCM_CORE_DIR, GCM_RELEASES_URL
+from gitpane.system.linux_distribution import DistributionFamily
+
+
+class GcmArchiveArchitecture(Enum):
+    """A processor the official Linux archive of the Git Credential Manager is built for; the value is the word of the archive's file name."""
+
+    X64 = "x64"
+    ARM64 = "arm64"
+
+
+# Keyed by platform.machine() on Linux. A processor missing from the table has no official archive.
+GCM_ARCHIVE_ARCHITECTURE_BY_MACHINE: dict[str, GcmArchiveArchitecture] = {
+    "x86_64": GcmArchiveArchitecture.X64,
+    "aarch64": GcmArchiveArchitecture.ARM64,
+}
+
+GCM_ARCHIVE_BASENAME_TEMPLATE = "gcm-linux-{architecture}-{version}.tar.gz"
+GCM_ARCHIVE_URL_TEMPLATE = "https://github.com/git-ecosystem/git-credential-manager/releases/download/v{version}/{basename}"
+
+
+def gcm_archive_architecture(machine: str) -> GcmArchiveArchitecture | None:
+    """Return the archive architecture of a processor name as ``platform.machine()`` writes it, or None when no official archive exists for it."""
+    return GCM_ARCHIVE_ARCHITECTURE_BY_MACHINE.get(machine)
+
+
+def session_gcm_archive_architecture() -> GcmArchiveArchitecture | None:
+    """Return the archive architecture of the running machine's processor, or None when no official archive exists for it."""
+    return gcm_archive_architecture(platform.machine())
+
+
+class GcmInstallText(Enum):
+    """A line of the Linux install text of the Git Credential Manager, as the install window shows it."""
+
+    RUN_IN_TERMINAL = " - in a terminal, run :"
+    """Introduces the commands, each alone on its line so it can be copied as is."""
+    RELEASES = " - releases : " + GCM_RELEASES_URL
+    """Ends the archive commands with the page of the releases, the only link of the text."""
+    UNKNOWN_DISTRIBUTION = " - GitPane does not know this distribution; the official archive runs on most distributions that use glibc : " + GCM_RELEASES_URL
+    """Opens the text of a distribution GitPane does not know, the link first, before the archive commands."""
+    NO_BUILD_FOR_PROCESSOR = " - no official Git credential manager build exists for this processor : " + GCM_RELEASES_URL
+    """The only line of a processor the official archive is not built for."""
+    DEBIAN_DOWNLOAD = " - download a .deb here : " + GCM_RELEASES_URL
+    """First line of the Debian family, which installs the official .deb."""
+    DEBIAN_INSTALL = " - install it with : sudo apt install ./gcm-linux-<arch>-<version>.deb"
+    """Second line of the Debian family: apt installs the downloaded .deb."""
+    DEBIAN_OTHER_DISTRIBUTIONS = " - or for other distros, a .tar.gz here : " + GCM_RELEASES_URL
+    """Third line of the Debian family, kept word for word from the lines Debian and Ubuntu already showed."""
+    # -L follows GitHub's redirection to the file, -f refuses to write an error page under the archive's name.
+    ARCHIVE_DOWNLOAD = 'cd "$(mktemp -d)" && curl -fLO {url}'
+    """Downloads the official archive into a new temporary folder."""
+    # The archive gives its ./ folder to uid 1000: extracted as root without --no-same-owner --no-overwrite-dir, it would
+    # give a system folder to the first user. The folder is created first so it belongs to root. No configuration step
+    # follows, since GitPane gives its own helper to every command it starts.
+    ARCHIVE_INSTALL = "sudo mkdir -p {core_dir} && sudo tar --no-same-owner --no-overwrite-dir -xzf {basename} -C {core_dir}"
+    """Extracts the official archive into the folder GitPane searches after the PATH."""
+    FEDORA_PACKAGES = "sudo dnf install libsecret libicu"
+    """Installs the libraries the archive needs, which a minimal or server install may lack, on the whole Fedora and RHEL families.
+
+    The Fedora family also holds Mageia, Bazzite and the other image-based Fedora, and Amazon Linux, where this command
+    can fail (other package names, a read-only system image, yum alone). It is kept for the whole family on purpose: those
+    systems already carry both libraries or name them otherwise, and the archive commands after it still work.
+    """
+    LIBRARIES_IF_NOT_STARTING = " - if the Git credential manager does not start, install libsecret and ICU with the package manager"
+    """Names the libraries the archive needs where GitPane gives no package command, since their package names were not checked."""
+    ARCH_PACKAGES = "sudo pacman -S --needed libsecret icu"
+    """Installs on Arch the libraries the archive needs, which a system without a desktop may lack."""
+    GENTOO_PACKAGES = "sudo emerge --ask --noreplace app-crypt/libsecret dev-libs/icu net-misc/curl"
+    """Installs on Gentoo the libraries the archive needs and curl, which a system without a desktop may lack."""
+    VOID_PACKAGES = "sudo xbps-install -S curl libsecret icu"
+    """Installs on Void curl and the libraries the archive needs, which a system without a desktop may lack."""
+    VOID_MUSL = " - the musl variant of Void cannot run the official archive : " + GCM_RELEASES_URL
+    """Opens Void's lines: both variants share one os-release ID, and the archive is built against glibc."""
+    VOID_GLIBC_RUN_IN_TERMINAL = " - on the glibc variant of Void, in a terminal, run :"
+    """Introduces Void's commands, which only the glibc variant can run."""
+    ALPINE = " - no official Git credential manager build runs on Alpine (musl libc) : " + GCM_RELEASES_URL
+    """The only line of Alpine, whose musl C library runs no program built against glibc."""
+    NIXOS = " - the official Git credential manager archive does not run as is on NixOS or GNU Guix : " + GCM_RELEASES_URL
+    """The only line of NixOS and Guix, which have no dynamic loader at the standard path a prebuilt program expects."""
+
+
+@dataclass(frozen=True)
+class FamilyGcmInstall:
+    """How one family of distributions installs the Git Credential Manager: plain lines, or the archive commands framed by its own lines."""
+
+    # Lines given as they are, without any archive command; when set, the other fields are not read.
+    plain_lines: tuple[GcmInstallText, ...] = ()
+    # True when the plain lines point to a file of the releases page, which only exists for the processors of the
+    # archive: another processor then gets the single line saying no official build exists for it.
+    plain_lines_need_archive_processor: bool = False
+    # Lines before the archive commands.
+    lead_lines: tuple[GcmInstallText, ...] = ()
+    run_line: GcmInstallText = GcmInstallText.RUN_IN_TERMINAL
+    # Command of the family's own package manager that installs what the archive needs, before the download.
+    package_command: GcmInstallText | None = None
+    trailing_lines: tuple[GcmInstallText, ...] = (GcmInstallText.RELEASES,)
+
+
+# Keyed by the family read from os-release; the value is text of the install window, another layer than the family.
+GCM_INSTALL_BY_FAMILY: dict[DistributionFamily, FamilyGcmInstall] = {
+    DistributionFamily.DEBIAN: FamilyGcmInstall(plain_lines=(GcmInstallText.DEBIAN_DOWNLOAD, GcmInstallText.DEBIAN_INSTALL, GcmInstallText.DEBIAN_OTHER_DISTRIBUTIONS),
+                                                plain_lines_need_archive_processor=True),
+    # Kept for the whole family by choice, although the command can fail on Mageia, on image-based Fedora such as Bazzite
+    # and where only yum exists: see the docstring of the command.
+    DistributionFamily.FEDORA: FamilyGcmInstall(package_command=GcmInstallText.FEDORA_PACKAGES),
+    DistributionFamily.RHEL: FamilyGcmInstall(package_command=GcmInstallText.FEDORA_PACKAGES),
+    # The package names of these families were not checked, so the libraries are named rather than given as a command.
+    DistributionFamily.SUSE: FamilyGcmInstall(trailing_lines=(GcmInstallText.LIBRARIES_IF_NOT_STARTING, GcmInstallText.RELEASES)),
+    DistributionFamily.SOLUS: FamilyGcmInstall(trailing_lines=(GcmInstallText.LIBRARIES_IF_NOT_STARTING, GcmInstallText.RELEASES)),
+    DistributionFamily.ARCH: FamilyGcmInstall(package_command=GcmInstallText.ARCH_PACKAGES),
+    # The official Gentoo package of the credential manager only exists under a testing keyword, hence the archive.
+    DistributionFamily.GENTOO: FamilyGcmInstall(package_command=GcmInstallText.GENTOO_PACKAGES),
+    DistributionFamily.VOID: FamilyGcmInstall(lead_lines=(GcmInstallText.VOID_MUSL,), run_line=GcmInstallText.VOID_GLIBC_RUN_IN_TERMINAL,
+                                              package_command=GcmInstallText.VOID_PACKAGES, trailing_lines=()),
+    # The official program asks for glibc's dynamic loader, which musl does not provide.
+    DistributionFamily.ALPINE: FamilyGcmInstall(plain_lines=(GcmInstallText.ALPINE,)),
+    DistributionFamily.NIXOS: FamilyGcmInstall(plain_lines=(GcmInstallText.NIXOS,)),
+    # The link comes first, since nothing says the archive runs on a distribution GitPane does not know.
+    DistributionFamily.UNKNOWN: FamilyGcmInstall(lead_lines=(GcmInstallText.UNKNOWN_DISTRIBUTION,), trailing_lines=(GcmInstallText.LIBRARIES_IF_NOT_STARTING,)),
+}
+
+
+def _archive_command_lines(architecture: GcmArchiveArchitecture) -> tuple[str, str]:
+    """Write the download and the extraction commands of the official archive for one processor."""
+    basename = GCM_ARCHIVE_BASENAME_TEMPLATE.format(architecture=architecture.value, version=GCM_ARCHIVE_VERSION)
+    url = GCM_ARCHIVE_URL_TEMPLATE.format(version=GCM_ARCHIVE_VERSION, basename=basename)
+    download_line = GcmInstallText.ARCHIVE_DOWNLOAD.value.format(url=url)
+    install_line = GcmInstallText.ARCHIVE_INSTALL.value.format(core_dir=GCM_CORE_DIR, basename=basename)
+    return download_line, install_line
+
+
+def distribution_gcm_install_lines(family: DistributionFamily, architecture: GcmArchiveArchitecture | None) -> tuple[str, ...]:
+    """Write the install lines of a distribution family on a processor.
+
+    A family with plain lines gets them on every processor, unless those lines point to an official file, which only
+    exists for the processors of the architecture table. Any other family installs the official archive, built for
+    the same processors. A processor without an official file gets a single line saying so, never a command that
+    cannot work.
+    """
+    family_install = GCM_INSTALL_BY_FAMILY[family]
+    if family_install.plain_lines and (architecture is not None or not family_install.plain_lines_need_archive_processor):
+        lines: list[str] = []
+        for text in family_install.plain_lines:
+            lines.append(text.value)
+        return tuple(lines)
+    if architecture is None:
+        return (GcmInstallText.NO_BUILD_FOR_PROCESSOR.value,)
+    lines = []
+    for text in family_install.lead_lines:
+        lines.append(text.value)
+    lines.append(family_install.run_line.value)
+    if family_install.package_command is not None:
+        lines.append(family_install.package_command.value)
+    lines.extend(_archive_command_lines(architecture))
+    for text in family_install.trailing_lines:
+        lines.append(text.value)
+    return tuple(lines)