gitpane 1.0.0__py3-none-any.whl

gitpane/system/installed_launcher.py

@@ -0,0 +1,136 @@
+"""Choose the command a desktop shortcut runs to start the running GitPane installation.
+
+pip and pipx write a small launcher for every script an installed package declares, in the scripts folder of the
+Python that installed it. A desktop shortcut starts that launcher when the running installation has one, so it follows
+whichever installation is running: a pipx environment, a global or ``--user`` pip install, or the editable install of a
+development checkout. An installation without that launcher (an editable install made before GitPane declared its
+command) is started through the running Python itself, on GitPane's application module.
+"""
+
+from __future__ import annotations
+
+import ntpath
+import os
+import shlex
+import subprocess
+import sys
+import sysconfig
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from gitpane.config import LINUX_PLATFORM, MACOS_PLATFORM, MODULE_OPTION, SAFE_PATH_OPTION, WINDOWS_PLATFORM
+from gitpane.process.process_group import WINDOWLESS_INTERPRETER_BASENAME
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+# The name of the gui-script that pyproject.toml declares, hence the name of the launcher pip writes.
+GITPANE_COMMAND_NAME = "gitpane"
+LAUNCHER_BASENAME_BY_PLATFORM = {
+    WINDOWS_PLATFORM: GITPANE_COMMAND_NAME + ".exe",
+    LINUX_PLATFORM: GITPANE_COMMAND_NAME,
+    MACOS_PLATFORM: GITPANE_COMMAND_NAME,
+}
+SCRIPTS_PATH_NAME = "scripts"
+USER_SCHEME_KIND = "user"
+# How a program and its arguments are written as one line the user can paste: Windows' own quoting there, a POSIX
+# shell's everywhere else.
+COMMAND_LINE_JOIN_BY_PLATFORM: dict[str, Callable[[Sequence[str]], str]] = {
+    WINDOWS_PLATFORM: subprocess.list2cmdline,
+}
+DEFAULT_COMMAND_LINE_JOIN = shlex.join
+
+
+@dataclass(frozen=True)
+class StartCommand:
+    """The program a shortcut starts and the arguments it passes before its own, never ``--log``."""
+
+    program_filename: str
+    arguments: tuple[str, ...] = ()
+
+
+def launcher_basename(platform: str) -> str:
+    """Return the file name pip gives the gitpane launcher on ``platform``; an unknown system raises OSError."""
+    basename = LAUNCHER_BASENAME_BY_PLATFORM.get(platform)
+    if basename is None:
+        raise OSError("No gitpane launcher name known for " + platform)
+    return basename
+
+
+def running_in_virtual_environment() -> bool:
+    """Tell whether the running Python is a virtual environment (a checkout's .venv, a pipx environment)."""
+    return sys.prefix != sys.base_prefix
+
+
+def installation_script_dirs(in_virtual_environment: bool) -> list[str]:
+    """List the scripts folders where the running installation keeps its launchers: its own, then, outside a venv, the one of ``pip install --user``.
+
+    A venv only looks in its own folder: a gitpane link that another installation (pipx) put in ``~/.local/bin`` must
+    never pass for the GitPane of that venv. The user folder comes from ``sysconfig.get_preferred_scheme("user")``,
+    never from ``os.name + "_user"``: on a macOS framework Python (Homebrew, python.org) the user scheme is
+    ``osx_framework_user``, whose scripts folder is not the one ``posix_user`` names. Empty and repeated folders are
+    left out, the order is kept.
+    """
+    candidate_dirs = [sysconfig.get_path(SCRIPTS_PATH_NAME)]
+    if not in_virtual_environment:
+        try:
+            user_scheme = sysconfig.get_preferred_scheme(USER_SCHEME_KIND)
+            candidate_dirs.append(sysconfig.get_path(SCRIPTS_PATH_NAME, user_scheme))
+        except KeyError:
+            pass
+    script_dirs = []
+    for script_dir in candidate_dirs:
+        if script_dir and script_dir not in script_dirs:
+            script_dirs.append(script_dir)
+    return script_dirs
+
+
+def find_launcher_filename(script_dirs: Sequence[str], platform: str, is_file: Callable[[str], bool] = os.path.isfile) -> str:
+    """Return the first gitpane launcher found in ``script_dirs``, or an empty text when none of them holds one."""
+    basename = launcher_basename(platform)
+    for script_dir in script_dirs:
+        launcher_filename = os.path.join(script_dir, basename)
+        if is_file(launcher_filename):
+            return launcher_filename
+    return ""
+
+
+def windowless_python_filename(python_filename: str, platform: str, is_file: Callable[[str], bool] = os.path.isfile) -> str:
+    """Return the Python a shortcut starts in place of ``python_filename``: on Windows the windowless pythonw.exe next to it when it is there.
+
+    A shortcut that started python.exe would open a console window beside GitPane. Elsewhere, and when pythonw.exe is
+    missing, ``python_filename`` is returned as it is: a venv's python is a link to the system's, so resolving it, or
+    making it absolute, would start GitPane outside its venv.
+    """
+    if platform != WINDOWS_PLATFORM:
+        return python_filename
+    # This only matters on Windows; ntpath keeps the path the same when the tests run it on another system.
+    windowless_filename = ntpath.join(ntpath.dirname(python_filename), WINDOWLESS_INTERPRETER_BASENAME)
+    if is_file(windowless_filename):
+        return windowless_filename
+    return python_filename
+
+
+def start_command(script_dirs: Sequence[str], platform: str, python_filename: str, application_module_name: str,
+                  is_file: Callable[[str], bool] = os.path.isfile) -> StartCommand | None:
+    """Choose what a shortcut starts: the gitpane command of ``script_dirs``, or else ``python_filename`` with ``-P -m`` on the application module.
+
+    The gitpane command is started with no argument. None is returned when there is no gitpane command and the Python
+    or the module cannot be named; an unknown system raises OSError.
+    """
+    launcher_filename = find_launcher_filename(script_dirs, platform, is_file)
+    if launcher_filename:
+        return StartCommand(launcher_filename)
+    if not python_filename or not application_module_name:
+        return None
+    return StartCommand(windowless_python_filename(python_filename, platform, is_file), (SAFE_PATH_OPTION, MODULE_OPTION, application_module_name))
+
+
+def command_line(arguments: Sequence[str], platform: str) -> str:
+    """Write ``arguments`` as one command line of ``platform``, each one quoted the way that system's shell reads it back."""
+    return COMMAND_LINE_JOIN_BY_PLATFORM.get(platform, DEFAULT_COMMAND_LINE_JOIN)(arguments)
+
+
+def start_command_line(command: StartCommand, platform: str) -> str:
+    """Write the program and the arguments of ``command`` as one command line of ``platform``, the way Settings shows it."""
+    return command_line((command.program_filename, *command.arguments), platform)

