glab-stack

glab stack

Worktree-local selection

The current stack selection is tracked per Git worktree. Select and inspect the intended stack from the worktree where you will operate; switching stacks in one worktree does not select that stack in another. Stack data and repository refs can still be shared, so this does not remove the need to review destructive or publishing actions.

Overview

A stack is a series of small, dependent merge requests delivering one feature. Locally, each diff is one commit on its own branch, based on the preceding diff's branch. Sync creates an MR targeting the preceding branch; the first diff targets the base branch.

Stack commands operate on the stack last created or switched to, regardless of the currently checked-out branch. Inspect that active stack before a mutation. This feature remains experimental. See references/commands.md for complete checksum-verified parent/subcommand help, including current terminology and examples.

Quick start

glab stack --help

Current behavior

Generated stack branches use {branch_prefix}-{stack-title}-{hash}. If branch_prefix is unset, glab uses the operating system account username (and removes a Windows domain prefix), falling back to glab-stack only when user lookup is unavailable. It does not rely on $USER; set glab config set branch_prefix <value> when automation requires a stable explicit prefix.

glab stack infer <revision-range> creates or appends stack layers from selected commits in a Git revision range. The start of the range must resolve to a branch name, not a relative ref such as HEAD~5, because the base branch is recorded in stack metadata.

# Infer stack layers from commits between main and the current branch
glab stack infer main..HEAD

# Infer from a feature branch that diverged from develop
glab stack infer develop..HEAD

# If no stack is active, create one with a specific name
glab stack infer --name feature-stack main..HEAD

When a stack is active, infer appends to that stack and ignores --name. Inspect the active stack first; use glab stack create or glab stack switch to select a different destination before inferring unrelated work.

glab stack sync supports --update-base, --assignee, --label, --reviewer, --skip-mr-creation, and --skip-push.

# Sync stack and rebase onto the latest base branch
glab stack sync --update-base

# Sync/push existing stack work without opening MRs for branches that do not have one yet
glab stack sync --skip-mr-creation

# Fetch and rebase the stack locally without pushing branches or creating MRs
glab stack sync --skip-push

# Sync stack and set MR metadata during submission
glab stack sync --assignee @owner --reviewer @reviewer --label backend

# Multiple reviewers can be repeated or comma-separated
glab stack sync --reviewer user1 --reviewer user2
glab stack sync --reviewer user1,user2

Use --update-base when the base branch (for example main) has moved and you want to rebase the entire stack before pushing.

Use --skip-mr-creation when you want to push amended stack branches and clean up merged entries but intentionally avoid opening new merge requests for stack layers that do not have one yet. Diffs whose merge requests are closed are kept in the stack.

Use --skip-push when you want to fetch and rebase the stack locally without pushing branches or creating merge requests. This is not an offline mode: glab still fetches from the remote and calls the GitLab API. Review the rewritten local history before a later push.

Use --assignee, --reviewer, and --label when you want glab stack sync to submit the stack's merge requests with ownership and routing metadata in the same step.

During stack sync pushes, glab streams Git hook output to stdout/stderr as it runs. Preserve that output in automation logs: a failing pre-push hook is returned as the push error instead of being hidden behind buffered output.

glab stack switch can now be run without a stack name to choose interactively from all stacks. Pass the stack name for non-interactive automation.

glab stack amend supports --reword to update only the stacked commit message without staging files. It cannot be combined with file arguments or --all; pass -m/--message or -d/--description, or let glab open the editor.

glab stack amend --reword -m "updated commit message"

glab stack amend and glab stack save support --no-verify to bypass local pre-commit and commit-msg hooks for the underlying Git commit. Treat it like git commit --no-verify: use only when the skipped hooks are understood and intentionally bypassed.

Reorder and recovery

glab stack reorder opens the current stack order in an editor, rebases each branch onto its new parent, and retargets moved merge requests on GitLab. It does not push branches, but it is a remote-write operation, not a dry run; approve MR target changes before running it. Run glab stack sync after reviewing the rewritten history to force-push the rebased branches.

glab stack reorder

# After resolving a rebase conflict and running git rebase --continue
glab stack reorder --continue

# Restore the original branch order instead
glab stack reorder --abort

Do not start another reorder while a reorder rebase is in progress. Resolve and continue, or abort, before retrying. Preserve the conflict and rebase output in automation logs.

Delete local stack metadata

# Choose a stack interactively
glab stack delete

# Delete a named stack after confirmation
glab stack delete <stack-name>

# Approved non-interactive deletion
glab stack delete <stack-name> --yes

Deletion removes only the stack's local stacked-metadata directory. It does not delete branches, commits, or merge requests. Verify the stack name and repository before --yes, then confirm the named directory is absent under $(git rev-parse --git-common-dir)/stacked/. This read-only check works for both ordinary checkouts and linked worktrees; glab stack list only lists layers in the current stack and cannot verify that a different stack was deleted.

Subcommands

• create: Create and activate a new stack.
• switch: Select a different active stack.
• infer: Add diffs from a Git revision range to the active stack, or create a stack if none is active.
• save: Save changes as a new diff.
• amend: Save changes to an existing diff.
• list: List all diffs in the active stack.
• first: Move to the first diff.
• last: Move to the last diff.
• next: Move to the next diff.
• prev: Move to the previous diff.
• move: Move to a specific diff.
• reorder: Rebase the reordered diffs and retarget moved MRs on GitLab without pushing branches.
• sync: Push the stack and create or update its merge requests, subject to the skip flags above.
• delete: Delete local stack metadata, not branches, commits, or MRs.

See references/commands.md for full --help output.