--- name: glab-stack description: Manage stacked diffs and merge requests with the GitLab CLI. Use when the user wants to create, save, amend, sync, navigate, reorder, or infer from commits a stack of dependent merge requests. Triggers on tasks involving stacked diffs, stacked MRs, dependent merge requests, or incremental code review workflows using `glab stack`. --- # glab stack `glab stack` is a feature of the [GitLab CLI](https://gitlab.com/gitlab-org/cli) for managing **stacked diffs**: small, dependent changes that build on each other to deliver a larger feature. Each diff in the stack is a separate branch with its own MR. Reviewers see only the changes in their diff; you keep building while earlier changes are in review. > **Status:** Experiment, released in GitLab CLI v1.42.0. The interface may change. ## How glab stack works `glab stack` uses a **save-centric model**: `glab stack save` bundles staging, committing, and branch creation into a single step. There are no separate Git operations for creating stack branches — the CLI manages branch creation automatically. Stack metadata lives in `.git/stacked/` in the repo. Each diff gets its own branch named `{branch_prefix}-{stack-title}-{8-char-hex}`. The branch prefix defaults to the current user's username (from `os/user.Current`), falling back to `glab-stack` if unavailable; it can also be set with `glab config set branch_prefix `. The hash is generated at save time from the message, title, author, and timestamp — branch names are not sequential or predictable in advance. Use `glab stack list` to see the current branch names for each diff. ```text main (default branch) └── karmstrong-add-auth-5b337685 → MR !1 (targets main) ← first diff (oldest) └── karmstrong-add-auth-74f87791 → MR !2 (targets karmstrong-add-auth-5b337685) └── karmstrong-add-auth-c3a91b02 → MR !3 (targets karmstrong-add-auth-74f87791) ← last diff (newest) ``` Stack names are sanitized on creation: spaces and special characters are replaced with dashes. The name `"add auth feature"` becomes `add-auth-feature`. Always use the sanitized form with `glab stack switch`. You can have multiple named stacks per repo and switch between them with `glab stack switch`. ## When to use stacks Stacks work well when: - A feature is large enough that a single MR would be hard to review - Changes have a clear dependency order — data layer feeds the API layer feeds the UI - You want to unblock reviewers on completed diffs while you keep building - Feedback on one diff shouldn't block progress on the diffs after it Each diff should represent a discrete, logical concern that can be reviewed independently. A reviewer reading the MRs in sequence should understand the progression as a cohesive story. ## Agent rules **These commands launch interactive TUIs or prompt for input — they hang or fail without a TTY:** - ❌ `glab stack move` — fuzzy-finder for selecting a diff; agents cannot interact with it - ❌ `glab stack reorder` without arguments — opens a text editor to reorder diffs, or fails without a TTY; pass branch names in order instead (`glab stack reorder ...`) - ❌ `glab stack infer` without `--all` — opens a text editor to select commits, or fails without a TTY; pass `--all` instead (`glab stack infer --all `) - ❌ `glab stack save` without `-m` — prompts interactively for a commit message if none is provided - ❌ `glab stack amend` without `-m` — prompts interactively for a description if none is provided - ❌ `glab stack create` without a name argument — may prompt **Always do the following:** 1. **Always pass `-m` to `save` and `amend`.** This is the most common footgun — without it, the CLI prompts interactively and hangs. 2. **Use `glab stack list` to inspect the stack, not `glab stack move`.** `list` is non-interactive; `move` is not usable by agents. 3. **Navigate with `first`, `last`, `prev`, `next`.** These are all non-interactive. Do not use `move` for navigation. 4. **Pass an explicit name to `glab stack switch`.** Stack names are the directory names under `.git/stacked/`. Note: `switch` only changes the active stack in config — it does not check out any branch. After switching, use `glab stack last` (or `first`, `next`, etc.) to move to a diff in the new stack. 5. **To reorder diffs non-interactively**, run `glab stack reorder ...` with the branches in the desired order. Run `glab stack list` first to get the branch names. - List every branch in the stack exactly once. A missing, unknown, or duplicate branch is an error. - The first branch becomes the diff closest to the base branch; the last becomes the newest. - Commit or stash tracked changes first. `reorder` refuses to run with uncommitted changes. - `reorder` rebases branches locally only. Run `glab stack sync` afterwards to force-push them. 6. **To infer diffs from a commit range non-interactively**, run `glab stack infer --all `. If no stack is active, also pass `--name `, or `infer` fails without a TTY. ## Stack structure Plan your diff boundaries before writing code. Earlier diffs (closer to main) are the foundation; later diffs depend on them. If code in one diff depends on code in another, the dependency must be in the same diff or an earlier one. **`save` vs `amend`:** - `glab stack save` — creates a **new** diff (new commit, new branch). Use when adding a new logical concern on top of what exists. - `glab stack amend` — modifies the diff you have **checked out**. Use when addressing review feedback or fixing a mistake in that diff. **Important:** If you navigate to an earlier diff and run `save` instead of `amend`, the CLI will warn you but still proceed — appending the new diff to the **end** of the stack, not inserting it at the current position. Always use `amend` when you've navigated to a specific diff to address feedback. Only use `save` from the last diff in the stack. For precise control over which files go into a diff, stage with `git add ` first, then `glab stack save -m "..."`. For convenience, `-a` stages all tracked/modified files, and passing `.` stages everything including untracked files. ## Quick reference | Task | Command | | ---- | ------- | | Create a new stack | `glab stack create ` | | Save staged changes as a new diff | `glab stack save -m "description"` | | Stage all tracked files and save | `glab stack save -a -m "description"` | | Stage all files (incl. untracked) and save | `glab stack save . -m "description"` | | Amend the diff you have checked out | `glab stack amend -m "description"` | | Amend with all tracked files staged | `glab stack amend -a -m "description"` | | Push branches and create/update MRs | `glab stack sync` | | Sync and set reviewer/assignee/label | `glab stack sync --reviewer --assignee --label