From mergify
Guides Claude Code to use `mergify stack` commands for push, commit, branch, and PR management. Handles stack editing, reordering, fixup, squashing, and note attachments for revision history.
How this skill is triggered — by the user, by Claude, or both
Slash command
/mergify:mergify-stackThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A branch is a stack. Keep stacks short and focused:
A branch is a stack. Keep stacks short and focused:
Proactive stack management:
mergify stack push (never git push)git commit --amend (never create new commits to fix issues)mergify stack note BEFORE mergify stack push to record why the commit was amended. The note appears in the PR's "Revision history" comment and JSON marker, so reviewers can see the reason without diffing.git stash -u), then use mergify stack edit <SHA-or-Change-Id-prefix> to pause the rebase at the target commit. Amend it with git commit --amend, then git rebase --continue, then mergify stack push, then git stash pop. Non-interactive — never use git rebase -i for this. (Calling mergify stack edit with no argument falls back to a fully interactive git rebase -i and will hang in agent contexts — always pass a commit prefix.)git stash -u), then use mergify stack reorder (list all commits in desired order) or mergify stack move (move a single commit) instead of manual git rebase -i — non-interactive and avoids GIT_SEQUENCE_EDITOR quoting issuesgit stash -u), then use mergify stack fixup <SHA>... to fold a commit into its parent (drops the listed commit's message). Non-interactive — never use git rebase -i for this.git stash -u), then use mergify stack squash SRC... into TARGET [-m "msg"] to combine multiple commits into one, with an optional custom message. Non-interactive — never use git rebase -i for this.git stash -u), then use mergify stack reword <SHA> -m "new message" to change a commit's message in place. Non-interactive when -m is given — never use git rebase -i for this.git stash -u), then use mergify stack drop <SHA>... to remove commits from the stack. Non-interactive — never use git rebase -i for this.feat:, fix:, docs:)mergify stack copies the commit message title to the PR title and the commit message body to the PR body — so write commit messages as if they were PR descriptions. Everything that should appear in the PR (ticket references, context, test plans) MUST go in the commit message.MRGFY-1234, Fixes #123) in the commit message body, not added separately to the PR.mergify stack: NEVER edit PR titles, bodies, or labels with gh pr edit or the GitHub MCP — they will be overwritten on the next push. NEVER close or merge PRs manually — mergify stack handles the entire PR lifecycle (creation, updates, and cleanup).| Wrong | Right | Why |
|---|---|---|
git push | mergify stack push | Git push bypasses stack management and breaks PR relationships |
| New commit to fix lint/typo | git commit --amend (HEAD) or git commit --fixup <SHA> + git rebase --autosquash (mid-stack) | Each commit = a PR; fix commits create unwanted extra PRs |
gh pr edit --title "..." | Edit the commit message, then mergify stack push | PR title/body are overwritten from commit messages on every push |
gh pr merge or gh pr close | PR lifecycle is fully managed — do nothing | PR lifecycle is fully managed by the stack tool |
git commit on main | mergify stack new <name> first | mergify stack push will fail on the default branch |
git rebase -i to fixup a commit | mergify stack fixup <SHA> | Non-interactive — works inside LLM/agent sessions; no editor spawned |
git rebase -i to squash commits | mergify stack squash A B into X [-m "..."] | Non-interactive — works inside LLM/agent sessions; no editor spawned |
git rebase -i to change a commit message | mergify stack reword <SHA> -m "..." | Non-interactive — works inside LLM/agent sessions; no editor spawned |
git rebase -i to amend a mid-stack commit | mergify stack edit <SHA-or-Change-Id-prefix> then git commit --amend then git rebase --continue | Non-interactive — pauses the rebase at the target commit without spawning an editor |
git rebase -i to drop a commit | mergify stack drop <SHA>... | Non-interactive — works inside LLM/agent sessions; no editor spawned |
GIT_SEQUENCE_EDITOR='sed -i ...' git rebase -i (any variant) | One of mergify stack {edit,fixup,squash,reorder,move} | Hand-rolled sequence-editor scripts are brittle; there is already a non-interactive command for every common rewrite |
| Deferring lint fixes to a later commit | Include the fix in the commit that caused it | Each commit runs CI independently; later commits won't save earlier ones |
| Rebase/reorder/checkout/sync with dirty worktree | git stash -u first, then git stash pop after | Uncommitted changes are lost or cause conflicts during these operations |
| Amending a pushed commit with no explanation | mergify stack note -m "why" before mergify stack push | The reason is recorded in the PR's Revision history table and JSON marker, so reviewers don't need to diff to understand the change |
mergify stack new NAME # Create a new stack/branch for new work
mergify stack push # Push and create/update PRs
mergify stack checkout NAME # Checkout an existing stack from GitHub (e.g. someone else's)
mergify stack sync # Fetch trunk, remove merged commits, rebase
mergify stack list # Show commit <-> PR mapping for current stack
mergify stack list --json # Same, but machine-readable JSON output
mergify stack reorder C A B # Reorder all commits (pass SHA or Change-Id prefixes)
mergify stack move X first # Move commit X to the top of the stack
mergify stack move X last # Move commit X to the bottom of the stack
mergify stack move X before Y # Move commit X before commit Y
mergify stack move X after Y # Move commit X after commit Y
mergify stack fixup X # Fold commit X into its parent (drops X's message)
mergify stack fixup X Y Z # Fold each into its parent (multi-fixup)
mergify stack squash X into Y # Reorder X adjacent to Y, fold X into Y (keeps Y's message)
mergify stack squash X Y into Z -m "msg" # Fold X Y into Z with a custom message
mergify stack reword X -m "msg" # Change commit X's message non-interactively
mergify stack reword X # Change commit X's message via $GIT_EDITOR (TTY only)
mergify stack edit X # Pause the rebase at X so you can `git commit --amend` it (X is required; no-arg form is interactive)
mergify stack drop X # Drop commit X from the stack
mergify stack drop X Y Z # Drop multiple commits in one rebase
mergify stack note -m "why" # Attach an amend reason to HEAD (shown in PR revision history)
mergify stack note <SHA-or-Change-Id-prefix> -m "why" # Attach to a specific commit in the stack
mergify stack note --append -m "more" # Append to an existing note
mergify stack note --remove # Remove the note from a commit
Use mergify stack checkout NAME to check out a stack that exists on GitHub (e.g. a colleague's stack). NAME is the remote branch name of the stack. It fetches all stacked PRs, creates a local branch, and sets up tracking. Use --branch to override the local branch name.
Use mergify stack sync to bring your stack up to date. It fetches the latest trunk, detects which PRs have been merged, removes those commits from your local branch, and rebases the remaining commits. Run this before starting new work on an existing stack.
Use mergify stack list to see which commits have been pushed, which PRs they map to, and whether the stack is up to date with the remote. It also shows CI status, review status, and merge conflicts for each PR. Use --verbose for detailed check names and reviewer names. Use --json when you need to parse the output programmatically — it includes full CI check details and review data.
mergify stack note records why a commit was amended. The note travels with the stack:
refs/notes/mergify/stack against the commit SHA.mergify stack push (alongside the commit refspecs, with --force-with-lease).Reason column of the markdown table, and embedded in the <!-- mergify-revision-data: {...} --> JSON marker (key reason) so it can be parsed programmatically.When to attach a note — any time you amend or rewrite a commit that already has a PR open (i.e. it has been pushed at least once). The note answers "why is this revision different?" so the reviewer doesn't have to diff old vs new SHAs to find out.
Workflow — attach the note BEFORE mergify stack push:
# Edit HEAD, then:
git commit --amend
mergify stack note -m "address review: rename foo() to bar()"
mergify stack push
# Or for a mid-stack commit (after the rebase that amended it):
mergify stack note <SHA-or-Change-Id-prefix> -m "fix lint reported in CI"
mergify stack push
A note is per-commit, not per-revision. Each amend (or other history rewrite) creates a new commit SHA, so you must run mergify stack note again for the new SHA — the previous note stays attached to the old SHA and won't carry over. Use --append only when the current target commit already has a note and you want to add another reason; use --remove to clear it. Notes on commits that haven't changed since the last push are preserved but won't add a new revision row.
BEFORE staging or committing anything, always check the current branch and assess stack state:
git branch --show-current
mergify stack list
main (or the repo's default branch): you MUST create a feature branch firstmain — mergify stack push will failgit add, not after git commitBEFORE running any operation that rewrites history or switches branches, check for uncommitted changes and stash them:
git status --short # Check for uncommitted changes
git stash -u # Stash tracked + untracked changes if any
Operations that require this check:
mergify stack edit <commit> (mid-stack fixes)mergify stack reorder / mergify stack movemergify stack fixupmergify stack squashmergify stack rewordmergify stack dropmergify stack checkoutmergify stack syncmergify stack new (switches to new branch)git checkout <branch>After the operation completes, restore the stashed changes:
git stash pop
If you skip this step, uncommitted work will be silently lost or cause rebase conflicts.
When asked to start a new piece of work, create a new feature, or work on something unrelated to the current stack:
git branch --show-currentmergify stack new <branch-name>
type/short-description (e.g., feat/add-login, fix/memory-leak)mergify stack pushWhen continuing work on an existing feature branch:
git branch --show-current
main: switch to the feature branch first with git checkout <branch> or create a new stackWhen a rebase causes conflicts (during git rebase -i or mergify stack push):
git addgit rebase --continueTo abort instead: git rebase --abort
After resolving, run mergify stack push to sync the updated stack.
npx claudepluginhub mergifyio/mergify-cli --plugin mergifyBuilds, publishes, synchronizes, validates, merges, and cleans up stacked pull requests without corrupting branch topology.
Provides Git-branchless stacked diffs workflow patterns, command references for detached HEAD, smartlog, committing, editing, restacking, syncing, and PR submission.