Manage combined-fixes branches as JSON specs instead of hand-maintained cherry-pick lists.

Synopsis

homeboy stack <COMMAND>

Stack specs live at ~/.config/homeboy/stacks/<id>.json. A stack declares one checkout path, a base ref to rebuild from, a target branch to materialize, and an ordered list of GitHub PRs to cherry-pick.

Spec format

{
  "id": "studio-combined",
  "description": "Studio dev/combined-fixes branch",
  "component": "studio",
  "component_path": "~/Developer/studio",
  "base": { "remote": "origin", "branch": "trunk" },
  "target": { "remote": "fork", "branch": "dev/combined-fixes" },
  "prs": [
    { "repo": "example-org/studio", "number": 3120, "note": "proc_open cwd fix" },
    { "repo": "example-org/studio", "number": 3211 }
  ]
}

component_path supports ~ and ${env.VAR} expansion. base and target are split into { remote, branch } so Homeboy can fetch and rebuild without reparsing slash-joined refs.

Subcommands

list

homeboy stack list

List installed stack specs.

show

homeboy stack show <stack-id>

Print the resolved stack spec.

create

homeboy stack create <stack-id> 
  --component studio 
  --component-path ~/Developer/studio 
  --base origin/trunk 
  --target fork/dev/combined-fixes 
  --description "Studio combined fixes"

Create a spec file under ~/.config/homeboy/stacks/.

add-pr

homeboy stack add-pr <stack-id> example-org/studio 3120 --note "proc_open cwd fix"

Append a PR entry to the stack’s prs array.

remove-pr

homeboy stack remove-pr <stack-id> 3120
homeboy stack remove-pr <stack-id> 3120 --repo example-org/studio

Remove a PR entry. Use --repo when the same number appears for multiple repos in one stack.

apply

homeboy stack apply <stack-id>

Fetches the base, recreates the local target branch from the base, then cherry-picks every PR head in order. apply stops on the first conflict, aborts the in-progress pick, and prints a manual-resolution hint. It does not push.

Safety manifest metadata marks apply and rebase as explicit branch-mutation actions. Use status for read-only inspection and sync --dry-run for the available planning path before mutating a stack branch.

status

homeboy stack status <stack-id>

Read-only report combining upstream PR state from GitHub with local target-branch state. Use it to spot merged PRs, missing local picks, and review status without mutating the checkout.

sync

homeboy stack sync <stack-id>
homeboy stack sync <stack-id> --dry-run

Rebuilds the target branch from the fresh base and removes PRs whose content is already in the base. --dry-run reports what would be dropped and picked without mutating the spec or target branch.

inspect

homeboy stack inspect [component-id] [--base <ref>] [--repo <owner/name>] [--no-pr] [--path <path>]

Spec-less inspection of the current branch as a stack of commits over a base ref.

GitHub dependency

apply, status, sync, and inspect PR lookup paths call the GitHub CLI (gh). Authenticate gh for private repositories before relying on stack reports.

push is classified as an explicit remote publication action in the safety manifest. It does not currently expose a dry-run contract.

Related

• rig — local dev environments that can reference stack IDs in component specs
• git — lower-level component-aware git primitives