Use GitButler CLI for efficient branching, committing, and diffing.
Install
mkdir -p .claude/skills/but && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/7231" && unzip -o skill.zip -d .claude/skills/but && rm skill.zipInstalls to .claude/skills/but
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Commit, push, branch, and manage version control with GitButler. Use for commits, selective dirty-file or hunk commits, branches, diffs, PRs, history edits, squashes, amends, undo, merge, apply, and unapply. For selected dirty files or hunks, inspect 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. Replaces git write commands.Key capabilities
- →Stage specific file hunks for commits
- →Manage multiple branches in a workspace
- →Amend or squash existing commit history
- →Undo recent git operations
- →Create and push branches with PRs
How it works
The tool replaces standard Git write commands with a specialized CLI that manages commit order, branch placement, and history edits through stable change IDs.
Inputs & outputs
When to use but
- →Stage specific file hunks for commits
- →Manage multiple branches in a workspace
- →Amend or squash existing commit history
- →Undo recent git operations
About this skill
GitButler CLI Skill
Use GitButler CLI (but) as the default version-control interface.
Start Here
Choose the narrowest first command by task; avoid ritual status checks:
# Selected dirty files/hunks:
but diff
# Commit order, branch/stack placement, conflict overview:
but status
# File IDs, per-commit files, amend details:
but status -fv
# What one applied branch or commit changed, for review:
but diff <branch-or-commit>
# 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 details needed for the task.
For "commit just/only/specific changes on a new branch", use the fast path:
but diff
but commit -b <branch> -m "<msg>" <id> <id>
but commit -b <branch> ... creates the branch when it does not exist and prints the created commit. Do not run a separate but branch new, status command, or verification diff unless the task needs workspace information that the result does not provide.
In a linked worktree, such as .claude/worktrees/*, omit -b so the commit goes on the branch the worktree has checked out. Use that branch as the new branch; do not stack another one on it. A worktree with a detached HEAD has no branch yet. There, but commit -b <new-name> -m "<msg>" creates the branch at HEAD, checks it out in that worktree, and commits to it.
IDs
The first token on each but diff / but status line is that line's ID. When a command needs an ID, copy it exactly from the current output; never hardcode or invent one. ID lifetimes differ by entity:
- Changes and sources are positional, space-separated IDs (
but commit -b feat -m "msg" uvw:2e4 uvw:e2c). An uncommitted hunk ID is written<file-id>:<hunk-id>(e.g.uvw:2e4, copied from barebut diff) — the part after the colon is the hunk's ID, not a line range (uvw:16-40is invalid). Do not invent flags like--changes/--hunk/--ids, pass a line range, or comma-separate IDs —uvw,qyois parsed as one ID and fails. but diffis the same for files and hunks, committed or not:but diff <id> <id>shows each in turn. Barebut diffshows all uncommitted files. A commit or branch must be its only target, because it doesn't compare two of them;git diff <a> <b>does.--statlists changed files and line counts instead of patches.- A committed file is
<commit-id>:<file-id>(e.g.mzm:uvw, shown under each commit). A committed hunk is<commit-id>:<file-id>:<hunk-id>and is shown bybut diff <commit-id>.@means the uncommitted area. - 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, and#N-suffixed refs disambiguate duplicates — both go stale after history edits, and a stale sha can silently resolve to the wrong commit. The(sha …)on verbose commit lines is informational — do not pass it to commands. - Branch short IDs are snapshot-local selectors. Use full branch names for branch-targeting mutations; short IDs are safe only for immediate read-only inspection.
- File/hunk IDs copied from one diff read generally remain usable across chained commits. If one stops resolving, re-read
but diffand retry.
Chaining: mutation output is concise by default, so you may chain mutations with && off one inspection read. Do not chain branch short IDs through mutations; use full branch names. Add --status-after only when the next step needs workspace IDs or details that the mutation result does not provide. Chained but commit calls stack in the order written — the first is oldest, each later one goes on top. History edits may run in sequence when every commit ref involved is a change-ID ref; run them one at a time with --status-after when a ref is sha-based or #N-suffixed, or when the next command needs freshly issued IDs. Chaining but uncommit <id> && but diff is safe because bare diff needs no ID from the uncommit output. Never pipe a mutation through tail or head: the pipeline then exits with their status, so the next && runs even when the mutation failed.
Non-Negotiable Rules
- Use
butfor all write operations. Never rungit add,git commit,git push,git fetch,git pull,git checkout,git merge,git rebase,git stash, orgit cherry-pick;but pull --checkfetches. The only exceptions are selecting a side of a conflicted submodule in resolution mode (see Resolve conflicted commits) and creating a missing target branch (see Notes). If the user says agitwrite command, translate it tobutand run that. - Mutation commands print their result without appending workspace status. Add
--status-afteronly when the next step needs resulting workspace IDs or details; otherwise trust the mutation result and do not run a verification status/diff. - Branches marked
(merged upstream)have landed; start new work on another branch. That marker alone does not meanbut pullremoves them: runbut pull --checkfirst.but pullremoves only branches listed[integrated]("has been integrated upstream and removed locally", or "has been merged into <target> and removed" when the target has no upstream) and rebases the rest, which stay applied. To clear a landed branch that stays applied, usebut unapply <branch>(acts on its whole stack) rather thanbut discard.pushand mutations (commit,amend,squash,uncommit,reword,move) refuse landed branches and commits,absorbskips them with a notice, andcommitskips them when picking a default target. - Keep going between routine
butcommands. Put any status note in the same message as the next command, and don't end a turn on a summary that announces the nextbutstep without running it. Finish with a concise summary. - Prefer this skill and
but skill referenceover exploratory help calls. Use<command> --helpwhen required syntax is missing or a command fails; use top-level help only when you genuinely need to discover an undocumented command. - Other agents may share this checkout, so
@can hold their edits. Commit, amend, and discard only the IDs or paths you changed. Barebut commit,but absorb,but discard @, andgit stashtake their work too, and a refusal naming files you didn't edit means you selected theirs.
Command Patterns
-
Initialize a Git repository:
but init(current directory) orbut -C <path> init. Non-interactive; creates no commits, remotes, or GitButler workspace. Existing repositories are left unchanged. In a repository with no commits, make the first commit with a barebut commit -m "<msg>";-bis refused there. -
Commit:
but commit -b <branch> -m "<msg>" <id> <id>—-b <branch>creates the branch if it does not exist -
Commit everything uncommitted:
but commit -b <branch> -m "<msg>"(omit the IDs) -
Several commits from one diff: chain
but commitcalls with&&(commits stack oldest-first) -
Never pass
-stocommit,move, orpick: it is--switch, not git's--signoff, and it unapplies every other stack. -
The branch is never positional (
but commit <branch>fails; use-b), andbut amendneeds-twhen several branches are applied. -
Commit at a specific history position:
--above <commit-or-branch>or--below <commit-or-branch>(mutually exclusive). With a branch target, add-b <new-name>to name the new branch; otherwise its name is generated. The name must not already exist. Do not combine-b(even without a name) with commit/worktree targets. -
Targeting is required when more than one stack is applied; without it
but commitfails with "Unclear where to commit. Found more than one stack". Several branches stacked together count as one stack — an untargeted commit then silently lands on the stack's top branch, so pass-bwhenever the branch matters. -
Always pass
-m "<msg>"(or-F -with a heredoc,-F <file>with a file outside the repository, or--no-message) tobut commit, and tobut squashwhenever its sources are commits or branches unless the target is@(squash also takes-uto keep the target's message) — those compose a new message; without a flag an agent run keeps whatever the command composed (empty forbut commit, the joined source messages forbut squash) and a terminal opens an editor. Squash sources that are uncommitted or committed changes reuse the target's message and need no flag; squashing into@rejects message flags outright. -
Amend:
but amend -t <commit-or-branch> <file-or-hunk-id> <file-or-hunk-id>— a branch target resolves to its newest commit; a branch with no commits takesbut commitinstead. Without-tthe changes go to the newest commit of the branch checked out where they are, also in a linked worktree; withgitbutler/workspacechecked out that takes exactly one applied branch -
Uncommit:
but uncommit <commit-id>(whole commit),but uncommit <branch>(all commits and remove branch),but uncommit <commit-id>:<file-id>(committed file), orbut uncommit <commit-id>:<file-id>:<hunk-id>(committed hunk); committed files and hunks may be mixed, but all must come from one commit -
Copy commits (sources stay unchanged):
but pick <sha> [<sha>...] -b <new-branch>puts the copies on a new independent branch from the target,-b <existing-branch>on that applied branch's tip, and--above <branch> -b <new-name>(or--below) on a new branch stacked there. Pick applies sources in the order given, so pass them oldest first. For a branch that is not applied, list SHAs withgit log --reverse <target>..<branch>and inspect them withgit showorbut show <sha>;but diffand the IDs thatbut branch showprints for it do not work. -
Move committed changes into an existing commit or
@:but squash <commit-id>:<file-id> -t <commit-id-or-@>for a committed file; `but squa
Content truncated.
When not to use it
- →Linked worktrees
- →Conflicted commits when using amend
Limitations
- →Linked worktrees are unsupported
- →Conflicted commits do not support amend
How it compares
It provides a higher-level interface that manages staging and history mutations as atomic operations rather than requiring manual Git index manipulation.
Compared to similar skills
but side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| but (this skill) | 1 | 4mo | Review | Intermediate |
| resolve-conflicts | 81 | 12mo | Review | Intermediate |
| openspec-onboard | 10 | 9mo | Review | Beginner |
| codex-cli-bridge | 9 | 1y | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
resolve-conflicts
antinomyhq
Use this skill immediately when the user mentions merge conflicts that need to be resolved. Do not attempt to resolve conflicts directly - invoke this skill first. This skill specializes in providing a structured framework for merging imports, tests, lock files (regeneration), configuration files, and handling deleted-but-modified files with backup and analysis.
openspec-onboard
studyzy
Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.
codex-cli-bridge
alirezarezvani
Bridge between Claude Code and OpenAI Codex CLI - generates AGENTS.md from CLAUDE.md, provides Codex CLI execution helpers, and enables seamless interoperability between both tools
skill-sync
KyleKing
Syncs Claude Skills with other AI coding tools like Cursor, Copilot, and Codeium by creating cross-references and shared knowledge bases. Invoke when user wants to leverage skills across multiple tools or create unified AI context.
github-workflow-automation
ruvnet
Advanced GitHub Actions workflow automation with AI swarm coordination, intelligent CI/CD pipelines, and comprehensive repository management
git-advanced-workflows
wshobson
Master advanced Git workflows including rebasing, cherry-picking, bisect, worktrees, and reflog to maintain clean history and recover from any situation. Use when managing complex Git histories, collaborating on feature branches, or troubleshooting repository issues.