Publishing commands
Commands that keep up with public, gate a feature, wait for CI and publish.
Keeping the shadow repo up with public, gating a feature, waiting for its CI, and publishing it. Each card shows the command’s own help: ghostbranch <command> --help prints the same. Every command also takes the global flags.
ghostbranch sync [flags]sync fast-forwards the shadow repo's main to public main. It never force-pushes: if shadow main has diverged it stops with exit 4. Its pushes start the shadow repo's push-triggered workflows, which re-test what public CI already tested, so it then cancels those runs (the token needs Actions write on the shadow repo); --no-cancel leaves them running. Last, it closes each feature whose public PR merged and whose branch hasn't moved since it was published, as feature close does; --no-close leaves them. It never closes a feature that needs a person.
| Flag | Value | Default | Description |
|---|---|---|---|
| --no-cancel | — | — | don't cancel the workflow runs the sync's pushes start in the shadow repo |
| --no-close | — | — | don't close features whose public PR merged |
| --plan | — | — | preview exactly what would change, and change nothing (same as --dry-run) |
| --yes | — | — | accepted for consistency; sync never asks |
More in Sync.
ghostbranch gate <feature> [flags]gate rebases the feature onto public main, scans exactly what would be published for leaks, pushes a CI candidate (the feature plus the overlay) to a draft PR in the shadow repo, and waits for every check. It records the result and never touches the public repo. Exit 3 means the gate failed. With --detach it returns a job id once CI has started; ghostbranch wait <job> finishes it, from this machine or another. Without --detach, Ctrl-C leaves the job pending for wait.
| Flag | Value | Default | Description |
|---|---|---|---|
| --detach | — | — | push the candidate, record the job and return without waiting for CI; finish it with ghostbranch wait <job> |
| --plan | — | — | preview exactly what would change, and change nothing (same as --dry-run) |
More in The gate.
ghostbranch wait <job> [flags]wait finishes a gate started with --detach (or interrupted): it waits for the candidate's CI, records the result, and prints what gate would have. A finished job answers at once. With --json it streams one JSON event per line on stdout, and the last line is the result envelope.
| Flag | Value | Default | Description |
|---|---|---|---|
| --timeout | <duration> | 0s | stop waiting after this long and report pending; the job keeps running (0, the default, waits until CI settles) |
More in Long CI.
promote
Section titled “promote”ghostbranch promote <feature>... [flags]promote reuses a fresh green gate (or runs one), builds the public commits (each feature commit with --mode preserve, one with squash, or the groups of a --curate file) on public main, ending on exactly the gated tree, scans every commit's files, message and author, the branch name and PR text for leaks, and saves a plan. With --plan it stops there. Otherwise a person confirms by typing a code shown on the console, or, if they have allowed agents with "ghostbranch agents allow", --yes publishes. Without either it stops at the plan with exit 5. Several features, bottom first (promote a b c), publish a stack: each branch's PR is based on the branch below (a's on main) and shows only that branch's commits, and one approval covers every PR. Each branch needs a fresh green gate built on the branch below. Where GitHub offers native stacked PRs, they are registered as one stack. --mode-for and --title-for set one branch's mode and PR title. After publishing, a person at the console picks Archive (the default: the shadow branch is archived and the PR is fixed by pushing to it) or Keep; with --yes, Archive applies unless --keep.
| Flag | Value | Default | Description |
|---|---|---|---|
| --body | <string> | — | PR body (default: the commit's body, or one line per commit) |
| --branch | <string> | — | public branch name (default: the feature name) |
| --curate | <string> | — | curated mode: a JSON file {"commits": [{"from": [<sha>...], "message": "..."}]} naming every feature commit once, in the order to publish |
| --detach | — | — | if a gate is needed, start it and return its job instead of waiting |
| --keep | — | — | after publishing, keep the feature's shadow branch: fixes go through gate and promote (default: archive it, and fix the PR by pushing to its branch) |
| --message, -m | <string> | — | the squash commit's message (squash mode only) |
| --mode | <string> | — | history mode: preserve (each commit), squash (one commit) or curated (a --curate file); default promote.default_mode, which is preserve unless set |
| --mode-for | <stringArray> | — | one branch's history mode in a stack promote: <feature>=squash or <feature>=preserve (repeatable); default --mode |
| --plan | — | — | save and print the plan without publishing |
| --title | <string> | — | PR title (needed when more than one commit is published; default: the only commit's subject, or the squash message's first line) |
| --title-for | <stringArray> | — | one branch's PR title in a stack promote: <feature>=<title> (repeatable) |
| --yes | — | — | publish under an agent grant (ghostbranch agents allow); on its own it never skips the console |
More in Promote and approval.
ghostbranch apply <plan-id|plan.json> [flags]apply publishes a plan saved by promote. It refuses with exit 6 if public main, the feature, the overlay or the gate candidate moved since the plan was made. Re-running it finishes an interrupted publish. A person confirms on the console, or --yes publishes under an agent grant. After publishing, a person at the console picks Archive (the default: the shadow branch is archived and the PR is fixed by pushing to it) or Keep; with --yes, Archive applies unless --keep.
| Flag | Value | Default | Description |
|---|---|---|---|
| --keep | — | — | after publishing, keep the feature's shadow branch: fixes go through gate and promote (default: archive it, and fix the PR by pushing to its branch) |
| --yes | — | — | publish under an agent grant (ghostbranch agents allow); on its own it never skips the console |
More in Promote and approval.