## Summary While reviewing stack-related MRs for `glab`, several points of confusion came up in the stacked diffs / `glab stack` documentation. This issue tracks reviewing and clarifying those docs. (Raised from an internal Slack thread; may contain additional concepts to clarify beyond the starting points below.) ## Docs affected - User docs: [Stacked diffs](https://docs.gitlab.com/user/project/merge_requests/stacked_diffs/) (source: [`doc/user/project/merge_requests/stacked_diffs.md`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/project/merge_requests/stacked_diffs.md)) - CLI command reference: [`glab stack move`](https://docs.gitlab.com/cli/stack/move/) and [`glab stack switch`](https://docs.gitlab.com/cli/stack/switch/) (source: [`docs/source/stack/`](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source/stack) in `gitlab-org/cli`) ## Points to clarify 1. **Terminology: stacked diffs vs. stacked MRs.** Confirm and document the mapping: local diffs in a stack become one MR each after `glab stack sync` (each MR targets the previous diff's branch, except the first). Is it accurate to say "stacked diffs locally become stacked MRs in the UI once you sync"? 2. **`glab stack move` synopsis is ambiguous.** The [command reference](https://docs.gitlab.com/cli/stack/move/) says "Shows a menu with a fuzzy finder to select a stack", but based on the [implementation](https://gitlab.com/gitlab-org/cli/-/blob/main/internal/commands/stack/navigate/stack_navigate.go), it selects a **diff within the current stack** (it iterates the current stack's refs and checks out the chosen branch). The short description "Moves to any selected entry in the stack" is correct; the synopsis should say "select a diff" instead of "select a stack". 3. **Contrast with `glab stack switch`.** [`glab stack switch`](https://docs.gitlab.com/cli/stack/switch/) is the command that selects a **stack** ("Switch between stacks to work on another stack created with `glab stack create`"). The `move` and `switch` docs should cross-reference each other so the distinction (diff within a stack vs. switching stacks) is clear. 4. **"Add changes to a diff in a stack" steps are incomplete.** The [user docs section](https://docs.gitlab.com/user/project/merge_requests/stacked_diffs/#add-changes-to-a-diff-in-a-stack) says to run `glab stack move` and "Select the stack you want to edit", but `glab stack move` selects a diff, not a stack. The steps should: - If needed, first switch to the right stack with `glab stack switch`. - Then run `glab stack move` and select the **diff** within the stack to edit. ## Suggested edits - Update the `glab stack move` synopsis (CLI help text in `stack_navigate.go`, which generates `docs/source/stack/move.md`) from "select a stack" to "select a diff". - Update the "Add changes to a diff in a stack" section of the stacked diffs user docs to reference selecting a diff (and optionally switching stacks first via `glab stack switch`). - Confirm the "stacked diffs become stacked MRs after sync" wording in the user docs intro. ## Additional context - Stacked diffs are an [experiment](https://docs.gitlab.com/policy/development_stages_support/) (released in GitLab CLI v1.42.0); general feedback is tracked in [cli#7473](https://gitlab.com/gitlab-org/cli/-/issues/7473). - There may be more concepts worth clarifying beyond this list; this thread's questions are a starting point. <!-- implementation plan added during 2026-09 backlog triage --> ## Implementation plan > **Note:** This plan was drafted during an AI-assisted triage of the backlog and has not been validated by a maintainer. Treat it as a starting point: file paths, line numbers, and the approach may need adjusting. Two changes, in two repositories. The `gitlab-org/cli` part is self-contained and small. 1. `internal/commands/stack/navigate/stack_navigate.go`, `NewCmdStackMove` (line 182): replace the `Long` string `"Shows a menu with a fuzzy finder to select a stack."` with wording that matches the code. The command iterates the current stack's refs (`stack.Iter()`, lines 189-195) and prompts `"Choose a diff to be checked out:"` (line 199), so it should say it shows a list of the diffs in the current stack and checks out the one you pick, and point at `glab stack switch` for changing to a different stack. Keep the trailing `+ text.ExperimentalString`. Note the list is a `huh.NewSelect` filtered by pressing `/`, so "menu with a filter" is more accurate than "fuzzy finder". 2. `internal/commands/stack/switch/switch.go`, `NewCmdStackSwitch` `Long` (line 21): add one line pointing at `glab stack move` for moving between diffs inside the current stack, so the two pages cross-reference each other. 3. Run `make gen-docs` and commit the regenerated `docs/source/stack/move.md` and `docs/source/stack/switch.md` in the same commit. Never edit files under `docs/source/` directly. 4. No unit test is needed: this is help text only, `internal/commands/stack/navigate/` has no test file, and the generated-doc drift check in `lefthook run pre-push` covers the regeneration. 5. Separate MR in `gitlab-org/gitlab` against `doc/user/project/merge_requests/stacked_diffs.md`, section "Add changes to a diff in a stack": change "Display a list of stacks" to refer to the diffs in the current stack, change "Select the stack you want to edit" to "Select the diff you want to edit", and add an optional preceding step to run `glab stack switch` first if the diff is in another stack. 6. In that same MR, add a `switch` row to the "Available commands" table on that page (it currently lists create, save, amend, prev, next, first, last, move, and sync, but not `switch`; `list` and `reorder` are also missing). Point 1 in the description needs no change: the intro of the same page already states that `glab stack sync` creates one merge request per diff and chains them, each except the first targeting the previous diff's branch.