@@ -55,9 +55,9 @@ GitHub understands stacks end-to-end: the pull request UI shows a **stack map**
## How It Works
-The `gh stack` CLI handles the local workflow: creating branches, keeping them rebased, pushing to GitHub, and creating PRs with the correct base branches. On GitHub, the PR UI gives reviewers the context they need β a stack map for navigation, focused diffs for each layer, and proper rules enforcement.
+The `gh stack` CLI handles the local workflow: creating branches, managing rebases, pushing to GitHub, and creating PRs with the correct base branches. On GitHub, the PR UI gives reviewers the context they need β a stack map for navigation, focused diffs for each layer, and proper rules enforcement.
-When you're ready to merge, you merge from the bottom up. Each PR can be merged directly or through the merge queue. When a PR at the bottom is merged, the remaining stack is automatically rebased so the next PR targets `main` and is ready for its own merge.
+When you're ready to merge, you can merge all or a part of the stack. Each PR can be merged directly or through the merge queue. After a merge, the remaining PRs in the stack are automatically rebased so the lowest unmerged PR targets the base branch.
## Get Started
@@ -65,19 +65,24 @@ When you're ready to merge, you merge from the bottom up. Each PR can be merged
# Install the CLI extension
gh extension install github/gh-stack
-# Create a stack (creates and checks out the first branch)
-gh stack init auth-layer
+# Alias `gh stack` as `gs` for easier use (optional)
+gh stack alias
+
+# Start a stack (creates and checks out the first branch)
+gs init auth-layer
# ... make commits ...
-gh stack add api-routes
+
+# Create new layers in the stack (creates and checks out each new branch)
+gs add api-routes
# ... make commits ...
-gh stack add frontend
+gs add frontend
# ... make commits ...
# Push all branches
-gh stack push
+gs push
# Open a stack of PRs
-gh stack submit
+gs submit
```
Ready to dive in? Start with the [Quick Start guide](/gh-stack/getting-started/quick-start/) or read the [full overview](/gh-stack/introduction/overview/).
diff --git a/docs/src/content/docs/introduction/overview.md b/docs/src/content/docs/introduction/overview.md
index 20a3024..947dd07 100644
--- a/docs/src/content/docs/introduction/overview.md
+++ b/docs/src/content/docs/introduction/overview.md
@@ -3,7 +3,7 @@ title: Overview
description: What stacked pull requests are, why they matter, and how GitHub supports them natively.
---
-## The Challenge
+## Why Stacks?
For developers who want to break large changes into smaller, dependent parts, the experience can be painful:
@@ -89,8 +89,9 @@ While the PR UI provides the review and merge experience, the `gh stack` CLI han
- **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.
+- **Checking out a stack** β `gh stack checkout
` pulls down a stack, with all its branches, from GitHub to your local machine.
-The CLI is not required to use Stacked PRs β the underlying git operations are standard. But it makes the workflow dramatically simpler.
+The CLI is not required to use Stacked PRs β the underlying git operations are standard. But it makes the workflow simpler, and you can create Stacked PRs from the CLI instead of the UI.
## Thinking About Stack Structure
diff --git a/docs/src/content/docs/reference/cli.md b/docs/src/content/docs/reference/cli.md
index 3146773..5853d9f 100644
--- a/docs/src/content/docs/reference/cli.md
+++ b/docs/src/content/docs/reference/cli.md
@@ -138,7 +138,7 @@ Check out a stack from a pull request number or branch name.
gh stack checkout [ | ]
```
-When a PR number is provided (e.g. `123`), the command fetches the stack on GitHub, pulls the branches, and sets up the stack locally. If the stack already exists locally and matches, it switches to the branch. If the local and remote stacks have different compositions, you'll be prompted to resolve the conflict.
+When a PR number is provided (e.g., `123`), the command fetches the stack on GitHub, pulls the branches, and sets up the stack locally. If the stack already exists locally and matches, it switches to the branch. If the local and remote stacks have different compositions, you'll be prompted to resolve the conflict.
When a branch name is provided, the command resolves it against locally tracked stacks only.
@@ -197,11 +197,11 @@ gh stack sync [flags]
Performs a safe, non-interactive synchronization of the entire stack:
-1. **Fetch** β fetches the latest changes from `origin`
-2. **Fast-forward trunk** β fast-forwards the trunk branch to match the remote (skips if diverged)
-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
+1. **Fetch** β fetches the latest changes from `origin`.
+2. **Fast-forward trunk** β fast-forwards the trunk branch to match the remote (skips if diverged).
+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.
| Flag | Description |
|------|-------------|
diff --git a/docs/src/styles/custom.css b/docs/src/styles/custom.css
index 2cedbb5..703db78 100644
--- a/docs/src/styles/custom.css
+++ b/docs/src/styles/custom.css
@@ -11,3 +11,19 @@
--sl-color-accent: #4f46e5;
--sl-color-accent-high: #312e81;
}
+
+/* Show full nav by default, switch to hamburger on narrow viewports */
+@media (max-width: 900px) {
+ .custom-header-links {
+ display: none !important;
+ }
+ .tablet-nav-wrapper {
+ display: block !important;
+ }
+}
+
+@media (min-width: 901px) {
+ .tablet-nav-wrapper {
+ display: none !important;
+ }
+}
diff --git a/skills/gh-stack/SKILL.md b/skills/gh-stack/SKILL.md
index d5e2a8f..1dc3a51 100644
--- a/skills/gh-stack/SKILL.md
+++ b/skills/gh-stack/SKILL.md
@@ -41,18 +41,35 @@ The GitHub CLI (`gh`) v2.0+ must be installed and authenticated. Install the ext
gh extension install github/gh-stack
```
+Before using `gh stack`, configure git to prevent interactive prompts:
+
+```bash
+git config rerere.enabled true # remember conflict resolutions (skips prompt on init)
+git config remote.pushDefault origin # if multiple remotes exist (skips remote picker)
+```
+
## Agent rules
-1. **Always supply branch names as positional arguments** to `init`, `add`, and `checkout`.
+**All `gh stack` commands must be run non-interactively.** Every command invocation must include the flags and positional arguments needed to avoid prompts, TUIs, and interactive menus. If a command would prompt for input, it will hang indefinitely.
+
+1. **Always supply branch names as positional arguments** to `init`, `add`, and `checkout`. Running these commands without arguments triggers interactive prompts.
2. **When a prefix is set, pass only the suffix to `add`.** `gh stack add auth` with prefix `feat` β `feat/auth`. Passing `feat/auth` creates `feat/feat/auth`.
-3. **Always use `--auto` when pushing** to skip PR title prompts.
-4. **Always use `--json` when viewing** to get structured output.
-5. **Use `--remote ` when multiple remotes are configured**, or set `remote.pushDefault` in git config.
+3. **Always use `--auto` with `gh stack submit`** to auto-generate PR titles. Without `--auto`, `submit` prompts for a title for each new PR.
+4. **Always use `--json` with `gh stack view`.** Without `--json`, the command launches an interactive TUI that cannot be operated by agents. There is no other appropriate flag β always pass `--json`.
+5. **Use `--remote ` when multiple remotes are configured**, or pre-configure `git config remote.pushDefault origin`. Without this, `push`, `submit`, `sync`, and `checkout` trigger an interactive remote picker.
6. **Avoid branches shared across multiple stacks.** If a branch belongs to multiple stacks, commands exit with code 6. Check out a non-shared branch first.
7. **Plan your stack layers by dependency order before writing code.** Foundational changes (models, APIs, shared utilities) go in lower branches; dependent changes (UI, consumers) go in higher branches. Think through the dependency chain before running `gh stack init`.
8. **Use standard `git add` and `git commit` for staging and committing.** This gives you full control over which changes go into each branch. The `-Am` shortcut is available but should not be the default approachβstacked PRs are most effective when each branch contains a deliberate, logical set of changes.
9. **Navigate down the stack when you need to change a lower layer.** If you're working on a frontend branch and realize you need API changes, don't hack around it at the current layer. Navigate to the appropriate branch (`gh stack down`, `gh stack checkout`, or `gh stack bottom`), make and commit the changes there, run `gh stack rebase --upstack`, then navigate back up to continue.
+**Never do any of the following β each triggers an interactive prompt or TUI that will hang:**
+- β `gh stack view` or `gh stack view --short` β always use `gh stack view --json`
+- β `gh stack submit` without `--auto` β always use `gh stack submit --auto`
+- β `gh stack init` without branch arguments β always provide branch names
+- β `gh stack add` without a branch name β always provide a branch name
+- β `gh stack checkout` without an argument β always provide a PR number or branch name
+- β `gh stack checkout ` when a different local stack already exists on those branches β this triggers an unbypassable conflict resolution prompt; use `gh stack unstack` first to remove the local stack, then retry the checkout
+
## Thinking about stack structure
Each branch in a stack should represent a **discrete, logical unit of work** that can be reviewed independently. The changes within a branch should be cohesiveβthey belong together and make sense as a single PR.
@@ -378,10 +395,10 @@ gh stack init --base main --adopt new-branch-1 new-branch-2 new-branch-3
### Initialize a stack β `gh stack init`
-Creates a new stack. Provide branch names as positional arguments.
+Creates a new stack. **Always provide at least one branch name as a positional argument** β running without branch arguments triggers interactive prompts that agents cannot use.
```
-gh stack init [branches...] [flags]
+gh stack init [flags]
```
```bash
@@ -415,16 +432,16 @@ gh stack init --adopt branch-a branch-b branch-c
- Creates any branches that don't already exist (branching from the trunk branch)
- In `--adopt` mode: validates all branches exist, rejects if any is already in a stack or has an existing PR
- Checks out the last branch in the list
-- Enables `git rerere` so conflict resolutions are remembered across rebases
+- Enables `git rerere` so conflict resolutions are remembered across rebases. On first run in a repo, this may trigger a confirmation prompt β pre-configure with `git config rerere.enabled true` to avoid it
---
### Add a branch β `gh stack add`
-Add a new branch on top of the current stack. Must be run while on the topmost branch (or the trunk if the stack has no branches yet). Always provide an explicit branch name.
+Add a new branch on top of the current stack. Must be run while on the topmost branch (or the trunk if the stack has no branches yet). **Always provide a branch name** β running without one triggers an interactive prompt.
```
-gh stack add [branch] [flags]
+gh stack add [flags]
```
**Recommended workflow β create the branch, then use standard git:**
@@ -501,14 +518,10 @@ gh stack push --remote upstream
### Submit branches and create PRs β `gh stack submit`
-Push all stack branches and create PRs on GitHub.
-
-```
-gh stack submit [flags]
-```
+Push all stack branches and create PRs on GitHub. **Always pass `--auto`** β without it, `submit` prompts for a PR title for each new branch.
```bash
-# Submit and auto-title new PRs
+# Submit and auto-title new PRs (required for non-interactive use)
gh stack submit --auto
# Submit and create PRs as drafts
@@ -517,7 +530,7 @@ gh stack submit --auto --draft
| Flag | Description |
|------|-------------|
-| `--auto` | Auto-generate PR titles without prompting |
+| `--auto` | Auto-generate PR titles without prompting (**required** for non-interactive use) |
| `--draft` | Create new PRs as drafts |
| `--remote ` | Remote to push to (use if multiple remotes exist) |
@@ -578,7 +591,7 @@ gh stack sync [flags]
Pull from remote and cascade-rebase stack branches. Use this when `sync` reports a conflict or when you need finer control (e.g., rebase only part of the stack).
```
-gh stack rebase [branch] [flags]
+gh stack rebase [flags] [branch]
```
```bash
@@ -620,20 +633,16 @@ gh stack rebase --abort
### View the stack β `gh stack view`
-Display the current stack's branches, PR status, and recent commits. Use `--json` for structured output.
-
-```
-gh stack view [flags]
-```
+Display the current stack's branches, PR status, and recent commits. **Always pass `--json`** β without it, this command launches an interactive TUI that agents cannot operate.
```bash
-# Structured JSON output (recommended)
+# Always use --json
gh stack view --json
```
| Flag | Description |
|------|-------------|
-| `--json` | Output stack data as JSON to stdout |
+| `--json` | Output stack data as JSON to stdout (**required** for non-interactive use) |
**`--json` output format:**
@@ -682,8 +691,6 @@ Fields per branch:
- `needsRebase` β whether the base branch is not an ancestor (non-linear history)
- `pr` β PR metadata (omitted if no PR exists). `state` is `"OPEN"` or `"MERGED"`.
-> **Note:** `--short` outputs a compact text view with box-drawing characters and status icons. Prefer `--json` for programmatic use.
-
---
### Navigate the stack
@@ -705,7 +712,7 @@ Navigation clamps to stack bounds. Merged branches are skipped when navigating f
### Check out a stack β `gh stack checkout`
-Check out a stack from a pull request number or branch name.
+Check out a stack from a pull request number or branch name. **Always provide an argument** β running `gh stack checkout` without arguments triggers an interactive selection menu.
```
gh stack checkout
@@ -719,9 +726,11 @@ gh stack checkout 42
gh stack checkout feature-auth
```
-When a PR number is provided (e.g. `123`), the command fetches the stack on GitHub, pulls the branches, and sets up the stack locally. If the stack already exists locally and matches, it switches to the branch. If the local and remote stacks have different compositions, you'll be prompted to resolve the conflict by deciding whether to replace the local stack with the remote version or delete the remote stack and keep the local version.
+When a PR number is provided (e.g. `123`), the command fetches the stack on GitHub, pulls the branches, and sets up the stack locally. If the stack already exists locally and matches, it switches to the branch.
+
+> **β οΈ Agent warning:** If the local and remote stacks have different branch compositions, this command triggers an interactive conflict-resolution prompt that cannot be bypassed with a flag. To avoid this: run `gh stack unstack` first to remove the conflicting local stack, then retry `gh stack checkout `.
-When a branch name is provided, the command resolves it against locally tracked stacks only.
+When a branch name is provided, the command resolves it against locally tracked stacks only. This is always safe for non-interactive use.
---
@@ -730,7 +739,7 @@ When a branch name is provided, the command resolves it against locally tracked
Tear down a stack so you can restructure it β remove a branch, reorder branches, rename branches, or make other large changes. After unstacking, use `gh stack init` to re-create the stack with the desired structure.
```
-gh stack unstack [branch] [flags]
+gh stack unstack [flags] [branch]
```
```bash