@codebend3r/che 1.1.0 → 1.2.1

package/README.md

@@ -5,7 +5,7 @@
 **A collection of helper scripts shared amongst computers, called by name from
 your shell, and browsable through one menu.**
 
-[![CI](https://github.com/codebend3r/che/actions/workflows/ci.yml/badge.svg)](https://github.com/codebend3r/che/actions/workflows/ci.yml)
+[![CI](https://github.com/codebend3r/che/actions/workflows/sanity-check.yml/badge.svg)](https://github.com/codebend3r/che/actions/workflows/sanity-check.yml)
 [![npm](https://img.shields.io/npm/v/%40codebend3r%2Fche)](https://www.npmjs.com/package/@codebend3r/che)
 ![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)
 ![Dependencies: stdlib only](https://img.shields.io/badge/dependencies-stdlib%20only-brightgreen)
@@ -79,8 +79,8 @@ git clone https://github.com/codebend3r/che.git ~/Developer/git/che
 ~/Developer/git/che/install.sh
 ```
 
-Or in one line, which clones for you (into `~/Developer/git/shell-functions`,
-or wherever `CHE_HOME` points):
+Or in one line, which clones for you (into `~/Developer/git/che`, or wherever
+`CHE_HOME` points):
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/codebend3r/che/main/install.sh | bash
@@ -103,7 +103,9 @@ which opens a first-run wizard: it lists the shells it found and the rc files
 it would touch, asks whether to add a `che` on `PATH` and whether to keep the
 completion chimes, offers to remove hand-written wrappers left over from before
 the installer existed, and reports any missing external tool (offering to
-`brew install` them when Homebrew is present).
+`brew install` them when Homebrew is present). A question already answered on
+the command line (`--no-sounds`, `--no-path-shim`, `--replace-legacy`,
+`--install-deps`) is not asked again.
 
 <div align="center">
 <img src="first-run.png" alt="The first run screen: che is not installed in this shell yet, offering to install, open the menu, or quit" width="700">
@@ -118,7 +120,7 @@ Skip the wizard:
 ./install.sh --yes --shells=zsh,fish  # or the ones you name
 ./install.sh --dry-run                # report what would change, write nothing
 ./install.sh --yes --replace-legacy   # also remove pre-che hand-written wrappers
-./install.sh --print                  # print the rc block, install nothing
+./install.sh --print                  # print the exact rc block, install nothing
 ```
 
 Every rc file is copied to `~/.config/che/backups/` before it is edited.
@@ -139,9 +141,9 @@ dotfiles:
 ```zsh
 # >>> che shell functions >>>
 # Managed by `che install` (che 1.0.0). Edits here are overwritten.
-export CHE_HOME=/Users/you/Developer/git/shell-functions
+export CHE_HOME=/Users/you/Developer/git/che
 export CHE_PYTHON=/opt/homebrew/bin/python3
-[ -r /Users/you/Developer/git/shell-functions/shell/che.zsh ] && . /Users/you/Developer/git/shell-functions/shell/che.zsh
+[ -r /Users/you/Developer/git/che/shell/che.zsh ] && . /Users/you/Developer/git/che/shell/che.zsh
 case ":$PATH:" in *":/Users/you/.local/bin:"*) ;; *) PATH="/Users/you/.local/bin:$PATH" ;; esac
 # <<< che shell functions <<<
 ```
@@ -164,7 +166,7 @@ python3 exists. `brew install python@3.13` if none does.
 
 ```sh
 che uninstall           # remove the block, the shim and the completions
-che uninstall --purge   # also delete ~/.config/che
+che uninstall --purge   # also delete ~/.config/che and the menu's input history
 ```
 
 The repo itself is left alone; delete the directory to finish.
@@ -214,13 +216,13 @@ have used, and `che help <command>` prints that script's own `--help`.
 | Command | Does | Preview |
 | --- | --- | --- |
 | **Git** | *Branch hygiene, worktrees and GitHub Actions* | |
-| `all-actions` | GitHub Actions status for every open PR you authored |  |
+| `all-actions` | GitHub Actions status for every open PR and every default branch |  |
 | `all-actions-watch` | Same as all-actions, refreshed on an interval |  |
 | `checkout-my-branches` | Check out recent remote branches you authored that aren't local yet |  |
 | `clean-stale-branches` | Delete local branches whose upstream is gone | `clean-stale-branches-dr` |
 | `prune-worktrees` | Remove every linked worktree, then prune stale admin records | `prune-worktrees-dr` |
-| `sync-all-branches` | Push every worktree, collapse the pushed ones, then tidy branches | `sync-all-branches-dr` |
-| `update-from-origin` | Same as sync-all-branches but never pushes: fetch, collapse, rebase |  |
+| `sync-all-branches` | Update every branch and worktree, preserving locks and local work | `sync-all-branches-dr` |
+| `update-from-origin` | Alias of sync-all-branches | `--dry-run` |
 | `update-local-branches` | Rebase every local branch that has an upstream onto origin | `--dry-run` |
 | **Video** | *Codecs, renaming, dedupe and metadata* | |
 | `show-codecs` | Report media files outside the Direct Play codec/container set |  |
@@ -316,9 +318,16 @@ where you copy one machine's rc file to another.
 ```
 bin/
   art.py              the wordmark and the face beside it, for every screen
-  che.py              the dispatcher and the interactive menu
+  che.py              the dispatcher, and the loop that runs what the menu picks
   commands.py         the command manifest: the source of truth for everything
-  install.py          installer, first-run wizard, doctor, self-update
+  doctor.py           `che doctor`: every check on the install
+  gitutils.py         shared git helpers: worktrees, main branch, hook skipping
+  install.py          installer, first-run wizard, self-update, uninstall
+  machine.py          shells, rc file paths, python, config: facts about the machine
+  media.py            shared ffprobe helpers for the video scripts
+  menu.py             the menu's list, keys and drawing
+  nas.py              the NAS drive table and SMB mounting, for the drive scripts
+  rcfile.py           edits to rc files: the che block and old hand-written wrappers
   shellgen.py         renders the wrappers, completions and README tables
   tui.py              terminal primitives: raw input, frame buffer, prompts
   utils.py            shared library: logging, arg parsing, subprocess, files
@@ -351,22 +360,45 @@ Every script follows the same shape, described in full at the top of
   point, so pointing a delete tool at `~/media -> /Volumes/...` used to be a
   silent no-op. Pass the real path to act on it.
 
-## Syncing branches and worktrees
+## Syncing branches
 
 ```sh
-sync-all-branches       # push every worktree, collapse the pushed ones, then sync
-sync-all-branches-dr    # preview only
-update-from-origin      # same, but --no-push: only collapses already-pushed worktrees
+sync-all-branches       # update branches and worktrees, keeping locks and local work
+sync-all-branches-dr    # preview cached remote refs; no fetch or changes
+update-from-origin     # alias of sync-all-branches
 ```
 
-A worktree is a temporary workspace. Once its commits are on origin the
-directory holds nothing the remote doesn't, so `sync-all-branches` pushes it,
-removes the directory, and leaves the branch behind as an ordinary local
-branch. That also clears the `already used by worktree` pin, which is what
-otherwise makes `main` un-checkoutable and stale branches un-deletable.
-
-A worktree is only collapsed when it is **clean** *and* **fully pushed**.
-Anything else is kept and reported with the reason.
+Fetches once and rebases every local branch onto its upstream, falling back to
+`origin/<branch>` when no upstream is configured. Branches in existing
+worktrees, including locked ones, update **inside their own checkout**. Dirty
+tracked and untracked work is temporarily stashed and restored with its staged
+state; unrelated existing stashes survive. Nested registered worktrees are
+excluded from their parent's stash. Dirty submodules and existing Git operations
+are reported and left alone.
+
+It **never pushes, hard resets or deletes local branches**, and preserves every
+existing worktree directory, lock and checkout, including the caller's branch.
+Unoccupied branches use temporary worktrees that are removed after updating.
+New origin branches authored by you become local tracking branches without
+switching HEAD. Missing upstreams are reported, not treated as proof of a merge;
+use `clean-stale-branches` separately when you want branch cleanup.
+
+Rebase conflicts are aborted and reported while other branches continue. If
+restoring WIP conflicts, the exact recovery stash is retained and its ID and
+worktree path are printed. A blocked branch makes the command exit nonzero even
+when other branches updated. Local-only branches are reported without inventing
+a remote target. Ahead counts may remain because local commits are kept; clearing
+them would require pushing or discarding work. Avoid concurrent edits or Git
+operations while the sync temporarily saves WIP.
+
+The `-dr` preview does not fetch and only inspects cached remote refs. It changes
+no branches, working files, locks or stashes. Legacy `--no-push` and
+`--keep-locked` flags are still accepted for compatibility.
+
+Like the other branch scripts (`clean-stale-branches`, `update-local-branches`,
+`checkout-my-branches`, `prune-worktrees`), sync retains che's existing policy of
+pointing `core.hooksPath` at `/dev/null` for its Git commands so bookkeeping does
+not run repository hooks.
 
 ## External tools
 
@@ -408,7 +440,7 @@ This repo uses [Bun](https://bun.sh) as its task runner and
 ```sh
 bun run test        # pytest
 bun run generate    # rewrite shell/ and this README's tables from the manifest
-bun run ci          # ruff + syntax + exec bits + shebangs + generated files + pytest
+bun run ci          # ruff + exec bits + shebangs + pytest (stale generated files fail it)
 ```
 
 Neither `pytest` nor `ruff` needs to be installed globally: the scripts shell

package/bin/art.py

@@ -56,28 +56,20 @@ INDENT = "  "
 GAP = 1
 
 
-def logo_lines() -> list[str]:
-    return LOGO.strip("\n").splitlines()
+LOGO_LINES: tuple[str, ...] = tuple(LOGO.strip("\n").splitlines())
+FACE_LINES: tuple[str, ...] = tuple(FACE.strip("\n").splitlines())
 
+HEIGHT = len(FACE_LINES)
+WIDTH = len(INDENT) + max(len(line) for line in FACE_LINES)
 
-def face_lines() -> list[str]:
-    return FACE.strip("\n").splitlines()
 
+def _paint(lines: Sequence[str], colors: tui.Palette, indent: str = "") -> list[str]:
+    return [f"{colors.bright_magenta}{indent}{line}{colors.reset}" for line in lines]
 
-HEIGHT = len(face_lines())
-WIDTH = len(INDENT) + max(len(line) for line in face_lines())
 
-
-def wordmark(colors: tui.Palette | None = None) -> list[str]:
+def wordmark(colors: tui.Palette) -> list[str]:
     """The block letters, coloured the way every screen prints them."""
-    colors = colors or tui.palette()
-    return [f"{colors.bright_magenta}{line}{colors.reset}" for line in logo_lines()]
-
-
-def face(colors: tui.Palette | None = None) -> list[str]:
-    """The face, indented to line up with the wordmark and in the same colour."""
-    colors = colors or tui.palette()
-    return [f"{colors.bright_magenta}{INDENT}{line}{colors.reset}" for line in face_lines()]
+    return _paint(LOGO_LINES, colors)
 
 
 def compose(left: Sequence[str], right: Sequence[str], *, gap: int = GAP) -> list[str]:
@@ -105,17 +97,27 @@ def fits(right: Sequence[str], columns: int) -> bool:
     return WIDTH + GAP + right_width <= columns
 
 
-def banner(
-    right: Sequence[str], *, columns: int | None = None, colors: tui.Palette | None = None
-) -> list[str]:
+def banner(right: Sequence[str], *, colors: tui.Palette, columns: int | None = None) -> list[str]:
     """The face with ``right`` beside it, or ``right`` alone when it would not fit.
 
     ``right`` is normally the wordmark plus whatever a screen wants under it (a
     subtitle, the command count). It comes back untouched, indent and all, on a
     terminal too narrow for both, so every caller keeps working at 40 columns.
+    The face is indented to line up with the wordmark and painted in its colour.
     """
     if columns is None:
         columns = tui.size()[0]
     if not fits(right, columns):
         return list(right)
-    return compose(face(colors), right)
+    return compose(_paint(FACE_LINES, colors, INDENT), right)
+
+
+def print_logo(subtitle: str = "") -> None:
+    """The face beside the wordmark, with ``subtitle`` under the letters."""
+    colors = tui.palette()
+    right = wordmark(colors)
+    if subtitle:
+        right.append(f"  {colors.grey}{subtitle}{colors.reset}")
+    for line in banner(right, colors=colors):
+        print(line)
+    print()

package/bin/branchsync.py

@@ -0,0 +1,324 @@
+"""Non-destructive branch/worktree synchronization for sync-all-branches.
+
+Unlike the old delegated cleanup, sync preserves every checkout and local branch.
+Only disposable worktrees created here may be removed. Git locks need no special
+handling: they prevent removal/pruning, not a rebase inside the locked checkout.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from gitutils import Worktree, local_branches, worktrees
+from utils import info, run, run_output, success, warning
+
+_OPERATION_FILES = (
+    "rebase-merge",
+    "rebase-apply",
+    "MERGE_HEAD",
+    "CHERRY_PICK_HEAD",
+    "REVERT_HEAD",
+    "BISECT_START",
+)
+
+
+def git_path(path: Path, name: str) -> Path:
+    result = Path(run_output(["git", "rev-parse", "--git-path", name], cwd=path))
+    return result if result.is_absolute() else path / result
+
+
+def operation_branch(path: Path) -> str:
+    """A rebase/bisect detaches HEAD but still reserves its original branch."""
+    for name in ("rebase-merge/head-name", "rebase-apply/head-name", "BISECT_START"):
+        file = git_path(path, name)
+        if file.is_file():
+            return file.read_text().splitlines()[0].removeprefix("refs/heads/")
+    return ""
+
+
+def in_progress(path: Path) -> bool:
+    return any(git_path(path, name).exists() for name in _OPERATION_FILES)
+
+
+@dataclass
+class BranchSync:
+    root: Path
+    dry_run: bool
+    updated: list[str] = field(default_factory=list)
+    current: list[str] = field(default_factory=list)
+    local_only: list[str] = field(default_factory=list)
+    restored: list[str] = field(default_factory=list)
+    blocked: list[str] = field(default_factory=list)
+    trees: list[Worktree] = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.trees = worktrees(self.root)
+
+    def block(self, branch: str, reason: str) -> None:
+        message = f"{branch}: {reason}"
+        self.blocked.append(message)
+        warning(f"  ❌ {message}")
+
+    def occupied(self) -> dict[str, Path]:
+        result: dict[str, Path] = {}
+        for tree in self.trees:
+            path = Path(tree.path)
+            branch = tree.branch
+            if not branch and path.is_dir():
+                branch = operation_branch(path)
+            if branch:
+                result[branch] = path
+            else:
+                info(f"  ℹ️ Detached worktree unchanged (no upstream): {path}")  # noqa: RUF001
+        return result
+
+    def pathspecs(self, path: Path) -> list[str]:
+        """Never stash another registered checkout nested inside this one.
+
+        Restrict status and stash by the same literal pathspecs, so untracked
+        siblings still count as WIP while a nested worktree stays untouched.
+        """
+        specs = ["."]
+        for tree in self.trees:
+            nested = Path(tree.path)
+            if nested != path and nested.is_relative_to(path):
+                specs.append(f":(exclude,literal){nested.relative_to(path).as_posix()}")
+        return specs
+
+    def dirty(self, path: Path) -> bool:
+        return bool(
+            run_output(
+                [
+                    "git",
+                    "status",
+                    "--porcelain",
+                    "-z",
+                    "--untracked-files=all",
+                    "--",
+                    *self.pathspecs(path),
+                ],
+                cwd=path,
+            )
+        )
+
+    def has_ref(self, ref: str) -> bool:
+        return (
+            run(
+                ["git", "show-ref", "--verify", "--quiet", ref],
+                cwd=self.root,
+                check=False,
+                capture=True,
+            ).returncode
+            == 0
+        )
+
+    def includes(self, branch: str, upstream: str) -> bool:
+        result = run(
+            ["git", "merge-base", "--is-ancestor", upstream, f"refs/heads/{branch}"],
+            cwd=self.root,
+            check=False,
+            capture=True,
+        )
+        if result.returncode not in (0, 1):
+            raise subprocess.CalledProcessError(
+                result.returncode, result.args, stderr=result.stderr
+            )
+        return result.returncode == 0
+
+    def save_wip(self, branch: str, path: Path) -> str:
+        if not self.dirty(path):
+            return ""
+        # A superproject stash cannot preserve dirty submodule working copies.
+        submodules = run(
+            ["git", "submodule", "foreach", "--quiet", "--recursive", "git status --porcelain"],
+            cwd=path,
+            check=False,
+            capture=True,
+        )
+        if submodules.returncode or submodules.stdout:
+            raise OSError(f"dirty/unreadable submodule in {path}; left untouched")
+        before = run_output(["git", "rev-parse", "--verify", "refs/stash"], cwd=path, check=False)
+        run(
+            [
+                "git",
+                "stash",
+                "push",
+                "--include-untracked",
+                "--message",
+                f"che sync-all-branches: {branch}",
+                "--",
+                *self.pathspecs(path),
+            ],
+            cwd=path,
+        )
+        oid = run_output(["git", "rev-parse", "--verify", "refs/stash"], cwd=path)
+        if not oid or oid == before:
+            raise OSError(
+                f"could not verify a new recovery stash in {path}; inspect git stash list"
+            )
+        info(f"  🧺 Recovery stash for {branch} in {path}: {oid}")
+        if self.dirty(path):
+            raise OSError(f"worktree remains dirty; left untouched, recovery stash {oid} in {path}")
+        return oid
+
+    def restore_wip(self, branch: str, path: Path, oid: str) -> bool:
+        if not oid:
+            return True
+        # Worktrees share refs/stash. Never pop the latest entry or drop a
+        # recovery copy until both working-copy and index restoration succeed.
+        if run(["git", "stash", "apply", "--index", oid], cwd=path, check=False).returncode:
+            self.block(
+                branch, f"WIP restoration conflicted in {path}; recovery stash retained: {oid}"
+            )
+            return False
+        entries = run_output(["git", "stash", "list", "--format=%gd%x01%H"], cwd=path)
+        matching = next(
+            (
+                ref
+                for line in entries.splitlines()
+                for ref, sha in [line.split("\x01")]
+                if sha == oid
+            ),
+            "",
+        )
+        if (
+            not matching
+            or run(["git", "stash", "drop", "--quiet", matching], cwd=path, check=False).returncode
+        ):
+            self.block(branch, f"WIP restored in {path}, but recovery stash not dropped: {oid}")
+            return False
+        self.restored.append(branch)
+        return True
+
+    def sync_branch(self, branch: str, upstream: str, occupied: dict[str, Path]) -> None:
+        path = occupied.get(branch)
+        if path is not None:
+            if not path.is_dir():
+                self.block(branch, f"worktree unavailable: {path}")
+                return
+            if in_progress(path):
+                self.block(branch, f"operation in progress in {path}; left untouched")
+                return
+        if self.includes(branch, upstream):
+            info(f"  = Up to date: {branch} (local commits kept){f' in {path}' if path else ''}")
+            self.current.append(branch)
+            return
+        if self.dry_run:
+            info(
+                f"  🌵 Would update {branch} from {upstream}{f' in {path}' if path else ''}; stash/restore WIP if needed"
+            )
+            return
+
+        temporary: Path | None = None
+        oid = ""
+        try:
+            if path is None:
+                temporary = Path(tempfile.mkdtemp(prefix="che-sync-"))
+                path = temporary / "checkout"
+                run(["git", "worktree", "add", "--quiet", str(path), branch], cwd=self.root)
+            oid = self.save_wip(branch, path)
+            info(f"⬇️ Rebasing {branch} in {path} (lock preserved)")
+            # DELIBERATE DIVERGENCE: one fetched snapshot instead of pull's
+            # per-branch fetch. Disable autostash/updateRefs so Git cannot
+            # compete with our exact WIP recovery or move unrelated branches.
+            rebased = (
+                run(
+                    [
+                        "git",
+                        "-c",
+                        "rebase.autoStash=false",
+                        "-c",
+                        "rebase.updateRefs=false",
+                        "rebase",
+                        "--no-autostash",
+                        upstream,
+                    ],
+                    cwd=path,
+                    check=False,
+                ).returncode
+                == 0
+            )
+            if not rebased:
+                warning(f"  ❌ Rebase failed for {branch} in {path}")
+                if in_progress(path):
+                    # Abort only the rebase we started. Failure to abort is
+                    # fatal: applying WIP or continuing is no longer safe.
+                    abort = run(["git", "rebase", "--abort"], cwd=path, check=False)
+                    if abort.returncode:
+                        warning(f"STOP: cannot abort in {path}; recovery stash: {oid or 'none'}")
+                        raise SystemExit(1)
+                self.block(branch, f"rebase failed in {path}; original commits retained")
+            restored = self.restore_wip(branch, path, oid)
+            if rebased and restored:
+                if self.includes(branch, upstream):
+                    self.updated.append(branch)
+                    success(f"  ✅ Updated: {branch}")
+                else:
+                    self.block(branch, "verification failed: fetched upstream not included")
+        except (subprocess.CalledProcessError, OSError) as exc:
+            self.block(
+                branch, f"{exc}; inspect {path}; recovery stash: {oid or 'see git stash list'}"
+            )
+        except KeyboardInterrupt:
+            warning(
+                f"Interrupted in {path}; inspect status before resuming. Recovery stash: {oid or 'see git stash list'}"
+            )
+            raise
+        finally:
+            # Never use TemporaryDirectory here: its automatic recursive
+            # deletion would erase files if a hook or recovery left a dirty tree.
+            if temporary is not None:
+                if not (temporary / "checkout").exists():
+                    temporary.rmdir()
+                elif (
+                    not in_progress(temporary / "checkout")
+                    and run(
+                        ["git", "worktree", "remove", str(temporary / "checkout")],
+                        cwd=self.root,
+                        check=False,
+                    ).returncode
+                    == 0
+                ):
+                    temporary.rmdir()
+                else:
+                    self.block(
+                        branch,
+                        f"temporary worktree retained for inspection: {temporary / 'checkout'}",
+                    )
+
+    def update(self) -> None:
+        occupied = self.occupied()
+        for branch, upstream in local_branches("upstream", cwd=self.root):
+            if not upstream and self.has_ref(f"refs/remotes/origin/{branch}"):
+                upstream = f"refs/remotes/origin/{branch}"
+            if not upstream:
+                info(f"  ℹ️ Local only: {branch} (no remote counterpart)")  # noqa: RUF001
+                self.local_only.append(branch)
+                continue
+            if not self.has_ref(upstream):
+                self.block(branch, f"upstream gone: {upstream}; branch and worktree retained")
+                continue
+            try:
+                self.sync_branch(branch, upstream, occupied)
+            except (subprocess.CalledProcessError, OSError) as exc:
+                self.block(branch, f"preflight failed: {exc}")
+
+    def summary(self, tracked: list[str]) -> None:
+        success("═══ summary ═══")
+        for label, names in (
+            ("Updated", self.updated),
+            ("Up to date", self.current),
+            ("Tracked new", tracked),
+            ("Local only", self.local_only),
+            ("WIP restored", self.restored),
+        ):
+            info(f"{label}: {len(names)} ({', '.join(names)})")
+        info(f"Blocked: {len(self.blocked)}")
+        for reason in self.blocked:
+            warning(f"  • {reason}")
+        info(
+            "Caller checkout, existing worktree paths, locks and local commits preserved. Nothing pushed."
+        )