unstack docs

Author: skarim

docs/src/content/docs/faq.md

@@ -33,11 +33,24 @@ You can also add PRs to an existing stack from the GitHub UI. See [Adding to an
 
 ### How can I modify my stack?
 
-Reordering or inserting branches into the middle of a stack is not currently supported. To restructure a stack, you need to delete it and recreate it with the desired order.
+Reordering or inserting branches into the middle of a stack is not currently supported. To restructure a stack, use `gh stack unstack` to tear it down and then recreate it with `gh stack init --adopt`:
+
+```sh
+# 1. Remove the stack
+gh stack unstack
+
+# 2. Make structural changes (reorder, rename, delete branches)
+git branch -m old-name new-name
+
+# 3. Re-create the stack with the new structure
+gh stack init --adopt branch-2 branch-1 branch-3
+```
 
 ### How do I delete my stack?
 
-You can unstack PRs from the GitHub UI — see [Unstacking](/gh-stack/guides/ui/#unstacking) for a walkthrough. This dissolves the association between PRs, turning them back into standard independent PRs. CLI support for unstacking is coming soon.
+**From the CLI** — Run `gh stack unstack` to delete the stack on GitHub and remove local tracking. Use `--local` to only remove local tracking.
+
+**From the UI** — You can unstack PRs from the GitHub UI — see [Unstacking](/gh-stack/guides/ui/#unstacking) for a walkthrough. This dissolves the association between PRs, turning them back into standard independent PRs.
 
 ### Can stacks be created across forks?
 

docs/src/content/docs/guides/workflows.md

@@ -163,6 +163,27 @@ Create a new branch (`gh stack add`) when you're starting a **different concern*
 
 All branches in a stack should be part of the same feature or project. If you need to work on something unrelated, start a separate stack with `gh stack init` or switch to an existing one with `gh stack checkout`.
 
+## Restructuring a Stack
+
+When you need to remove a branch, reorder branches, or rename branches, tear down the stack and rebuild it:
+
+```sh
+# 1. Remove the stack on GitHub and locally
+gh stack unstack
+
+# 2. Make structural changes
+git branch -m old-branch-1 new-branch-1  # rename a branch
+git branch -D branch-3                   # delete a branch
+
+# 3. Re-create the stack with the new order
+gh stack init --adopt new-branch-1 branch-2 branch-4
+
+# 4. Push and sync the new stack
+gh stack submit
+```
+
+The `unstack` command deletes the stack on GitHub first, then removes local tracking. Your branches and PRs are not affected — only the stack relationship is removed. After `init --adopt`, any existing open PRs are automatically re-associated with the new stack.
+
 ## Using AI Agents with Stacks
 
 AI coding agents (like GitHub Copilot) can create and manage Stacked PRs on your behalf. Install the gh-stack skill to give them the context they need:

docs/src/content/docs/introduction/overview.md

@@ -88,6 +88,7 @@ While the PR UI provides the review and merge experience, the `gh stack` CLI han
 - **Creating PRs** — `gh stack submit` pushes branches and creates or updates PRs, linking them as a Stack on GitHub.
 - **Navigating the stack** — `gh stack up`, `down`, `top`, and `bottom` let you move between layers without remembering branch names.
 - **Syncing everything** — `gh stack sync` fetches, rebases, pushes, and updates PR state in one command.
+- **Tearing down stacks** — `gh stack unstack` removes a stack from GitHub and local tracking if you need to restructure it.
 
 The CLI is not required to use Stacked PRs — the underlying git operations are standard. But it makes the workflow dramatically simpler.
 

docs/src/content/docs/reference/cli.md

@@ -275,6 +275,39 @@ gh stack push
 gh stack push --remote upstream
 ```
 
+### `gh stack unstack`
+
+Remove a stack from local tracking and delete it on GitHub.
+
+```sh
+gh stack unstack [flags] [branch]
+```
+
+Deletes the stack on GitHub first, then removes it from local tracking. If the remote deletion fails, the local state is left untouched so you can retry. Use `--local` to skip the remote deletion and only remove local tracking.
+
+This is useful when you need to restructure a stack — remove a branch, reorder branches, rename branches, or make other large changes. After unstacking, use `gh stack init --adopt` to re-create the stack with the desired structure.
+
+| Flag | Description |
+|------|-------------|
+| `--local` | Only delete the stack locally (keep it on GitHub) |
+
+| Argument | Description |
+|----------|-------------|
+| `[branch]` | A branch in the stack to identify which stack to delete (defaults to the current branch) |
+
+**Examples:**
+
+```sh
+# Delete the stack on GitHub and remove local tracking
+gh stack unstack
+
+# Only remove local tracking
+gh stack unstack --local
+
+# Specify a branch to identify which stack
+gh stack unstack feature-auth
+```
+
 ---
 
 ## Navigation