gitpane/system/linux_distribution.py

@@ -0,0 +1,151 @@
+"""Tell which Linux distribution os-release describes, as GitPane groups them.
+
+The family is the one of os-release's ID when the table knows it, otherwise the one of the first word of ID_LIKE the
+table knows, read from left to right, otherwise UNKNOWN. The precise distribution comes from the exact ID alone, and only
+names the few distributions whose install commands differ from the rest of their family; any other ID gives OTHER, so a
+derivative known only through ID_LIKE keeps the line of its family. ID and ID_LIKE are compared exactly as os-release
+writes them, without changing their case. Nothing read from os-release ever becomes a text shown to the user or a
+command: only a member of ``DistributionFamily`` or ``DistributionRelease`` leaves this module, and the commands GitPane
+shows come from its own tables.
+Python's ``freedesktop_os_release`` keeps os-release for the whole process once it was read successfully, so asking the
+family again then costs no file read; on a system without os-release, each call tries both files again and raises
+``OSError``, which gives UNKNOWN and OTHER here.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from platform import freedesktop_os_release
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+OS_RELEASE_ID_KEY = "ID"
+OS_RELEASE_ID_LIKE_KEY = "ID_LIKE"
+
+
+class DistributionFamily(Enum):
+    """A family of Linux distributions that install software the same way; UNKNOWN when os-release names none GitPane knows."""
+
+    DEBIAN = "debian"
+    """Debian, Ubuntu and their derivatives, which install ``.deb`` packages through apt."""
+    FEDORA = "fedora"
+    """Fedora and the distributions built on it, which install packages through dnf."""
+    RHEL = "rhel"
+    """Red Hat Enterprise Linux and its rebuilds, kept apart from Fedora because some tools only reach them through EPEL."""
+    SUSE = "suse"
+    """openSUSE and SUSE Linux Enterprise, which install packages through zypper."""
+    ARCH = "arch"
+    """Arch Linux and its derivatives, which install packages through pacman."""
+    GENTOO = "gentoo"
+    """Gentoo and Funtoo, which build packages through emerge."""
+    VOID = "void"
+    """Void Linux, which installs packages through xbps, in a glibc and a musl variant under the same ID."""
+    ALPINE = "alpine"
+    """Alpine Linux and its derivatives, built on the musl C library, which runs no program linked against glibc."""
+    NIXOS = "nixos"
+    """NixOS and Guix System, neither of which has the dynamic loader or the libraries at the standard paths a prebuilt Linux program expects."""
+    SOLUS = "solus"
+    """Solus, which installs packages through eopkg."""
+    UNKNOWN = "unknown"
+    """A distribution os-release describes with no ID or ID_LIKE word GitPane knows, or a system without os-release."""
+
+
+# A key is an ID or a word of ID_LIKE, exactly as os-release writes it. Since ID is read first, a derivative is found by
+# its own ID before any word of its ID_LIKE: Rocky Linux and AlmaLinux say ``ID_LIKE="rhel centos fedora"`` and find
+# ``rhel`` first, while Nobara and Bazzite, Fedora derivatives whose ID_LIKE also starts with ``rhel``, stay Fedora
+# through their own ID. Garuda and Artix write no ID_LIKE, so their own ID is the key.
+FAMILY_BY_OS_RELEASE_ID: dict[str, DistributionFamily] = {
+    "debian": DistributionFamily.DEBIAN,
+    "ubuntu": DistributionFamily.DEBIAN,
+    "fedora": DistributionFamily.FEDORA,
+    "nobara": DistributionFamily.FEDORA,
+    "bazzite": DistributionFamily.FEDORA,
+    "rhel": DistributionFamily.RHEL,
+    "centos": DistributionFamily.RHEL,
+    "rocky": DistributionFamily.RHEL,
+    "almalinux": DistributionFamily.RHEL,
+    "ol": DistributionFamily.RHEL,
+    "opensuse": DistributionFamily.SUSE,
+    "suse": DistributionFamily.SUSE,
+    "arch": DistributionFamily.ARCH,
+    "garuda": DistributionFamily.ARCH,
+    "artix": DistributionFamily.ARCH,
+    "gentoo": DistributionFamily.GENTOO,
+    "funtoo": DistributionFamily.GENTOO,
+    "void": DistributionFamily.VOID,
+    "alpine": DistributionFamily.ALPINE,
+    "nixos": DistributionFamily.NIXOS,
+    "guix": DistributionFamily.NIXOS,
+    "solus": DistributionFamily.SOLUS,
+}
+
+
+def distribution_family(os_release_by_key: Mapping[str, str]) -> DistributionFamily:
+    """Return the family os-release describes: the one of its ID first, then of each word of ID_LIKE in order, otherwise UNKNOWN.
+
+    Ubuntu says ``ID_LIKE=debian`` and Linux Mint ``ID_LIKE="ubuntu debian"``, so both are Debian; Rocky Linux says
+    ``ID_LIKE="rhel centos fedora"`` and finds ``rhel`` before ``fedora``.
+    """
+    distribution_ids = [os_release_by_key.get(OS_RELEASE_ID_KEY, ""), *os_release_by_key.get(OS_RELEASE_ID_LIKE_KEY, "").split()]
+    for distribution_id in distribution_ids:
+        family = FAMILY_BY_OS_RELEASE_ID.get(distribution_id)
+        if family is not None:
+            return family
+    return DistributionFamily.UNKNOWN
+
+
+def read_os_release_or_nothing(read_os_release: Callable[[], Mapping[str, str]]) -> dict[str, str]:
+    """Read os-release, or nothing when the system has none, so that a missing file gives the unknown family instead of an error."""
+    try:
+        return dict(read_os_release())
+    except OSError:
+        return {}
+
+
+def session_distribution_family(read_os_release: Callable[[], Mapping[str, str]] = freedesktop_os_release) -> DistributionFamily:
+    """Return the family of the running system; never raises, and gives UNKNOWN on a system without os-release."""
+    return distribution_family(read_os_release_or_nothing(read_os_release))
+
+
+class DistributionRelease(Enum):
+    """A distribution whose install commands differ from the rest of its family; OTHER when the family alone says how to install."""
+
+    RHEL = "rhel"
+    """Red Hat Enterprise Linux, whose extra build repository, CodeReady Builder, is turned on through subscription-manager."""
+    CENTOS_STREAM = "centos"
+    """CentOS Stream, whose CRB repository is turned on through dnf config-manager."""
+    ROCKY_OR_ALMA = "rocky_or_alma"
+    """Rocky Linux and AlmaLinux, whose CRB repository is turned on by the ``crb`` script that epel-release installs."""
+    ORACLE_LINUX = "ol"
+    """Oracle Linux, which ships EPEL in Oracle's own repositories."""
+    GUIX = "guix"
+    """Guix System, told apart from NixOS, with which it shares its family, because it installs software through guix."""
+    OTHER = "other"
+    """Any other distribution, a derivative known only through ID_LIKE, or a system without os-release: the family alone says how to install."""
+
+
+# A key is an ID exactly as os-release writes it, never a word of ID_LIKE, so that a derivative that names ``rhel`` in
+# its ID_LIKE without its own ID here keeps the line of its family instead of borrowing one of these.
+RELEASE_BY_OS_RELEASE_ID: dict[str, DistributionRelease] = {
+    "rhel": DistributionRelease.RHEL,
+    "centos": DistributionRelease.CENTOS_STREAM,
+    "rocky": DistributionRelease.ROCKY_OR_ALMA,
+    "almalinux": DistributionRelease.ROCKY_OR_ALMA,
+    "ol": DistributionRelease.ORACLE_LINUX,
+    "guix": DistributionRelease.GUIX,
+}
+
+
+def distribution_release(os_release_by_key: Mapping[str, str]) -> DistributionRelease:
+    """Return the precise distribution os-release's exact ID names, otherwise OTHER.
+
+    The ID is compared exactly as written: ``RHEL`` in capitals, or a derivative found only through ID_LIKE, gives OTHER.
+    """
+    return RELEASE_BY_OS_RELEASE_ID.get(os_release_by_key.get(OS_RELEASE_ID_KEY, ""), DistributionRelease.OTHER)
+
+
+def session_distribution_release(read_os_release: Callable[[], Mapping[str, str]] = freedesktop_os_release) -> DistributionRelease:
+    """Return the precise distribution of the running system; never raises, and gives OTHER on a system without os-release."""
+    return distribution_release(read_os_release_or_nothing(read_os_release))

