carapace-sh GitButler CLI (but) In-Depth Reference
Reference for the GitButler CLI — a stacked-branch Git workflow tool that enables virtual branches, parallel branch work, commit editing, and AI agent integration from the terminal.
Data Flow
Working directory changes
→ but stage (assign changes to branches)
→ but commit (create commits on virtual branches)
→ but push (push branches to remote)
→ but pr (create/update pull requests on forge)
but status
→ but diff (inspect changes)
→ but show (inspect commits/branches)
→ but rub (edit: amend, squash, move, split)
→ but oplog (review history) / but undo (revert)
Sub-Resources
Load the reference that matches your task. When in doubt, load multiple references.
| Keywords | Reference |
|---|---|
| workspace, integration branch, virtual branches, parallel branches, gitbutler/workspace, setup, teardown, merge base, upstream, target branch | references/workspace.md |
| branch, branch new, branch delete, branch list, branch show, branch update, apply, unapply, clean, anchor, stacked branch, stack, strategy | references/branches.md |
| commit, commit empty, stage, amend, squash, reword, move, pick, absorb, discard, commit message, --ai, --changes, --only, hunk, --after, --before | references/commits.md |
| rub, rubbing, amend via rub, squash via rub, move via rub, split commits, uncommit via rub, stage via rub, assign changes, zz, unassigned | references/rubbing.md |
| status, diff, show, CLI ID, cliId, hunk ID, change ID, change type, but status --json, but diff --json, format, --format, files, verbose, upstream | references/inspection.md |
| push, pull, pull --check, pr, pr new, pr setDraft, pr setReady, pr autoMerge, pr template, forge, GitHub, authentication, auth, list-users, remote, review | references/forge.md |
| oplog, oplog list, oplog restore, oplog snapshot, undo, redo, snapshot, operation history, CreateCommit, AmendCommit, SquashCommit, RestoreFromSnapshot | references/oplog.md |
| resolve, resolve finish, resolve cancel, resolve status, conflict, conflict resolution, zdiff3, conflicted commit, rebase conflict | references/conflicts.md |
| config, config user, config target, config forge, config metrics, config ui, config ai, anthropic, openai, ollama, lmstudio, openrouter, alias, alias add, alias list, alias remove, editor, name, email | references/config.md |
| tui, interactive TUI, keybindings, navigation, diff TUI, stage hunk picker, reorder stacks, apply from TUI, move commits, copy, scroll | references/tui.md |
| agent, agent setup, skill, skill install, skill check, AI, --ai, coding agent, steering instructions, parallel agents, tuning agent behavior, checkpoint commits, stacked PRs, ship it | references/ai-agents.md |
| root command, global flags, --current-dir, --format, --version, completions, update, update check, update install, update suppress, command groups | references/misc.md |
Quick Guide
- What is the GitButler workspace model? → references/workspace.md
- How do virtual branches work? → references/workspace.md
- How do I create a stacked branch? → references/branches.md
- How do I commit changes to a specific branch? → references/commits.md
- What is
but ruband how does it work? → references/rubbing.md - How do CLI IDs work? → references/inspection.md
- How do I push and create PRs? → references/forge.md
- How do I undo an operation? → references/oplog.md
- How do I resolve conflicts? → references/conflicts.md
- How do I configure GitButler? → references/config.md
- What can the TUI do? → references/tui.md
- How do I set up GitButler for AI coding agents? → references/ai-agents.md
- What are the global flags? → references/misc.md
Cross-Project References
- For Git internals (branches, refs, remotes, changes, tags), use the git skill.
- For carapace completion integration (specs, actions, macros), use the carapace skill.