From 85523b63ad80894a1dfb3f4ebd9fc7484ab0e614 Mon Sep 17 00:00:00 2001
From: Pierre Kisters <1524059+lhns@users.noreply.github.com>
Date: Thu, 1 Oct 2026 23:25:10 +0200
Subject: [PATCH] Docs: lazy Nix removal, install --clone with the template's
 credentials

README: what --clone does for a private repository (the template's
gh/store helpers, the gh auth login offer, keep those lines in your
config, what gets cloned into and that re-running continues), the
git/gh lines in the usage example, and that uninstall no longer waits
for programs from the Nix store. docs/cleanup.md: the clone steps, the
untouched-template marker, and the LazyUnmount= drop-in.
---
 README.md           | 45 ++++++++++++++++++++++++-------------
 docs/cleanup.md     | 55 +++++++++++++++++++++++++++++----------------
 docs/development.md |  2 +-
 3 files changed, 67 insertions(+), 35 deletions(-)

diff --git a/README.md b/README.md
index 8153d16..5717745 100644
--- a/README.md
+++ b/README.md
@@ -92,10 +92,18 @@ it just switches again (`--yes` answers every question). Afterwards edit
 
 Your own config in a git repository: `--clone <git-url>` clones it into
 `~/nix-config` (`--dir <path>`, branch `--ref <branch>`) and installs it like
-`--flake <dir>`; an existing clone of the same repository is reused (after
-asking, `git pull --ff-only`). URLs: `git@github.com:owner/repo`,
-`https://...` or `github:owner/repo`; a private repository needs an SSH URL
-with your key or HTTPS credentials (e.g. `gh auth login`).
+`--flake <dir>`. URLs: `git@github.com:owner/repo`, `https://...` or
+`github:owner/repo`. Without a Home Manager configuration it first activates
+the template, whose git credential helpers then clone a private repository:
+your GitHub CLI login (`~/.config/gh`, kept by `uninstall`) or
+`~/.git-credentials`; git never asks for a password. If the clone fails, it
+offers `gh auth login` (browser or one-time code, works with 2FA); an SSH URL
+uses your key instead. The clone then replaces the template. Keep the
+template's `programs.git`/`programs.gh` lines (see [Usage](#usage)) in your
+config, or the helpers go with the switch to it. Only a missing
+`~/nix-config` or the unchanged template is replaced by the clone; anything
+else there is used as it is, without cloning. So re-running continues where
+it stopped (after a failed switch it just switches again).
 
 ```sh
 curl -fsSL https://steam-frame-nix.lhns.de | bash -s -- install --clone git@github.com:owner/my-config
@@ -188,6 +196,12 @@ these two files ([`template/`](template), with more comments):
   home.stateVersion = "26.05";
   targets.genericLinux.enable = true;
   programs.home-manager.enable = true;
+  programs.git = {                    # SteamOS's git, Home Manager writes its config
+    enable = true;
+    package = null;
+    settings.credential.helper = "store";   # ~/.git-credentials
+  };
+  programs.gh.enable = true;          # github.com credentials: gh auth login
 
   steamFrame = {
     keyboard.layout = "de";               # XKB layout, Steam session
@@ -449,11 +463,11 @@ versions left: [docs/cleanup.md](docs/cleanup.md).
 - `experimental-features = nix-command flakes` in `~/.config/nix/nix.conf`
   if Nix was already there without flakes;
 - `~/nix-config` (your configuration, a git repository, from the template
-  with your user name filled into `flake.nix`) and the link
-  `~/.config/home-manager` to it, unless that exists or `--flake` is given
-  (with `--flake <dir>` or `--clone`, the link to that directory unless it
-  exists); uninstall removes the link, never the configuration (a clone
-  included);
+  with your user name filled into `flake.nix`; with `--clone` only until the
+  clone replaces it) and the link `~/.config/home-manager` to it, unless that
+  exists or `--flake` is given (with `--flake <dir>` or `--clone`, the link
+  to that directory unless it exists); uninstall removes the link, never
+  the configuration (a clone included);
 - dotfiles in Home Manager's way, renamed to `*.hm-backup-<time>` (kept);
 - `~/.local/state/home-manager`, `~/.local/state/nix` (profiles,
   generations), `~/.nix-profile`, `~/.nix-defexpr`, `~/.nix-channels`,
@@ -500,12 +514,13 @@ stops Home Manager's user services (reverting the UI patches), runs
 `cleanup --all`, runs `home-manager uninstall`, then removes Nix and the
 per-user Nix state (see [Set up by install.sh](#set-up-by-installsh)). If
 SteamVR is running, its key is restored when SteamVR stops (the closing
-message says so). Nix can't be removed while programs started from the Nix
-store run: `uninstall` lists them and waits; close them or run it right
-after a reboot. If Nix stays (in use, `--yes`, or its uninstaller failed),
-the rest still runs (the `~/.config/home-manager` link goes) except the
-per-user Nix state, and the closing message says to run `uninstall` again. Your configuration, `*.hm-backup-*` files, app data and
-Flatpaks stay.
+message says so). Programs started from the Nix store (often the Steam
+session itself) keep running until you log out or reboot: `uninstall` lists
+them and removes Nix without waiting. If Nix's uninstaller fails, the rest
+still runs (the `~/.config/home-manager` link goes) except the per-user Nix
+state, and the closing message says to reboot and run `uninstall` again.
+Your configuration, `*.hm-backup-*` files, app data, Flatpaks and the GitHub
+CLI login (`~/.config/gh`) stay.
 
 To drop steam-frame-nix from a Home Manager configuration you keep, first
 run `steam-frame-nix-cleanup --all`, then remove it and switch. Or set Home
diff --git a/docs/cleanup.md b/docs/cleanup.md
index 6a8aa58..fb142fc 100644
--- a/docs/cleanup.md
+++ b/docs/cleanup.md
@@ -45,11 +45,28 @@ What `install.sh install` sets up is listed in the README under
 desktop can't reach it with its own environment) and uses the installed
 `home-manager` if there is one, else Home Manager's `master`.
 
-`install --clone` takes SteamOS' `git`, else `nix run nixpkgs#git`. An
-existing directory is reused only if it is the top of a clone whose
-`origin` is the same repository: URLs are compared as lower-case
-host/path without `.git` (so `git@host:o/r`, `ssh://git@host/o/r` and
-`https://host/o/r.git` match), and with `--ref` it must be on that branch.
+`install --clone` takes SteamOS' `git`, else `nix run nixpkgs#git`, always
+with `GIT_TERMINAL_PROMPT=0`. Each step checks whether an earlier run did it
+(Nix works: not installed). The target directory is cloned into only when it
+is missing, empty or the untouched template: `create_config` writes the hash
+of the configuration's files (without `.git`) to
+`.git/steam-frame-nix-template`, and the template counts as untouched while
+the files still match and there is at most one commit. Anything else (the
+clone of an earlier run, a changed template, any other directory) is used
+as it is: no clone, `--ref` ignored, straight to the switch.
+
+Into an empty target, the template comes first, but only without a Home
+Manager configuration (no `~/.config/home-manager`); with one, git clones
+with that configuration's helpers. The switch to the template is skipped
+when it is linked, Home Manager is installed and git has a credential
+helper. The clone goes to `.<dir>.clone.XXXXXX` next to the target (removed
+if it fails, the template stays), replaces the template (checked unchanged
+again), then Home Manager switches to it. A failed switch leaves the clone,
+so a rerun only switches. `gh auth login --hostname github.com
+--git-protocol https`, with the Home Manager profile's `gh`, is offered only
+for `https://github.com/` URLs and with a terminal. Tests: section G of
+`modules/cleanup/check.nix` (a logging git, a fake nix,
+`STEAM_FRAME_NIX_TTY` instead of `/dev/tty`).
 
 `restart-check` (run by the session module's activation after
 `steamFrameUserServices`, and by `install` at its end) compares the