gitpane/system/network_folder.py

@@ -0,0 +1,46 @@
+"""Tell whether a Windows folder lives on a network share, from the drive table alone."""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import sys
+from typing import TYPE_CHECKING
+
+from gitpane.config import WINDOWS_PLATFORM
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+# GetDriveTypeW answers: DRIVE_UNKNOWN when the type cannot be told, DRIVE_REMOTE for a drive letter mapped to a network share.
+DRIVE_UNKNOWN_TYPE = 0
+DRIVE_REMOTE_TYPE = 4
+# A folder written \\server\share\... or //server/share/... is on a network share whatever the drive table says.
+UNC_PATH_PREFIXES = ("\\\\", "//")
+
+
+def windows_drive_type(root_dir: str, platform: str = sys.platform) -> int:
+    """Ask Windows what kind of drive a drive root is (a letter, a colon and a separator), from its own drive table, without contacting any server.
+
+    Other systems have no drive letters, so the type is unknown there.
+    """
+    if platform != WINDOWS_PLATFORM:
+        return DRIVE_UNKNOWN_TYPE
+    get_drive_type = ctypes.WinDLL("kernel32").GetDriveTypeW
+    get_drive_type.argtypes = [ctypes.c_wchar_p]
+    get_drive_type.restype = ctypes.c_uint
+    return get_drive_type(root_dir)
+
+
+def network_directory(directory: str, drive_type: Callable[[str], int] = windows_drive_type) -> bool:
+    """Tell whether a Windows folder lives on a network share: a UNC path, or a drive letter mapped to a share.
+
+    Looking for a file in such a folder can freeze the window for seconds while Windows waits for a disconnected
+    share, so searches run from the window skip these folders. Only the path and the drive table are read.
+    """
+    drive, _rest = os.path.splitdrive(directory)
+    if drive.startswith(UNC_PATH_PREFIXES):
+        return True
+    if not drive:
+        return False
+    return drive_type(drive + os.sep) == DRIVE_REMOTE_TYPE

