Maintenance¶

The upkeep is a small number of just recipes. This page says what each one touches, so you can run the right one.

The update cycle¶

just update

update runs three recipes in order:

just upgrade-all is the smaller variant: it only reinstalls the uv interpreters and runs mise install.

just outdated lists what Homebrew would upgrade without doing it.

Brewfiles¶

There are two kinds of Brewfile in home/:

just freeze (alias just lock) is the one to run after you install or remove something; just upgrade also runs it at the end. It overwrites this Mac's file with a fresh dump. Git holds the previous version, so review the change before you commit:

just freeze
git diff home/Brewfile.$(hostname -s)

Lint¶

just lint

This runs every hook in .pre-commit-config.yaml through prek: whitespace and end-of-file fixes, YAML, TOML, and JSON syntax, executable bits, shellcheck on the bash files, ruff on the Python scripts, and just --fmt --check on every justfile. The CI workflow runs the same command on every push, so a failure there is a failure you can reproduce locally.

To run the hooks on every commit as well, run uvx prek install once in the repository.

just fmt formats the justfiles in place. Run it before just lint when the format check fails.

The manual¶

The Docs workflow builds and deploys the site on every push to main. It publishes through a GitHub Pages artifact, not a branch. The repository's Pages source must stay on "GitHub Actions"; if it flips to the branch build, GitHub renders the README instead. See Troubleshooting.

Run just update-docs after you add or rename a recipe, and commit the result. Zensical's config is zensical.toml at the repository root; it has to stay there, because Zensical treats the config's folder as the project root.

Python¶

uv owns Python. The recipes are in the python module:

The tool list is in home/.justfiles/python.justfile. Add a tool there, not by hand, so every Mac gets it.

Python versions¶

Every Mac keeps one uv install of each version: the newest patch release. On 2026-10-12 all three Macs had the same set:

3.10 and older are gone. Do not install them again.

Homebrew also installs Python 3.12 to 3.14 in /opt/homebrew/bin, because other formulae need them. ~/.local/bin comes last on the PATH, so python3 and python3.14 find the Homebrew copy first. Only python always finds the uv copy.

To see what is installed:

uv python list --only-installed --managed-python
uv python dir      # where uv keeps them

To move to new patch releases and drop the old ones:

1. Run just python::uv-pip-upgrade. It runs uv python upgrade, which installs the newest patch of each version and moves the links.
2. uv python upgrade skips the free-threaded builds. Install those by full version, for example uv python install 3.14.8+freethreaded.
3. Remove each old patch by its key, for example uv python uninstall cpython-3.14.7-macos-aarch64-none.
4. Do the same on each Mac.

A project .venv points to the exact patch release that made it. When that release is removed, the .venv stops working. Run uv sync in the project to make a new one. For a uv tool, run uv tool install --reinstall <tool>.

Languages¶

just mise::upgrade runs mise install, then mise prune to drop versions the config no longer names, then mise reshim. The versions are in home/.config/mise/config.toml. Python is disabled in mise so it never competes with uv.

Leftovers from the Python migration¶

Leave ~/.virtualenvs/ alone. Nothing needs to be deleted here any more.