Pitot
Guides / 02 — Upgrades

Guide 02 / Upgrades

Upgrades as a reviewed diff

Because the repository owns the version, upgrading Pitot is not a machine-by-machine operation. It is one reviewed line in one commit — and rolling back is reverting that commit.

01The entire upgrade is one line

pitot upgrade changes exactly one thing in your repository: the pin. Everything else — verification, tenant re-validation — happens before that line is rewritten, so the diff your reviewer sees is the whole change:

git diff — the entire upgrade
--- a/.pitot/version
+++ b/.pitot/version
-0.1.1
+0.1.2

The shims do not change on upgrade. They are version-agnostic readers of the pin — that is what makes the one-line property hold.

02Check before you change anything

Report only
01 pitot upgrade --check

reports pinned vs latest; writes nothing

Use this in a scheduled CI job if you want upgrade candidates surfaced automatically — the check is read-only, so it is safe anywhere.

03Running the upgrade

Upgrade
01 pitot upgrade

hydrate the new release, validate tenants against it, rewrite .pitot/version — nothing else

02 git diff

review the one line; commit it like any other change

04What is verified before the pin moves

  • The release itself. The new version is hydrated and sha256-verified against the published checksums.txt — the same verification the shim performs.
  • Every tenant fragment. Each fragment under .pitot/conf.d/ is re-checked against the new release. A fragment that pinned requires_protocol to a version the new binary cannot honor fails the upgrade loudly, naming the fragment — before the pin is touched.
Design intent

An upgrade that would break a tenant's declared expectations refuses to produce the diff, instead of producing a diff that breaks a teammate's tool after merge.

05Rollout and rollback are git operations

  • Rollout: merge the pin commit. Every clone hydrates the new version on its next .pitot/bin/pitot invocation — teammates, CI, and cloud agents pick it up with no action.
  • Rollback: revert the pin commit. The previous version is still in every user's cache, so rollback is instant and offline-safe.

06Watching for drift

Two kinds of drift matter, and one command reports both:

Inspect
01 pitot doctor

reports the effective boundary, the pin, and the local cache state

  • Pin vs cache: a clone whose cache lacks the pinned release hydrates on next run; with PITOT_NO_HYDRATE=1 set, doctor is how you see that a pre-seed is needed.
  • Global CLI vs pin: a globally installed pitot may lag the repository pin — harmless inside pinned repos (the shim wins), but doctor makes the difference visible instead of surprising.