gitpane/system/path_identity.py

@@ -0,0 +1,95 @@
+"""Identity of a path, decided in one place.
+
+Two paths name the same folder or file when they have the same ``canonical_path``. On macOS ``realpath`` keeps the
+letter case and the Unicode form that were typed, while a default macOS disk finds the same folder under another case
+and another form (composed or decomposed accents): the identity there is the spelling the file system itself gives.
+Windows and Linux keep ``normcase(realpath)``, so short names, network drives and links the user made are identified
+exactly as before.
+
+Never compare the bytes of a name read from the disk with the bytes of a path Git printed: compare them only after
+both went through ``canonical_path``.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import TYPE_CHECKING
+
+from gitpane.config import MACOS_PLATFORM
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+# MAXPATHLEN of macOS: the longest path the kernel gives back for an open descriptor.
+MACOS_MAXIMUM_PATH_BYTES = 1024
+
+
+def macos_disk_spelling(path: str) -> str:
+    """Return how an existing file or folder is spelled on a macOS disk, links resolved like realpath does.
+
+    No process is started: one open and one ``fcntl`` call, about the cost of a ``realpath``. Raises ``OSError`` when
+    the path does not exist or cannot be opened.
+    """
+    # fcntl does not exist on Windows; this function is only called on macOS.
+    import fcntl
+
+    # Workaround: F_GETPATH needs an open descriptor. O_EVTONLY asks for an event-only descriptor, so no data is read:
+    # a file evicted to the cloud is not downloaded, and O_NONBLOCK keeps a named pipe from blocking the open.
+    descriptor = os.open(path, os.O_EVTONLY | os.O_NONBLOCK | os.O_CLOEXEC)
+    try:
+        spelling = fcntl.fcntl(descriptor, fcntl.F_GETPATH, bytes(MACOS_MAXIMUM_PATH_BYTES))
+    finally:
+        os.close(descriptor)
+    return os.fsdecode(spelling.rstrip(b"\0"))
+
+
+def _deepest_disk_spelling(resolved_path: str, disk_spelling: Callable[[str], str]) -> str:
+    """Spell the deepest element of an absolute, link-free path that can be opened as on disk, and keep the rest as written.
+
+    When no element can be opened, the path is returned unchanged.
+    """
+    existing_path = resolved_path
+    remaining_names: list[str] = []
+    while True:
+        try:
+            spelling = disk_spelling(existing_path)
+        except OSError:
+            parent_path = os.path.dirname(existing_path)
+            if parent_path == existing_path:
+                return resolved_path
+            remaining_names.append(os.path.basename(existing_path))
+            existing_path = parent_path
+            continue
+        for remaining_name in reversed(remaining_names):
+            spelling = os.path.join(spelling, remaining_name)
+        return spelling
+
+
+def on_disk_path(path: str, platform: str = sys.platform, disk_spelling: Callable[[str], str] = macos_disk_spelling) -> str:
+    """Return the absolute path with links resolved, spelled as the disk spells it on macOS, as realpath spells it elsewhere.
+
+    On macOS a path whose end does not exist keeps that end as written after the disk spelling of its deepest existing
+    part; a part that cannot be read (permission refused) keeps its realpath spelling.
+    """
+    if platform != MACOS_PLATFORM:
+        return os.path.realpath(path)
+    if path:
+        try:
+            return disk_spelling(path)
+        except OSError:
+            pass
+    return _deepest_disk_spelling(os.path.realpath(path), disk_spelling)
+
+
+def canonical_path(path: str, platform: str = sys.platform, disk_spelling: Callable[[str], str] = macos_disk_spelling) -> str:
+    """Return the key that identifies a folder or file, so separators, letter case, Unicode form and links cannot hide a difference."""
+    return os.path.normcase(on_disk_path(path, platform, disk_spelling))
+
+
+def link_resolved_path(path: str) -> str:
+    """Resolve links and keep the typed spelling, to tell whether a path goes through a link by comparing it with the typed path.
+
+    Only for that check: it is not an identity, since on macOS another letter case or Unicode form stays different.
+    """
+    return os.path.normcase(os.path.realpath(path))

gitpane/system/private_tree_removal.py

@@ -0,0 +1,47 @@
+"""Remove a folder tree that GitPane created for its own private files, read-only entries included.
+
+Git writes its object files read-only. On Linux and macOS that does not stop their removal, which only needs a
+writable parent folder, but on Windows deleting a read-only file (or folder) fails with "Access is denied". This
+module only changes how a removal already decided by its caller is carried out: it removes exactly what
+``shutil.rmtree`` removes, keeps its handling of links and junctions (the link itself is removed, never what it
+points to), and must never be given a user's worktree or submodule.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+def _is_link(information: os.stat_result) -> bool:
+    """Tell whether an entry is a symbolic link or a Windows reparse point (junction), which is never made writable."""
+    reparse_point = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
+    return stat.S_ISLNK(information.st_mode) or bool(getattr(information, "st_file_attributes", 0) & reparse_point)
+
+
+def _retry_read_only_entry(function: Callable[[str], object], path: str, error: BaseException) -> None:
+    """Make one read-only entry writable, then remove it again; any other failure is raised unchanged."""
+    if not isinstance(error, PermissionError) or function not in (os.unlink, os.remove, os.rmdir):
+        raise error
+    try:
+        information = os.lstat(path)
+    except OSError:
+        raise error from None
+    if _is_link(information) or information.st_mode & stat.S_IWRITE:
+        raise error
+    # Workaround: Windows refuses to delete an entry that has the read-only attribute, which Git puts on every
+    # object file it writes. Clearing that attribute on this one entry (never on a link, checked just above) lets
+    # the removal that rmtree already decided go through; on Linux and macOS this point is not reached for Git's
+    # read-only files, since their removal only depends on the parent folder.
+    os.chmod(path, stat.S_IMODE(information.st_mode) | stat.S_IWRITE)
+    function(path)
+
+
+def remove_private_tree(directory: str) -> None:
+    """Remove a private folder of GitPane and everything inside it, including files Git made read-only."""
+    shutil.rmtree(directory, onexc=_retry_read_only_entry)

