Hall upkeep
Keeping the hall honest from inside the harness — reconciling against ivar.json, listing what is registered, and authoring the setup script a fresh worktree needs.
The hall is shared state: a manifest everyone commits and a local checkout that has to keep up with it. Three commands cover the upkeep.
Reconcile against the manifest
/ivar-syncReconciles the hall's derived local state against its sources of truth — the
committed ivar.json and the installed ivar package. Run it after pulling the
hall, and any time the local checkout stops matching what the manifest says.
See what is registered
/ivar-repo-listLists the repos in the hall manifest, along with the features, sessions and promoted repos. The quickest orientation when you land in a hall you did not set up.
Author a setup script
/ivar-repo-setupWrites a repo's setup script at .ivar/setups/<repo>.sh by inspecting the
repo and working out what a freshly-cut worktree needs: install dependencies,
copy env files, run codegen.
Why a worktree needs one at all
A new worktree is a clean checkout. Everything that is gitignored — installed dependencies, generated code, local env files — is absent, and every feature branch you cut starts from that state. The setup script is what makes a fresh worktree usable without a wiki page.
ivar runs the script when a worktree is materialised, and receipts the run so
a later sync does not repeat work that is already done. The script lives in
.ivar/setups/, which you commit, so it reaches every teammate who clones the
hall.
What the script gets
ivar runs bash .ivar/setups/<repo>.sh with the worktree as the working
directory, so #!/bin/sh in the first line has no effect. These variables are
set:
| Variable | Value |
|---|---|
IVAR_HALL | The hall root |
IVAR_REPO | The repo's name in ivar.json |
IVAR_BRANCH | The branch checked out in the worktree |
IVAR_WORKTREE | Absolute path to the worktree (the working directory) |
IVAR_WORKTREE_KIND | default when ivar sync runs it, feature when ivar feature promote does |
IVAR_FEATURE | The feature's name; set only when IVAR_WORKTREE_KIND is feature |
IVAR_SECRETS_DIR | .ivar/secrets/, ignored by git and kept on each machine |
Keep secrets in IVAR_SECRETS_DIR and copy them in from the script. The
script stays committable and the values stay on each developer's disk.
A Flutter app
set -euo pipefail
flutter pub get
dart run build_runner build -d
if [[ "$(uname -s)" == Darwin ]]; then
(cd ios && pod install)
fi
cp "$IVAR_SECRETS_DIR/google-services.json" android/app/
cp "$IVAR_SECRETS_DIR/app.env" .envEvery step is safe to run twice, which matters because a failed run gets
retried. Each feature worktree holds its own .dart_tool/ and build/, so
budget disk for one build per parallel feature. Simulators and dev-server
ports stay shared between worktrees; two agents running the app at once need
different devices or ports.
When the script fails
A failed script does not undo the promotion. The repo stays promoted, its
state reads failed with the script's exit and last output line, and the
full output is in .ivar/features/<feature>/setup-<repo>.log.
ivar feature status <feature> shows the reason and the retry command, and
ivar doctor lists every failed promotion in the hall. Fix the cause, then
promote again:
ivar feature promote <feature> <repo>Promoting a repo whose promotion failed retries it: the worktree is recreated
or adopted and the script runs again. For a default-branch worktree,
ivar repo setup <repo> --force-setup re-runs the script.
From the command line
Everything above is a slash command over an ivar subcommand. When you want to
run one yourself, they are documented in
Reference → ivar hall.