Install#

git clone https://github.com/adamsrnmsu/perch.git && cd perch && make install

perch is the one repo you clone. make install clones Budgie and gitboard into apps/ (ignored by perch’s git; each stays its own repo), sets up one .venv for all three and puts perch, budgie and gitboard on your PATH. It leaves an app already in apps/ alone, so it is safe to re-run. Then:

perch init apollo --gitlab group/apollo   # scaffold projects/apollo/, its .env and its Budgie project
perch doctor           # tools, config, names, freshness; FIX lines say what to run

Each project has its own GitLab URL and tokens in projects/NAME/.env, written by perch init (add --gitlab group/NAME to fill gitlab_project:) with <key-from-gitlab> placeholders to replace. perch/.env is the shared fallback for a project with no .env of its own; perch doctor says which one each project uses and never prints a token.

pyproject.toml pins Budgie to its GitHub repo by URL (never PyPI, where the name is not ours); make install never installs it, so local Budgie edits show up in perch at once.

make install puts one .venv in the checkout that holds only the dependencies of perch, Budgie and gitboard (nothing of ours is built or installed), writes perch, budgie and gitboard into .venv/bin as small scripts that run each app from its checkout, and links them into ~/.local/bin. It needs Python 3.11 or newer (make install PYTHON=python3.12). Offline: PIP_NO_INDEX=1 PIP_FIND_LINKS=/path/to/wheels make install. The old ~/Documents/tools/perch and ~/Documents/tools/budgie can be deleted once perch doctor is clean; doctor names them.

Migrating an old workspace#

If you have a perch-home.yaml beside projects/ and budget/:

  1. git pull perch, then make install (adds HTTPS clones for missing apps and relinks).

  2. From the old workspace run perch doctor. It prints the exact mv commands; run them, then perch doctor again to confirm.

  3. Create config.yaml with lead: NAME and move the old alerts: block into it.

  4. perch gb pull -p X once per project so a .base exists; perch gb plan -p X should then show nothing.

  5. Delete perch-home.yaml.

Nothing is moved for you.