gitpane/system/process_program.py

@@ -0,0 +1,63 @@
+"""Name the program a process of this session runs, as /proc tells it.
+
+The name is first the base name of the target of ``/proc/<pid>/exe``. When the executable file was removed while the
+process runs, as a package update does, the kernel appends `` (deleted)`` to the link's target (proc(5)), and that
+suffix is taken off before the base name. The kernel refuses to read that link for a process that is not "dumpable",
+even one of the same user: a program started with file capabilities (seen with ``kwin_wayland``, which carries
+``cap_sys_nice``) or one that calls ``prctl(PR_SET_DUMPABLE, 0)`` (KeePassXC). For such a refusal the name is read from ``/proc/<pid>/comm`` instead, which
+the kernel lets any user read, even for a process of another user whose executable link it refuses; it is cut to 15
+characters, so the table of known programs also holds the cut names. ``comm`` can be changed by the program itself,
+but so can the owner of the Secret Service name, which any program of the user can take: the link gives no stronger
+guarantee.
+``cmdline`` is never read. A process that ended meanwhile, or a name that cannot be read at all, gives an empty name.
+Only Linux has these files; elsewhere they are missing and the name is empty.
+"""
+
+from __future__ import annotations
+
+import os
+import posixpath
+from typing import TYPE_CHECKING
+
+from gitpane.config import PROC_DIR
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+PROC_EXECUTABLE_BASENAME = "exe"
+# The file of /proc/<pid>/ that holds the program's command name, cut to 15 characters by the kernel.
+PROC_COMMAND_NAME_BASENAME = "comm"
+# What the kernel appends to the target of an executable link once the executable file was removed (proc(5)).
+DELETED_EXECUTABLE_SUFFIX = " (deleted)"
+
+
+def program_name_from_executable_link(link_text: str) -> str:
+    """Return the base name of the program an executable link names, without the suffix the kernel adds after a package update."""
+    return posixpath.basename(link_text.removesuffix(DELETED_EXECUTABLE_SUFFIX))
+
+
+def read_command_name_file(filename: str) -> str:
+    """Return the text of a /proc command name file; the kernel writes it as bytes, so a byte that is not UTF-8 is replaced rather than refused."""
+    with open(filename, encoding="utf-8", errors="replace") as command_name_file:
+        return command_name_file.read()
+
+
+def program_name_of_process(pid: int, read_link: Callable[[str], str] = os.readlink, read_text: Callable[[str], str] = read_command_name_file) -> str:
+    """Return the name of the program process ``pid`` runs, or an empty text when /proc does not tell it.
+
+    The executable link is read first; only a refusal to read it (a process that is not dumpable) falls back on the
+    command name, since any other error means the process is gone or /proc is missing. ``read_link`` and ``read_text``
+    read the files, so the tests can give any target, name or refusal without a real process.
+    """
+    # The files are paths of Linux's /proc, written in POSIX form whatever system builds them, hence posixpath.
+    process_dir = posixpath.join(PROC_DIR, str(pid))
+    try:
+        return program_name_from_executable_link(read_link(posixpath.join(process_dir, PROC_EXECUTABLE_BASENAME)))
+    except PermissionError:
+        pass
+    except OSError:
+        return ""
+    try:
+        return read_text(posixpath.join(process_dir, PROC_COMMAND_NAME_BASENAME)).strip()
+    except OSError:
+        return ""