@@ -60,17 +77,17 @@ with the debugger drop-in, looks for a listener on port 8087 in
 `/proc/net/tcp*`. Tests use `STEAM_FRAME_NIX_PROC` and
 `STEAM_FRAME_NIX_CGROUP` (section F of `modules/cleanup/check.nix`).
 
-`uninstall` removes Nix with nix-installer, which fails when it can't
-unmount `/nix` (`systemctl stop nix.mount`). Before that it scans `/proc`
-for processes using `/nix`: their `exe`, `cwd`, `root` or an `fd` links into
-`/nix`, or `maps` names a file there (e.g. an app started before the
-uninstall that mapped Home Manager's `mime.cache`). Only the user's own
-processes are readable; the Nix daemon is nix-installer's to stop. Skipped:
-the script itself, its subshells (descendants) and its process group (the
-`curl | bash` pipeline). Its ancestors are listed with a hint to run
-`uninstall` from another terminal. Nothing is killed: it asks to close them
-and re-checks on Enter, or (`--yes`, no terminal) stops before Nix. A bash
-from the Nix store re-executes the script with `/usr/bin/bash` first, and
-nix-installer runs from a root-owned copy in `/tmp`. The check uses
-`STEAM_FRAME_NIX_PROC` as a fake `/proc` (section H of
-`modules/cleanup/check.nix`).
+`uninstall` removes Nix with nix-installer (from a root-owned copy in
+`/tmp`), whose `systemctl stop nix.mount` fails while a process uses `/nix`,
+and in the Steam session some always do until logout (e.g. Steam and
+xdg-desktop-portal, once they mapped a file from the store). So first a
+runtime drop-in, `/run/systemd/system/nix.mount.d/50-steam-frame-nix-lazy-unmount.conf`
+with `LazyUnmount=yes`, makes that stop detach `/nix` (`umount -l`): the
+programs keep their open files until they exit. The drop-in is removed
+afterwards. Before that, for information, it lists the processes whose
+`exe`, `cwd`, `root` or an `fd` links into `/nix`, or whose `maps` names a
+file there (only the user's own are readable), except the script itself,
+its subshells and its process group (the `curl | bash` pipeline). Tests:
+section H of `modules/cleanup/check.nix` (`STEAM_FRAME_NIX_PROC` as a fake
+`/proc`, `STEAM_FRAME_NIX_SYSTEM_RUNTIME` for the drop-in, a logging
+nix-installer).
diff --git a/docs/development.md b/docs/development.md
index b07951c..d00c206 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -49,7 +49,7 @@ modules/
   cleanup.nix                  switch: `cleanup --orphans`; steam-frame-nix-cleanup on PATH
   cleanup/package.nix          build: install.sh as a command (cleanup, steamvr-debugger-arm, restart-check)
   cleanup/check.nix            test: install.sh cleanup and restart-check on fake home/runtime dirs,
-                               install --clone against local bare repos, uninstall on a fake /proc
+                               install (template, --clone) against local bare repos, uninstall on a fake /proc
   portal.nix                   Steam session portal config (session.portalFix)
   portal/check.nix             test: KDE FileChooser on by default, absent when disabled
   applications-menu.nix        applications.menu link for KDE apps (session.applicationsMenu)