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.zip

Installs 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.
460 chars✓ has a “when” triggerlonger than Claude Code's old 250-char listing cap (fine on current versions)
Intermediate

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

You give it
Git repository changes
You get back
Version control state updates

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 bare but diff) — the part after the colon is the hunk's ID, not a line range (uvw:16-40 is invalid). Do not invent flags like --changes / --hunk / --ids, pass a line range, or comma-separate IDs — uvw,qyo is parsed as one ID and fails.
  • but diff is the same for files and hunks, committed or not: but diff <id> <id> shows each in turn. Bare but diff shows 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. --stat lists 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 by but 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 diff and 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

  1. Use but for all write operations. Never run git add, git commit, git push, git fetch, git pull, git checkout, git merge, git rebase, git stash, or git cherry-pick; but pull --check fetches. 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 a git write command, translate it to but and run that.
  2. Mutation commands print their result without appending workspace status. Add --status-after only when the next step needs resulting workspace IDs or details; otherwise trust the mutation result and do not run a verification status/diff.
  3. Branches marked (merged upstream) have landed; start new work on another branch. That marker alone does not mean but pull removes them: run but pull --check first. but pull removes 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, use but unapply <branch> (acts on its whole stack) rather than but discard. push and mutations (commit, amend, squash, uncommit, reword, move) refuse landed branches and commits, absorb skips them with a notice, and commit skips them when picking a default target.
  4. Keep going between routine but commands. Put any status note in the same message as the next command, and don't end a turn on a summary that announces the next but step without running it. Finish with a concise summary.
  5. Prefer this skill and but skill reference over exploratory help calls. Use <command> --help when required syntax is missing or a command fails; use top-level help only when you genuinely need to discover an undocumented command.
  6. Other agents may share this checkout, so @ can hold their edits. Commit, amend, and discard only the IDs or paths you changed. Bare but commit, but absorb, but discard @, and git stash take 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) or but -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 bare but commit -m "<msg>"; -b is 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 commit calls with && (commits stack oldest-first)

  • Never pass -s to commit, move, or pick: it is --switch, not git's --signoff, and it unapplies every other stack.

  • The branch is never positional (but commit <branch> fails; use -b), and but amend needs -t when 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 commit fails 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 -b whenever the branch matters.

  • Always pass -m "<msg>" (or -F - with a heredoc, -F <file> with a file outside the repository, or --no-message) to but commit, and to but squash whenever its sources are commits or branches unless the target is @ (squash also takes -u to keep the target's message) — those compose a new message; without a flag an agent run keeps whatever the command composed (empty for but commit, the joined source messages for but 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 takes but commit instead. Without -t the changes go to the newest commit of the branch checked out where they are, also in a linked worktree; with gitbutler/workspace checked 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), or but 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 with git log --reverse <target>..<branch> and inspect them with git show or but show <sha>; but diff and the IDs that but branch show prints 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.

SkillInstallsUpdatedSafetyDifficulty
but (this skill)14moReviewIntermediate
resolve-conflicts8112moReviewIntermediate
openspec-onboard109moReviewBeginner
codex-cli-bridge91yReviewIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

Search skills

Search the agent skills registry