docs for modify cmd

Author: skarim

README.md

@@ -232,6 +232,68 @@ gh stack rebase --continue
 gh stack rebase --abort
 ```
 
+### `gh stack modify`
+
+Interactively restructure the current stack.
+
+```
+gh stack modify [flags]
+```
+
+Opens a terminal UI for restructuring a stack. You can rename, drop, reorder, and fold branches into adjacent ones. All the changes are staged during the preview and applied at once on save.
+
+If the stack of PRs has been created on GitHub, run `gh stack submit` afterwards to push the changes and recreate the stack.
+
+| Flag | Description |
+|------|-------------|
+| `--continue` | Continue after resolving conflicts |
+| `--abort` | Abort the modify session and restore the stack to its pre-modify state |
+
+**Operations:**
+
+- **Drop** (`x`): Remove a branch and its commits from the stack. Local branch and associated PR are preserved.
+- **Fold down** (`d`): Absorb a branch's commits into the branch below (toward trunk). Folded branch removed from stack.
+- **Fold up** (`u`): Absorb a branch's commits into the branch above (away from trunk). Folded branch removed from stack.
+- **Reorder** (`Shift+↑`/`Shift+↓`): Move a branch up (away from trunk) or down (toward trunk) in the stack.
+- **Rename** (`r`): Rename a branch locally and in the stack metadata.
+- **Undo** (`z`): Undo the last staged action.
+
+**Keybindings:**
+
+| Key | Action |
+|-----|--------|
+| `↑`/`↓` | Navigate branch list |
+| `f` | View files changed |
+| `c` | View commits |
+| `x` | Drop branch |
+| `r` | Rename branch |
+| `u/d` | Fold branch up/down |
+| `Shift+↑`/`Shift+↓` | Move branch up/down |
+| `z` | Undo last action |
+| `Ctrl+S` | Apply all changes |
+| `q`/`Esc` | Cancel and exit |
+| `?` | Help |
+
+**Preconditions:**
+- Must have an active stack checked out locally
+- Working tree must be clean
+- No rebase in progress
+- No PR in the stack is queued for merge
+- Commit history must be linear
+
+**Examples:**
+
+```sh
+# Open the modify TUI
+gh stack modify
+
+# Continue after resolving a conflict
+gh stack modify --continue
+
+# Abort and restore to the previous state
+gh stack modify --abort
+```
+
 ### `gh stack sync`
 
 Fetch, rebase, push, and sync PR state in a single command.

docs/astro.config.mjs

@@ -65,6 +65,7 @@ export default defineConfig({
 						{ label: 'Working with Stacked PRs', slug: 'guides/stacked-prs' },
 						{ label: 'Stacked PRs in the GitHub UI', slug: 'guides/ui' },
 						{ label: 'Typical Workflows', slug: 'guides/workflows' },
+						{ label: 'Restructuring Stacks', slug: 'guides/modify' },
 					],
 				},
 				{

docs/src/assets/screenshots/modify-stack-tui.png

@@ -0,0 +1,101 @@
+---
+title: Restructuring Stacks
+description: How to use `gh stack modify` to restructure a stack.
+---
+
+`gh stack modify` provides an interactive terminal UI for restructuring a stack locally. You can drop, fold, rename, and reorder branches and then apply all your changes at once.
+
+![The modify stack terminal UI](../../../assets/screenshots/modify-stack-tui.png)
+
+## When to use modify
+
+Use `modify` when you need to:
+- **Remove** a branch from the stack
+- **Combine** two branches into one
+- **Rename** a branch
+- **Reorder** branches
+
+## Prerequisites
+
+Before running `modify`, ensure:
+- You have an active stack checked out locally
+- Your working tree is clean (no uncommitted changes)
+- No rebase is in progress
+- No PR in the stack is queued for merge
+- Commit history is linear (run `gh stack rebase` first if needed)
+
+## Opening the TUI
+
+```sh
+gh stack modify
+```
+
+The TUI shows your stack as a vertical list of branches with PR information, commits, and files changed. Merged branches appear as locked rows that cannot be modified. Press `?` for a help overlay describing all operations.
+
+## Operations
+
+### Drop (`x`)
+
+Removes a branch and its commits from the stack. The local branch and any associated PR are preserved. Upstream branches are rebased to exclude the dropped branch's unique commits.
+
+### Fold down (`d`)
+
+Absorbs the selected branch's commits into the branch below it (toward trunk) via cherry-pick. The folded branch is removed from the stack.
+
+### Fold up (`u`)
+
+Absorbs the selected branch's commits into the branch above it (away from trunk). Since the branch above already contains the folded branch's commits in its history, this is handled by adjusting what is considered the first unique commit for the branch. The folded branch is removed from the stack.
+
+### Rename (`r`)
+
+Opens an inline prompt to enter a new name for the branch. The branch is renamed locally and in the stack metadata. On the next `submit`, the new branch name is pushed to GitHub.
+
+### Reorder (`Shift+↑`/`Shift+↓`)
+
+Moves the selected branch up (away from trunk) or down (toward trunk) in the stack. A cascading rebase adjusts all affected branches. Note: reordering and structural changes (drop/fold/rename) cannot be mixed in the same session.
+
+### Undo (`z`)
+
+Reverses the most recent staged action. You can undo multiple times to step back through your changes.
+
+## Applying changes
+
+Press `Ctrl+S` to apply all staged changes. Nothing is modified until you save. The apply phase renames branches, folds/drops branches, and runs a cascading rebase to create a linear commit history with the desired stack state.
+
+### Handling conflicts
+
+If a rebase conflict occurs during the apply phase, you have two options:
+
+1. **Resolve and continue**: Fix the conflicts in your editor, stage with `git add`, then run `gh stack modify --continue` (you may need to do this multiple times)
+2. **Abort**: Run `gh stack modify --abort` to abort the operation and restore the stack to the pre-modify state
+
+If a second conflict occurs after continuing, the same options are available.
+
+## After modifying
+
+If a stack of PRs has been created on GitHub, run:
+
+```sh
+gh stack submit
+```
+
+This pushes the updated branches and recreates the stack. The old stack is automatically replaced.
+
+## Aborting
+
+If you want to discard all changes and restore the stack to its pre-modify state, run:
+
+```sh
+gh stack modify --abort
+```
+
+This also works if `modify` was interrupted (e.g., terminal crash). A pre-modify snapshot is cached locally for state recovery.
+
+## Limitations
+
+- Cannot modify merged branches (they are locked)
+- Cannot add new branches (use `gh stack add` instead)
+- Cannot split a branch into multiple branches
+- Cannot move branches between different stacks
+- Requires an interactive terminal
+- Reordering and structural changes (drop/fold/rename) cannot be mixed in the same session

docs/src/content/docs/guides/modify.md

@@ -168,24 +168,49 @@ All branches in a stack should be part of the same feature or project. If you ne
 
 ## Restructuring a Stack
 
-When you need to remove a branch, reorder branches, or rename branches, tear down the stack and rebuild it:
+When you need to change the composition of a stack — remove a branch, combine branches, change the order, or rename a branch — use `gh stack modify`:
 
 ```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
