From 0d8cccdbb509656afb9e185397fb503bb7e43294 Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Sat, 11 Jul 2026 11:10:17 +0200 Subject: Document --setup-repo and --update Add a Repository setup and refresh section to README covering the two modes, SBO_RSYNC_URL, SBO_PERSONAL_TREES, and shadow self-healing. Extend CLAUDE.md's architecture list with the tree-lifecycle functions, the CONFIG-block description, and the verified-status notes for the untested rsync/git/shadow paths. Co-Authored-By: Claude Opus 4.8 --- README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index b361e46..aa14781 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,58 @@ The base is kept patched automatically on each run: when the mirror's ChangeLog head differs from the recorded marker, new packages from `patches/packages/` are applied to the local base via `upgradepkg`. +## Repository setup and refresh + +Two config vars manage the SBo tree itself, on top of the read-in-place lookup +described above: + +- **`SBO_RSYNC_URL`** - rsync source for the tree, the same source `sbopkg` + uses (e.g. `slackbuilds.org::slackbuilds/15.0`). This is the public + slackbuilds.org rsync tree, distinct from `LOCAL_MIRROR_15` (the NFS package + mirror). Leave empty and `--setup-repo` refuses to run; `--update` skips the + rsync and only pulls + shadows. +- **`SBO_PERSONAL_TREES`** - a bash associative array, directory name (created + under `SBO_TREE_ROOTS[0]`) to git clone URL, for your own SlackBuilds that + live outside upstream (unpublished/personal/pentesting packages). + +### First-time setup: `--setup-repo` + +Builds `SBO_TREE_ROOTS[0]` from scratch. Runs as root, asks for confirmation, +then REMOVES the existing tree root, rsyncs it fresh from `SBO_RSYNC_URL`, +clones each `SBO_PERSONAL_TREES` subtree into it, then shadows (see below, +with its own confirmation). Exits afterward, does not build. Hard-fails on an +rsync or clone error. + +```sh +sbo-batch-test --setup-repo +``` + +### Per-run refresh: `--update` + +Runs inline before a build, refreshing the tree without wiping personal work. +rsyncs the tree with `--delete` to pull in upstream changes and removals +(personal subtrees are excluded from the rsync, so they are never touched by +`--delete`), which also brings back any upstream package that a previous +shadow removed. Then git-pulls each personal subtree, then re-shadows. +Fail-soft: a network or git error prints a warning and the run continues. + +```sh +sbo-batch-test --update playwright-cli +``` + +### Shadowing + +Your personal packages win. When a package under a `SBO_PERSONAL_TREES` subtree +shares a name with a package elsewhere in the upstream tree, the upstream copy +is `rm -r`'d so lookup (first match wins per `SBO_TREE_ROOTS` order, but within +one root the personal copy would otherwise collide) resolves to yours. Both +`--setup-repo` and `--update` run this scan, and both ask for confirmation +before removing anything. + +This self-heals: if you later drop a package from a personal repo, the next +`--update` rsync brings the upstream copy back, since nothing shadows it +anymore. + ## Package cache Set `PKG_CACHE` in your config to a local directory to cache built packages @@ -136,6 +188,8 @@ sbo-batch-test --dry-run playwright-cli | `--with-x` | Enable X passthrough (`xhost +local:hosts`). Headless by default. Security caveat: allows local non-network connections to your X server. | | `-j`, `--jobs N` | Reserved. No-op stub today (builds are serial). | | `--init-base` | First-time populate `SLACKWARE_BASE` from the mirror, then exit. Run once before the first build. Refuses to clobber an existing base. | +| `--setup-repo` | First-time build of the SBo tree from `SBO_RSYNC_URL` and `SBO_PERSONAL_TREES`. See below. Exits, does not build. | +| `--update` | Before building, refresh the SBo tree (rsync + git pull + shadow). See below. | ## Per-package status values -- cgit v1.2.3