add prune to docs

github · skarim · May 15, 2026 · May 15, 2026 · May 15, 2026 · May 15, 2026
commit bfebb7f26fcc61e66b2b384ff04ffe99715eb878
@@ -310,15 +310,20 @@ Performs a safe, non-interactive synchronization of the entire stack:
 3. **Cascade rebase** — rebases all stack branches onto their updated parents (only if trunk moved). If a conflict is detected, all branches are restored to their original state and you are advised to run `gh stack rebase` to resolve conflicts interactively
 4. **Push** — pushes all branches (uses `--force-with-lease` if a rebase occurred)
 5. **Sync PRs** — syncs PR state from GitHub and reports the status of each PR
+6. **Prune** — in interactive terminals, prompts to delete local branches for merged PRs. Use `--prune` to prune automatically
 
 | Flag | Description |
 |------|-------------|
 | `--remote <name>` | Remote to fetch from and push to (defaults to auto-detected remote) |
+| `--prune` | Delete local branches for merged PRs |
 
 **Examples:**
 
 ```sh
 gh stack sync
+
+# Sync and automatically prune merged branches
+gh stack sync --prune
 ```
 
 ### `gh stack push`
@@ -556,6 +561,7 @@ gh stack push
 
 # 8. When the first PR is merged, sync the stack
 gh stack sync
+# → prompts to prune merged branches (or use --prune to prune automatically and avoid the prompt)
 ```
 
 ## Abbreviated workflow

@@ -49,4 +49,4 @@ gh stack sync
 
 - **`gh stack push`** pushes branches only (uses `--force-with-lease` for safety). It does not create or update PRs.
 - **`gh stack submit`** pushes branches and creates or updates PRs, linking them as a Stack on GitHub.
-- **`gh stack sync`** is the all-in-one command: fetch, rebase, push, and sync PR state.
+- **`gh stack sync`** is the all-in-one command: fetch, rebase, push, sync PR state, and optionally prune local branches for merged PRs.
@@ -134,6 +134,7 @@ This command:
 3. Rebases all remaining stack branches onto the updated trunk
 4. Pushes the updated branches
 5. Syncs PR state from GitHub
+6. Prompts to prune local branches for merged PRs (use `--prune` to prune automatically)
 
 If a conflict is detected during the rebase, all branches are restored to their original state, and you're advised to run `gh stack rebase` to resolve conflicts interactively.
 

@@ -295,15 +295,20 @@ Performs a safe, non-interactive synchronization of the entire stack:
 3. **Cascade rebase** — rebases all stack branches onto their updated parents (only if trunk moved). If a conflict is detected, all branches are restored to their original state, and you are advised to run `gh stack rebase` to resolve conflicts interactively.
 4. **Push** — pushes all branches (uses `--force-with-lease` if a rebase occurred).
 5. **Sync PRs** — syncs PR state from GitHub and reports the status of each PR.
+6. **Prune** — in interactive terminals, prompts to delete local branches for merged PRs. Use `--prune` to prune automatically.
 
 | Flag | Description |
 |------|-------------|
 | `--remote <name>` | Remote to fetch from and push to (defaults to auto-detected remote) |
+| `--prune` | Delete local branches for merged PRs |
 
 **Examples:**
 
 ```sh
 gh stack sync
+
+# Sync and automatically prune merged branches
+gh stack sync --prune
 ```
 
 ### `gh stack rebase`

@@ -152,6 +152,7 @@ Small, incidental fixes (e.g., fixing a typo you noticed) can go in the current
 | Create PRs as ready for review | `gh stack submit --auto --open` |
 | Sync (fetch, rebase, push) | `gh stack sync` |
 | Sync with specific remote | `gh stack sync --remote origin` |
+| Sync and prune merged branches | `gh stack sync --prune` |
 | Rebase entire stack | `gh stack rebase` |
 | Rebase upstack only | `gh stack rebase --upstack` |
 | Continue after conflict | `gh stack rebase --continue` |
@@ -305,8 +306,13 @@ gh stack push
 ```bash
 # Single command: fetch, rebase, push, sync PR state
 gh stack sync
+
+# Sync and automatically clean up local branches for merged PRs
+gh stack sync --prune
 ```
 
+> **Note for agents:** In non-interactive environments, the prune prompt is not shown. Use `--prune` explicitly to delete local branches for merged PRs.
+
 ### Squash-merge recovery
 
 When a PR is squash-merged on GitHub, the original branch's commits no longer exist in the trunk history. `gh stack` detects this automatically and uses `git rebase --onto` to correctly replay remaining commits.
@@ -615,6 +621,7 @@ gh stack sync [flags]
 | Flag | Description |
 |------|-------------|
 | `--remote <name>` | Remote to fetch from and push to (use if multiple remotes exist) |
+| `--prune` | Delete local branches for merged PRs |
 
 **What it does (in order):**
 
@@ -623,6 +630,7 @@ gh stack sync [flags]
 3. **Cascade rebase** all stack branches onto their updated parents (only if trunk moved). Handles merged PRs automatically. If a conflict is detected, **all branches are restored** to their pre-rebase state and the command exits with code 3 — see [Handle rebase conflicts](#handle-rebase-conflicts-agent-workflow) for the resolution workflow
 4. **Push** all active branches atomically
 5. **Sync PR state** from GitHub and report the status of each PR
+6. **Prune** — in interactive terminals, prompts to delete local branches for merged PRs. Use `--prune` to skip the prompt. In non-interactive environments, pruning only happens when `--prune` is passed explicitly
 
 **Output (stderr):**
 
@@ -632,6 +640,7 @@ gh stack sync [flags]
 - `✓ Pushed N branches`
 - `✓ PR #N (<branch>) — Open` per branch
 - `Merged: #N, #M` for merged branches
+- `✓ Pruned <branch> (merged)` per pruned branch (when pruning)
 - `✓ Stack synced`
 
 ---