+# Open the modify TUI
+gh stack modify
+
+# In the TUI:
+#   x     → drop a branch
+#   d     → fold down (into branch below)
+#   u     → fold up (into branch above)
+#   Shift+↑/↓ → reorder
+#   r     → rename
+#   z     → undo
+#   Ctrl+S → apply changes
+#   q     → cancel
+
+# After modifying, push changes to remote and recreate the stack on GitHub
 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.
+### Common restructuring scenarios
+
+**Remove a branch and its unique commits from the stack:**
+1. `gh stack modify`
+2. Navigate to the branch, press `x` to mark it for drop
+3. Press `Ctrl+S` to apply
+4. `gh stack submit`
+
+**Combine two branches into one:**
+1. `gh stack modify`
+2. Navigate to the branch you want to fold
+3. Press `d` to fold its commits into the branch below, or `u` to fold into the branch above
+4. Press `Ctrl+S` to apply
+5. `gh stack submit`
+
+**Reorder branches:**
+1. `gh stack modify`
+2. Navigate to the branch to move
+3. Press `Shift+↑` to move up or `Shift+↓` to move down
+4. Press `Ctrl+S` to apply
+5. `gh stack submit`
+
+For a comprehensive guide on all modify operations, see the [Restructuring Stacks](/gh-stack/guides/modify/) guide.
 
 ## Using AI Agents with Stacks
 

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

@@ -157,6 +157,68 @@ gh stack checkout feature-auth
 gh stack checkout
 ```
 
+### `gh stack modify`
+
+Interactively restructure the current stack.
+
+```sh
+gh stack modify [flags]
+```
+
+Opens an interactive terminal UI for restructuring a stack. All changes are staged in the TUI and applied together when you press `Ctrl+S`. Branches from merged PRs cannot be modified.
+
+| Flag | Description |
+|------|-------------|
+| `--continue` | Continue after resolving conflicts |
+| `--abort` | Abort the modify session and restore the stack to its pre-modify state |
+
+**Preconditions:**
+
+The command checks these conditions before opening the TUI:
+
+1. Must have an active stack checked out locally
+2. Working tree must be clean (no uncommitted changes)
+3. No rebase in progress
+4. No PR in the stack is queued for merge
+5. Commit history must be linear (no merge commits, no diverged branches)
+
+**Operations:**
+
+| Operation | Key | Effect |
+|-----------|-----|--------|
+| Drop | `x` | Remove branch and its commits from stack. Local branch and associated PR are preserved. |
+| Fold down | `d` | Absorb commits into branch below (toward trunk). Folded branch removed from stack. |
+| Fold up | `u` | Absorb commits into branch above (away from trunk). Folded branch removed from stack. |
+| Move down | `Shift+↓` | Reorder branch down (toward trunk) in the stack |
+| Move up | `Shift+↑` | Reorder branch up (away from trunk) in the stack |
+| Rename | `r` | Rename the branch (opens inline prompt) |
+| Undo | `z` | Undo the last staged action |
+
+**Apply phase:**
+
+When you press `Ctrl+S`, the staged changes are applied by renaming branches, folding/dropping branches, and running a cascading rebase to create a linear commit history with the desired stack state.
+
+If a rebase conflict occurs, you can:
+- Resolve conflicts, stage files, and run `gh stack modify --continue`
+- Or run `gh stack modify --abort` to abort the operation and restore the stack to the pre-modify state
+
+**After modifying:**
+
+If a stack of PRs has been created on GitHub, run `gh stack submit` to push the updated branches and recreate the stack. The old stack is automatically replaced.
+
+**Examples:**
+
+```sh
+# Open the interactive modify TUI
+gh stack modify
+
+# Continue after resolving a conflict
+gh stack modify --continue
+
+# Abort and restore to the previous state
+gh stack modify --abort
+```
+
 ---
 
 ## Remote Operations