Commit, push, branch, and manage version control. Use for git commit, git status, git push, git diff, creating branches, staging files, editing history, pull requests, or any git/version control operation. Replaces git write commands with 'but' - always use this instead of raw git.
npxskills add gitbutlerapp/gitbutler--skill butLoading…
Use GitButler CLI (but) as the default version-control interface.
Choose the first command by task:
# Selected dirty files/hunks:
but diff
# Commit order, branch layout, conflict overview:
but status
# Per-commit file details, amend/split details:
but status -fv
For "commit just/only/specific changes on a new branch", use the fast path:
but diff
but commit <branch> -c -m "<msg>" --changes <id>,<id>
but commit <branch> -c ... --changes ... creates the branch and prints the resulting workspace state. Do not run a separate but branch new, staging command, status command, or verification diff unless the returned output lacks information you need.
--changes (or -p) takes comma-separated file or hunk IDs from but diff / but status -fv. A hunk ID is written <file-id>:<hunk-id> (e.g. qs:5, copied from but diff) — the part after the colon is the hunk's ID, not a line range (qs:16-40 is invalid). Do not invent flags like --hunk / --hunks / --ids, pass a line range, or pass the IDs as positional arguments.
The first token on each status line is that line's ID — pass it to commands as-is. Commit IDs are stable change IDs that survive history edits (amend, squash, move, uncommit, reword); commits without a change ID (e.g. upstream-only) lead with a sha prefix instead, which goes stale after history edits. The (sha …) shown on verbose commit lines is informational — do not pass it to commands. CLI IDs may be a single character when unambiguous; copy them exactly from command output. Longer unambiguous prefixes also work.
but for all write operations. Never run git add, git commit, git push, git checkout, git merge, git rebase, git stash, or git cherry-pick. If the user says a git write command, translate it to but and run that. Exceptions: git add -- <path> to mark a conflicted uncommitted file resolved (see "Conflicts in uncommitted files"), and a worktree-local Git commit when reports that linked worktrees are unsupported. Never run from a linked worktree.Start with the narrowest inspection that answers the task. Avoid ritual status checks.
# Selected dirty files/hunks:
but diff
# Commit order, branch/stack placement, conflict overview:
but status
# File/hunk IDs, per-commit files, amend/split details:
but status -fv
# Details for one known branch or commit:
but show <id>
Do not run plain but status and then but status -fv unless the compact output lacks file/hunk details needed for the task.
Perform mutations with IDs from diff, status, status -fv, or show:
but <mutation> ...
but commit <branch> -m "<msg>" --changes <id>,<id>but commit calls - but commit <branch> -m "<msg>" --changes <id>,<id> && but commit <branch> -m "<msg>" --changes <id>,<id> (commits stack oldest-first in the order you write them — first call is oldest; file/hunk IDs from the initial output generally remain usable; refresh if an ID stops resolving)but commit -a is accepted as a no-op compatibility flag; GitButler already includes uncommitted changes by default.but commit <branch> -c -m "<msg>" --changes <id>but commit <branch> -m "<msg>" --changes <id>,<id> --before <commit-or-branch-id> or --after <commit-or-branch-id>but amend <commit-id> --changes <file-or-hunk-id>,<file-or-hunk-id>For "get latest from main", "update/sync this workspace", or "pull main":
but status -fvbut pull --checkbut pullbut status -fvbut pull updates applied branches onto the latest target branch (usually
main). Do not use raw git pull or git rebase.
but diff — use this first for selective dirty commits. It shows file and hunk IDs for uncommitted changes.<file-id>:<hunk-id> from but diff (e.g. qs:5), not the whole file ID and not a line range. Do not run plain but status first.but commit <branch> -c -m "<msg>" --changes <id1>,<id2>.
For an existing branch, omit -c: but commit <branch> -m "<msg>" --changes <id1>,<id2>.
Omit IDs you don't want committed.
Creating a new branch with -c does not require a prior but branch or .Edge case: if wanted and unwanted edits are in the same diff hunk, GitButler cannot split that hunk by ID. Only when the task requires keeping part of that hunk uncommitted, temporarily edit the working tree to isolate the wanted lines, commit with --changes, then restore the leftover lines so they remain uncommitted.
but status -fv (or but show <branch-id>)but amend <commit-id> --changes <file-or-hunk-id>,<file-or-hunk-id>; use one command for multiple files/hunks that belong in the same commit. To amend into several different commits, run the amends in sequence — change-ID refs from one status read survive each amend, but take fresh refs from the returned status whenever a ref is sha-based or #N-suffixed.Use this when an existing commit should be replaced by selected smaller commits.
but status -fv when you need the source commit, branch name, or placement anchor.but uncommit <source-commit-id> --diff to expose that commit's changes as uncommitted changes and print committable file/hunk IDs.but uncommit --diff, not from the old committed diff.but commit calls (file/hunk IDs from the diff stay usable across commits):
but commit <branch> -m "<message 1>" --changes <id>,<id> && but commit <branch> -m "<message 2>" --changes <id>,<id>
Each new commit goes to the TOP of the stack. So if you split a commit that had other commits above it, the replacements are now sitting above those preserved commits.--before <top>/--after <top>: a sha-based or #N-suffixed anchor goes stale as and each insert rewrite history (and just puts commits on top of the branch). Instead, take the preserved commit's ref from the workspace state the last printed, then to lift it back to the top/newest (for several preserved commits, list every one, oldest first: ).but move supports both commit reordering and branch stack operations. Use commit IDs when reordering commits.
but status displays commits newest/top first, while task specs often list history oldest to newest. Use but status -fv only if you also need file-level details.
but statusbut move <source-commit-id> <target-commit-id> places source immediately before target in oldest-to-newest history. In but status, source appears directly below target.but move <source-commit-id> <target-commit-id> --after places source immediately after target in oldest-to-newest history. In but status, source appears directly above target.but move <source-commit-id> <branch-name-or-id> moves source to branch top/newest.but move <source-commit-id>,<source-commit-id> <target-commit-id> moves multiple commit sources together. Multi-source moves accept comma-separated commit IDs only, not branch names.For explicit final-order tasks, run but status once to get commit IDs. If the task names an adjacent commit block, do not sort the whole branch or move block members one by one: preserve the block's internal oldest-to-newest order, find the commit that should immediately follow the block in the requested oldest-to-newest order, then run one block move: but move <oldest-block-id>,<newest-block-id> <following-commit-id>. After a successful block move, stop if the returned status shows the requested order; do not move the anchor or any member of that block again.
For other explicit reorders, translate the requested order into the newest-to-oldest order shown by but status, then make the smallest set of moves. Prefer the default before/below form because it matches the status display: but move <source> <newer-neighbor> places source directly below its newer neighbor. Use a branch target only when a commit must become top/newest, and use --after only when it clearly avoids extra moves.
Use this when multiple existing commits should become one commit.
but status to get commit IDs and current order. Use but status -fv only if you also need per-commit file details.but squash <source-commit-id> [<source-commit-id>...] <target-commit-id> -m "<new message>".#N-suffixed.--help, status, or status -fv only to reconfirm.To make one existing branch depend on (stack on top of) another, use top-level move:
but move feature/frontend feature/backend
This moves the frontend branch on top of the backend branch in one step.
DO NOT use uncommit + branch delete + branch new -a to stack existing branches. That approach fails because git branch names persist even after but branch delete. Always use but move <branch> <target-branch>.
To unstack (make a stacked branch independent again):
but move feature/logging zz
Note: branch stack/tear-off operations use branch names (like feature/frontend) or branch CLI IDs, while commit reordering uses commit IDs (like nn). Do NOT use but undo to unstack — it may revert more than intended and lose commits.
but pr new <branch-id> pushes the branch and creates a pull request in one step. Do not run but push first. Agents must provide -F pr_message.txt, -t, or -m with real newline characters (zsh/bash: -m $'Title\n\nBody') so the command does not open an editor. If forge auth is missing, run but config forge auth.
For independent, unstacked branches, another forge tool may be okay if the user asked for it or but pr is unavailable. Still prefer but pr new when you are already working from GitButler branch IDs.
For stacked branches, but pr is mandatory. Create and manage stacked PRs with GitButler so PR bases match the stack and GitButler can maintain the stack metadata in PR description footers. Do not create stacked PRs with gh pr create or other forge tools.
To publish a whole stack, create the PR from the top branch you want published:
but pr new <top-branch-id> -t
That creates or updates reviews for that branch and its dependencies in stack order. Use but pr auto-merge <selector>, but pr set-draft <selector>, and but pr set-ready <selector> for follow-up PR management; selectors can be branch names, branch IDs, stack IDs, or numeric review IDs.
A dependency lock occurs when a file was originally committed on branch A, but you're trying to commit changes to it on branch B. Symptoms:
but commit succeeds but the file still appears in uncommittedChanges in the returned statusRecovery: Stack your branch on the dependency branch, then commit:
but status -fv — identify which branch originally owns the file (check commit history).but move <your-branch-name> <dependency-branch-name> — stack your branch on the dependency. Uses full branch names, not CLI IDs.but status -fv — the file should now be committable. Commit it.but commit <branch> -m "<msg>" --changes <id>If but move <branch> <target-branch> fails: Do NOT try uncommit, squash, or undo to work around it — these will leave the workspace in a worse state. Instead, re-run but status -fv to confirm both branches still exist and are applied, then retry with exact branch names from the status output.
NEVER use git add, git commit, git checkout --theirs, git checkout --ours, or any git write commands during resolution. Only use but resolve commands and edit files directly with the Edit tool.
If but move causes conflicts (conflicted commits in status):
but status -fv — find commits marked as conflicted.but resolve <commit-id> — enter resolution mode. This puts conflict markers in the files.<<<<<<< / ======= / >>>>>>> markers.but resolve finish — finalize. Do NOT run this without editing the files first.Common mistakes: Do NOT use but amend on conflicted commits (it won't work). Do NOT skip step 4 — you must actually edit the files to remove conflict markers before finishing.
but status lists uncommitted files with unresolved merge conflicts marked
{conflicted}; they are excluded from committable changes. These conflicts are
outside but resolve mode. Choose the desired contents or delete the file, then
run git add -- <path> to mark it resolved. This is the one case where using
git add is permitted.
| git | but |
|---|---|
git status | but status for branch/stack/commit overview; but status -fv for file/hunk details; but diff for selected dirty changes |
git add + git commit | but commit ... --changes ... |
git checkout -b + commit | but commit <branch> -c -m ... --changes ... |
but status for commit order, branch/stack placement, and conflict overview. Escalate to but status -fv only when file/hunk IDs or per-commit file details are needed.git log, git blame, git show --stat) is allowed.but status or but status -fv only if that output lacks the ID you need or files changed since.--help probes; use this skill and references/reference.md first. Only use --help after a command fails or required syntax is missing from the installed references.but commitbut setupbut commit mutations with && to make several commits from one diff; they stack in the order you write them, so the first but commit is the oldest of the new commits and each later one goes on top (newest). File/hunk IDs copied from the original output generally remain usable across commits, and branch IDs are stable. History edits (amend, squash, move, uncommit, reword) may also run in sequence off one status read when every commit ref involved is a change-ID ref — those stay valid across the edits. Run them one at a time when a ref is sha-based or #N-suffixed (those go stale after a history edit, and a stale sha can silently resolve to the wrong commit), or when the next command needs IDs the previous one prints (e.g. recommitting after but uncommit --diff). Take follow-up refs from the returned workspace state. If a chained command cannot resolve an ID, re-read with but status/but diff and retry.but diff / but status / but status -fv / but show; never hardcode IDs.but status or but status -fv as routine preflight for selected dirty-file or hunk commits. Start with but diff; use compact but status for commit order, branch/stack placement, or conflict overview. Use but status -fv when file/hunk IDs or per-commit file details matter.but commit <branch> -c -m "<msg>" --changes <ids>.(merged upstream); run but pull to remove it, or create/use another branch for new work.but commands and give a concise final summary.but uncommit <commit-id> --diffbut commit empty [-m "<msg>"] [<target>]but squash <source-commit-id> [<source-commit-id>...] <target-commit-id> [-m "<msg>"]but move <source-commit-id> <target-commit-id> (commit IDs, not branch names)but move <source-commit-id>,<source-commit-id> <target-commit-id> (comma-separated commit IDs)but move <commit-id> <branch-name-or-id> (puts that commit at the top/newest position of the branch)but move <commit-id>,<commit-id> <branch-name-or-id> (commit IDs only; not branches)but move <branch-name-or-id> <target-branch-name-or-id> (branch names or branch CLI IDs)but move <branch-name-or-id> zz (zz = uncommitted; branch name or branch CLI ID)but push <branch-name> — always specify the branch; bare but push pushes ALL branches when run non-interactivelybut pull --check then but pullbut pr new <branch-id> [-m "Title..."] [-F pr_message.txt] [-t] [--draft] — auto-pushes before creating the PR; do not run but push firstbut pr auto-merge <selector>, but pr set-draft <selector>, but pr set-ready <selector>but status -fvbut uncommit--before <branch>but commitbut move <preserved-commit-id> <branch>but move <id1>,<id2>,<id3> <branch>git push | but push <branch-name> |
git rebase -i | but move, but squash, but reword |
git rebase --onto | but move <branch> <new-base> |
git cherry-pick | but pick |
gh pr create | but pr new <branch-id> (pushes the branch, then creates the PR; no separate but push) |
but prints an AGENT ACTION REQUIRED skill warning, run the suggested command once, then reload/use the GitButler skill. If it repeats, report it instead of retrying.references/reference.mdreferences/concepts.mdreferences/examples.md
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).