gitpane/system/qt_folder.py

@@ -0,0 +1,38 @@
+"""Give a folder read from Qt the separator of the system it runs on.
+
+Qt names the folders it knows (desktop, documents, application data) with ``/`` on every system, Windows included,
+while Python's ``os.path.join`` adds the system's own separator: a path built from such a folder and shown to the user
+would mix both on Windows. A folder read from Qt therefore goes through here where it enters the application, before
+it is joined or shown.
+"""
+
+from __future__ import annotations
+
+import ntpath
+import posixpath
+
+from PySide6.QtCore import QStandardPaths
+
+from gitpane.config import WINDOWS_PLATFORM
+
+
+def native_folder_path(folder: str, platform: str) -> str:
+    """Write ``folder`` with the separator ``platform`` writes its own paths with.
+
+    Qt names the folders it knows with ``/`` on every system, Windows included, while Windows writes its paths with
+    ``\\``: the desktop folder as Qt gives it, joined to the shortcut's name, would show both separators in the line
+    Settings shows. Only the separators change, so the folder stays the same folder.
+    """
+    if platform != WINDOWS_PLATFORM:
+        return folder
+    return folder.replace(posixpath.sep, ntpath.sep)
+
+
+def writable_folder(location: QStandardPaths.StandardLocation, platform: str) -> str:
+    """Answer the folder Qt names for ``location``, written with the separator ``platform`` writes its own paths with.
+
+    A path built on such a folder then shows one kind of separator: the diagnostic log path shown in the error dialogs
+    and in the terminal, the file name a save dialog suggests, and the private folders GitPane keeps its recovery data
+    in.
+    """
+    return native_folder_path(QStandardPaths.writableLocation(location), platform)

