Gitbutler CLI

GitButler CLI Skill

CRITICAL: Default to --json

Always pass --json (or -j) to but commands unless a human is reading the output directly. The default human tree output uses unicode box-drawing characters (┊╭├┄┴) that break common grep/sed patterns, and tail -N on a long status hides entire stacks — leading to wrong conclusions about workspace state. Pipe --json through jq instead.

but status --json | jq '.unassigned[].path'
but status --json | jq '.stacks[].branches[].name'
but show <id> --json | jq '.commits[]'
but oplog list --json

Reserve plain output for the user-facing summary at the end of a turn.

CRITICAL: but is NOT git

but has its own flags and syntax. Git flags DO NOT work with but.

Common mistakes to NEVER make:

• but show <commit> --stat - WRONG (--stat is a git flag, not a but flag)
• but show <commit> --patch - WRONG (--patch is a git flag)
• but show <commit> --oneline - WRONG (--oneline is a git flag)
• but diff --cached - WRONG (--cached is a git flag)
• but diff --stat - WRONG (--stat is a git flag)
• but branch -a - WRONG (-a is a git flag)

Rule: Only use flags that appear in the help output below. When unsure, run but <cmd> --help first.

When to Use This Skill

Use this skill when on gitbutler/workspace branch - use but instead of git for:

• Committing changes (but commit not git commit)
• Pushing changes (but push not git push)
• Staging files to a branch (but stage)
• Viewing commit/branch details (but show)
• Viewing diffs (but diff)

Do NOT use for repositories NOT on gitbutler/workspace branch.

Note: Read-only git operations like git log, git show still work alongside but.

Live Command Reference

The following is live help output from the installed but CLI. Use ONLY these flags.

but top-level help

!but --help 2>&1

but status help

!but status --help 2>&1

but show help

!but show --help 2>&1

but diff help

!but diff --help 2>&1

but commit help

!but commit --help 2>&1

but branch help

!but branch --help 2>&1

but push help

!but push --help 2>&1

but pr help

!but pr --help 2>&1

Core Concepts

Virtual Branches

Multiple branches active simultaneously. Changes belong to different virtual branches without switching contexts.

Stacks

A series of commits on a virtual branch. Squash, amend, move, and reorder easily.

The but Command

All GitButler operations use but. It is simpler and safer than complex Git commands, but has different flags.

Best Practices

1. but status -v to see workspace state
2. but undo to revert any mistake
3. but <cmd> --help when unsure about flags
4. Never guess flags from git knowledge - always verify with --help
5. Default to --json (see the CRITICAL section at the top of this skill).