Feature commands
Commands that start, list, update, stack and close private features.
Starting a feature, looking at it, bringing in changes from its public pull request, stacking and folding, and closing or abandoning it. Each card shows the command’s own help: ghostbranch <command> --help prints the same. Every command also takes the global flags.
feature start
Section titled “feature start”ghostbranch feature start <name> [flags]feature start creates <name> from shadow main in the shadow repo and records it as a feature. It does not touch your checkout; fetch and switch to the branch afterwards. With --from <feature> it starts at that feature's tip instead and records it as the parent, stacking the new feature on it.
| Flag | Value | Default | Description |
|---|---|---|---|
| --from | <string> | — | stack the feature on another feature: start it at that feature's tip in the shadow repo (default: shadow main) |
| --plan | — | — | preview exactly what would change, and change nothing (same as --dry-run) |
| --yes | — | — | accepted for consistency; feature start never asks |
More in Your first feature.
feature list
Section titled “feature list”ghostbranch feature list [flags]feature list prints one line per feature: its state, whether it still merges cleanly onto public main (drift), its last gate and its public PR. Abandoned features are left out unless --all. It only reads.
| Flag | Value | Default | Description |
|---|---|---|---|
| --all | — | — | include abandoned features |
More in The repo pair and the shadow.
feature show
Section titled “feature show”ghostbranch feature show <name>feature show prints everything about one feature: its state, branch and base, drift onto public main and the files that conflict, its last gate, its public PR and plan, its commits since public main, and this pair's ledger entries for it. It only reads.
More in The repo pair and the shadow.
feature pull
Section titled “feature pull”ghostbranch feature pull <feature> [flags]feature pull reads the open public PR of <feature> and the commits on its branch that Ghostbranch didn't publish (someone pushed them on GitHub: a maintainer's fix, an applied suggestion). It brings them into the feature's branch in the shadow repo and records them as adopted, in one push leased on what it read. They are already public, so the next gate doesn't scan them again; the next promote keeps them. Your later commits are replayed on top of them. A merge commit or a conflict stops it with the git steps to merge the PR's branch yourself; Ghostbranch never resolves conflicts. It only touches the shadow repo; your checkout needs a fetch and reset afterwards. --plan shows what would change.
| Flag | Value | Default | Description |
|---|---|---|---|
| --plan | — | — | preview exactly what would change, and change nothing (same as --dry-run) |
More in Updating an open PR.
feature restack
Section titled “feature restack”ghostbranch feature restack <feature> [flags]feature restack replays each feature stacked above <feature> (then the ones above those, in order) onto its parent's new tip, in a throwaway worktree, and pushes each with a lease, together with its updated record. A feature that already holds its parent's tip only has its record updated. The first conflict stops the restack with the git commands to rebase that feature yourself; features already restacked stay restacked. Ghostbranch never resolves conflicts. With --onto main or --onto <feature>, <feature> itself moves first: its own commits are replayed onto main (dropping its parent's commits) or onto that feature, and then the features above it follow. It only touches the shadow repo; your checkouts of the rewritten branches need a fetch and reset afterwards.
| Flag | Value | Default | Description |
|---|---|---|---|
| --onto | <string> | — | move <feature> itself onto "main" or onto another feature first |
| --plan | — | — | preview exactly what would change, and change nothing (same as --dry-run) |
More in Stacked features.
feature fold
Section titled “feature fold”ghostbranch feature fold <feature> [flags]feature fold moves the parent feature's branch to <feature>'s head in the shadow repo, a fast-forward (never a merge or a rebase), and closes <feature>. Its branch, gate branch, metadata and plan refs are deleted in the same atomic push, leased on what fold read, and the features stacked on <feature> are stacked on the parent instead. Nothing is lost: every commit of <feature> is on the parent, so no console is asked. If the parent has moved on since <feature> was started from it, fold refuses with FOLD_NEEDS_REBASE, and next gives the git commands to rebase <feature> yourself. Ghostbranch never resolves conflicts. --plan shows what would change.
| Flag | Value | Default | Description |
|---|---|---|---|
| --plan | — | — | preview exactly what would change, and change nothing (same as --dry-run) |
More in Stacked features.
feature close
Section titled “feature close”ghostbranch feature close <name> [flags]feature close deletes a feature from the shadow repo: its branch, its gate branch, its metadata, its plan refs and, for an archived feature, its archive ref, in one push that fails, deleting nothing, if any of them moved since it looked. Then it closes the gate's draft PR and removes the feature's plan files and mirror refs on this machine. The ledger records every ref deleted with the SHA it pointed at, so a branch can be pushed back.
A feature whose public PR merged and whose branch hasn't moved since closes without asking (sync does this on its own). Anything else would lose work that was never published, so a person confirms by typing a code at the console. --plan shows what would be deleted and asks no one.
| Flag | Value | Default | Description |
|---|---|---|---|
| --plan | — | — | preview exactly what would change, and change nothing (same as --dry-run) |
More in Merging and closing.
feature abandon
Section titled “feature abandon”ghostbranch feature abandon <name> [flags]feature abandon marks a feature abandoned in its metadata in the shadow repo. Nothing is deleted: its branch, gate and plans stay, status still shows it, and feature list hides it unless --all. --undo makes it an active feature again. To delete a feature, use feature close.
| Flag | Value | Default | Description |
|---|---|---|---|
| --plan | — | — | preview exactly what would change, and change nothing (same as --dry-run) |
| --undo | — | — | restore an abandoned feature |
More in Merging and closing.
feature archive
Section titled “feature archive”ghostbranch feature archive <name> [flags]feature archive hands a published feature off to the public repo, as apply's Archive does: in one push to the shadow repo it moves the feature's branch to refs/ghostbranch/archive/<name> and deletes the branch and its gate branch, then closes the gate's draft PR and marks the record. Nothing is lost: the archive keeps the branch's head. From then on, fix or change its PR by pushing to the PR's branch; promote, gate and feature pull refuse it, and sync closes it when the PR merges. It runs only while the PR is open and no other feature is built on this one. An archived feature is left as it is. --plan shows what would change.
| Flag | Value | Default | Description |
|---|---|---|---|
| --plan | — | — | preview exactly what would change, and change nothing (same as --dry-run) |
More in Promote and approval.
status
Section titled “status”ghostbranch statusstatus reports whether shadow main is behind public main, whether the overlay's managed files need an upgrade, and whether scheduled sync is on; then every feature, abandoned ones included, with its state, whether it still merges cleanly onto public main (drift), its last gate and its public PR. It only reads: nothing is pushed and nothing is written to the ledger.
More in The repo pair and the shadow.
ghostbranch log [flags]log prints this workspace's ledger: every mutating command, who ran it (the actor), and how it ended, newest first. It reads only the local ledger: no token, no network, no pair. --feature and --op match exactly, --actor matches a prefix (agent: shows every agent), and --since takes a duration back from now (24h) or an RFC 3339 time. --repo shows one pair's entries, even after remove; --repo . is the pair this checkout's remotes name.
| Flag | Value | Default | Description |
|---|---|---|---|
| --actor | <string> | — | only entries whose actor starts with this, such as agent: or human:octo |
| --feature | <string> | — | only entries about this feature |
| --limit | <int> | 50 | at most this many entries (1 or more) |
| --op | <string> | — | only entries for this operation, such as promote or "feature start" |
| --since | <string> | — | only entries from this long ago (24h) or since this RFC 3339 time |
More in How agents use Ghostbranch.