gitpane/system/ready_channel_watch.py

@@ -0,0 +1,67 @@
+"""Watch the ready channel of a GitPane started detached, so its standard streams leave the gitpane command's pipes as soon as that command is gone.
+
+The gitpane command never writes on the channel: GitPane's end only becomes readable when the command's end closes,
+which happens when the command ends before GitPane said it is ready (its wait ran out, Ctrl+C, the terminal was
+closed). From then on nothing reads the pipes GitPane's standard streams point to, so they are moved to the null device
+at once, without waiting for the first window.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, QSocketNotifier
+
+from gitpane.system.terminal_detach import notify_ready, redirect_standard_streams_to_null
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+class ReadyChannelWatch(QObject):
+    """Hold GitPane's end of the ready channel until GitPane is ready or the gitpane command is gone, whichever comes first.
+
+    ``channel`` is the open descriptor while neither happened, then ``None``. The two functions it calls are given to
+    the constructor so tests can record them instead of touching the standard streams of their own process.
+    """
+
+    def __init__(
+        self,
+        channel: int,
+        parent: QObject | None = None,
+        *,
+        release_streams: Callable[[], None] = redirect_standard_streams_to_null,
+        send_ready_signal: Callable[[int, str], None] = notify_ready,
+    ) -> None:
+        """Start watching ``channel``, which becomes readable only when the command's end of it closes."""
+        super().__init__(parent)
+        self.channel: int | None = channel
+        self._release_streams = release_streams
+        self._send_ready_signal = send_ready_signal
+        self._notifier = QSocketNotifier(channel, QSocketNotifier.Type.Read, self)
+        self._notifier.activated.connect(self._release_after_command_left)
+
+    def _release_after_command_left(self, *_signal_arguments: object) -> None:
+        """Move the standard streams off the command's pipes and close the channel, the command being gone."""
+        if self.channel is None:
+            return
+        self._notifier.setEnabled(False)
+        self._release_streams()
+        try:
+            os.close(self.channel)
+        except OSError:
+            pass
+        self.channel = None
+
+    def send_ready(self, log_filename: str) -> None:
+        """Tell the waiting command that GitPane is ready, unless that command is already gone.
+
+        The notifier is turned off first, so it never watches a descriptor the ready signal has closed.
+        """
+        if self.channel is None:
+            return
+        self._notifier.setEnabled(False)
+        channel = self.channel
+        self.channel = None
+        self._send_ready_signal(channel, log_filename)