Upgrading Ghostbranch

Ghostbranch tells you when a new release is out, and names the command that upgrades your copy. It never upgrades itself.

The update check

Now and then, Ghostbranch asks GitHub whether a newer release is out: every 4 hours before version 1.0, and once a day after it. It runs in the background while a command works, as at most two anonymous requests, with no token and nothing that identifies you or your repos. It never downloads or installs anything, and it never makes a command fail or slows it by more than half a second. (doctor, which looks there and then, waits up to 3 seconds.)

When a newer release is out, you see a reminder after a command’s own output:

Terminal

# after the command's output, on stderr:

! Ghostbranch 0.1.1 is out (you have 0.1.0).

Upgrade: brew upgrade ghostbranch

When the new release fixes a security issue in your version, it says so:

Terminal

✗ Ghostbranch 0.1.1 fixes a security issue (GHSA-xxxx-xxxx-xxxx); you have 0.1.0.

Upgrade now: brew upgrade ghostbranch

Both are the reminder’s format with sample versions: no release is out yet, so neither could be captured. The command on the second line depends on how you installed Ghostbranch (see below).

You see a reminder only at a terminal, and not with --json. Before 1.0 it comes on every command while you’re behind; from 1.0 at most once a day, except for a security fix, which reminds you every time.

What agents see

With --json, the reminder is the warning UPDATE_AVAILABLE in the result’s warnings. This is its format with sample versions, built from the binary’s source like the reminders above:

warnings (part; sample values)

{
  "code": "UPDATE_AVAILABLE",
  "message": "Ghostbranch 0.1.1 is out (this is 0.1.0)",
  "details": {
    "current": "0.1.0",
    "latest": "0.1.1",
    "url": "https://github.com/ghostbranch-labs/ghostbranch/releases/tag/v0.1.1",
    "security": false,
    "advisories": [],
    "upgrade": "brew upgrade ghostbranch"
  }
}

A coding agent tells you about it and quotes details.upgrade. It never runs the upgrade itself: what runs on your machine is your call. With details.security: true, it says that first.

What doctor says

ghostbranch doctor looks for a release there and then, and its last line says how the check stands. On a development build, made from a checkout as here, it’s off:

TerminalCopy

$ ghostbranch doctor

# the six checks, then:

update check: off (development build)

On a release, the line is one of these, filled in with your versions:

• update check: on · last looked 3h ago · up to date
• update check: on · last looked 3h ago · 0.1.1 available (you have 0.1.0), with the advisories after it for a security fix
• update check: on · not looked yet
• update check: on · no release published yet
• update check: on · last look failed: <reason>

doctor --json has the same in data.update_check, including the upgrade command.

Turning it off

Set GHOSTBRANCH_NO_UPDATE_CHECK=1, and Ghostbranch never looks. It’s off by itself in CI too: whenever CI, GITHUB_ACTIONS, GITLAB_CI, BUILDKITE, CIRCLECI, JENKINS_URL or TF_BUILD is set. doctor names the reason:

Terminal

$ GHOSTBRANCH_NO_UPDATE_CHECK=1 ghostbranch doctor

# the six checks, then:

update check: off (GHOSTBRANCH_NO_UPDATE_CHECK)

In CI, the reason is CI.

Upgrade

Upgrade the same way you installed. The reminder works out which way that was from where the ghostbranch binary is, and names the command. When it can’t tell, it gives the release page instead.

Installed with	Upgrade with
Homebrew	brew upgrade ghostbranch Placeholder: the Homebrew tap isn’t published yet.
Scoop / winget	scoop update ghostbranch or winget winget upgrade --id <WINGET_ID> Placeholder: the Scoop bucket and winget package aren’t published yet.
npm	npm update -g ghostbranch or pnpm, yarn or bun pnpm update -g ghostbranch yarn global upgrade ghostbranch bun update -g ghostbranch Placeholder: the npm package isn’t published yet.
Install script	The update reminder links to the release page Placeholder: the install script isn’t published yet.
Go	go install github.com/ghostbranch-labs/ghostbranch/cmd/ghostbranch@latest Works once the repository is public.

Note

Ghostbranch has no release yet, so none of these routes is published. Install says the same for each one.

After you upgrade, run ghostbranch doctor to check the new version works with your setup.

Check your version

TerminalCopy

$ ghostbranch version

ghostbranch v0.0.0-20261014135732-03a0aa5dc864 (commit 03a0aa5dc864), JSON contract 0.15

ghostbranch --version prints the same line. It has three parts:

• The version. A development build, as here, has a version made from the commit’s date and hash. A release has a number such as v0.1.0.
• The commit it was built from.
• The JSON contract, the version of the --json output that scripts and agents read. It’s the schema_version in every result:

ghostbranch version --json

{
  "schema_version": "0.15",
  "command": "version",
  "ok": true,
  "exit_code": 0,
  "data": {
    "version": "v0.0.0-20261014135732-03a0aa5dc864",
    "commit": "03a0aa5dc864",
    "schema_version": "0.15"
  },
  "warnings": [],
  "next": [],
  "error": null
}

If you work on two machines, upgrade both. A newer version can write records the older one won’t change: see Working on two machines.

Tip

ghostbranch upgrade is a different command. It doesn’t update the program: it updates the files Ghostbranch manages in your shadow repo, to match the version you have. Run it when a command warns OVERLAY_OUTDATED, which can happen after you upgrade. See Setting up CI.

Errors you may see

UPDATE_AVAILABLEwarningA newer Ghostbranch release is out (details.latest; this is details.current). details.security is true when it fixes a security issue that affects this version (details.advisories).

What to do

Tell the person, quoting details.upgrade (the command that upgrades this install) and, for a security fix, details.advisories. Never run the upgrade yourself. GHOSTBRANCH_NO_UPDATE_CHECK=1 turns the check off.

UPGRADE_NEEDEDexit 1Something this pair uses was written by a newer Ghostbranch: a record (error.details.record: feature, plan, grants or waivers) or the overlay config (error.details.unknown_key, a key this binary doesn't know).

What to do

Upgrade ghostbranch on this machine to the version that wrote it, or newer (the other machine is probably newer). Don't edit the record or the overlay config to make an older binary accept it. If the key in error.details.unknown_key is a typo, a person fixes it in .ghostbranch.yml on the overlay branch.

RECORD_NEWERwarningA record was written by a newer Ghostbranch; this binary shows what it can read of it and won't change it.

What to do

Upgrade ghostbranch on this machine (the other machine is probably newer). Reads still work; commands that would change the record stop with UPGRADE_NEEDED.

OVERLAY_OUTDATEDwarningA Ghostbranch-managed file on the overlay branch is missing, out of date, or edited by hand.

What to do

Run ghostbranch upgrade --plan to see the change, then ghostbranch upgrade.

DOCTOR_FAILEDexit 1ghostbranch doctor found failing checks; error.details.failed lists their IDs.

Causes

• one of tools, token, pair, guard, state or ci failed; data.checks[].message says why

What to do

Run the fix each failing check names (data.checks[].fix, also listed in next), then run ghostbranch doctor again. Warnings don't fail doctor.