Smithery is now a part of Arcade.dev! Read more in our announcement here
This skill should be used when the user asks to "create a virtual branch", "assign file to branch", "work on multiple features simultaneously", "organize commits after coding", "use but commands", or...
Virtual branches → parallel development → post-hoc organization.
NOT for: projects using Graphite (incompatible models), simple linear workflows (use plain git)
| Task | This | Not That |
|---|---|---|
| Initialize workspace | but setup |
manual setup |
| Create branch | but branch new name |
git checkout -b name |
| View changes | but status |
git status |
| Assign file to branch | but rub <file-id> <branch> |
manual staging |
| Commit to branch | but commit <branch> -m "msg" |
git commit -m "msg" |
| Move commit | but rub <sha> <branch> |
git cherry-pick |
| Squash commits | but squash <branch> |
git rebase -i |
| Undo operation | but undo |
git reset |
| Switch context | Create new branch | git checkout |
Key difference from Git: All branches visible at once. Organize files to branches after editing. No checkout.
| Concept | Description |
|---|---|
| Virtual branches | Multiple branches applied simultaneously to working directory |
| Integration branch | gitbutler/workspace tracks virtual branch state — never touch directly |
| Target branch | Base branch (e.g., origin/main) all work diverges from |
| File assignment | Assign file hunks to branches with but rub |
| Oplog | Operations log for undo/restore — your safety net |
# Initialize (one time)
but setup
# Create branch
but branch new feature-auth
# Make changes, check status for file IDs
but status
# â•â”„00 [Unassigned Changes]
# │ m6 A src/auth.ts
# Assign file to branch using ID
but rub m6 feature-auth
# Commit
but commit feature-auth -m "feat: add authentication"
but branch new <name>but status to see file IDsbut rub <file-id> <branch-name>but commit <branch> -m "message"but rubSwiss Army knife — combines entities to perform operations:
| Source | Target | Operation |
|---|---|---|
| File ID | Branch | Assign file to branch |
| File ID | Commit | Amend commit with file |
| Commit SHA | Branch | Move commit between branches |
| Commit SHA | Commit SHA | Squash (newer into older) |
| Command | Purpose |
|---|---|
but setup |
Initialize GitButler in repository |
but status |
View changes and file IDs |
but branch new <name> |
Create virtual branch |
but branch new <name> --anchor <parent> |
Create stacked branch |
but rub <source> <target> |
Assign/move/squash/amend |
but commit <branch> -m "msg" |
Commit to branch |
but commit <branch> -o -m "msg" |
Commit only assigned files |
but absorb |
Auto-amend uncommitted changes to appropriate commits |
but squash <commits> |
Squash commits (by IDs, range, or branch) |
but show <id> |
Inspect a commit or branch in detail |
but resolve <commit> |
Enter conflict resolution mode |
but push |
Push branches to remote |
but pr new |
Create/update PRs on forge |
but config forge auth |
Authenticate with GitHub (OAuth) |
but mark <branch> |
Auto-assign new changes to branch |
but unmark |
Remove all mark rules from workspace |
but oplog |
Show operation history |
but undo |
Undo last operation |
but oplog snapshot --message "msg" |
Create manual snapshot |
but pull |
Update workspace with latest base |
but gui |
Open GitButler GUI for current repo |
JSON output: Use --json or -j flag on any command: but status --json
# Create two independent features
but branch new feature-a
but branch new feature-b
# Edit files for both (same workspace!)
echo "Feature A" > feature-a.ts
echo "Feature B" > feature-b.ts
# Assign to respective branches
but rub <id-a> feature-a
but rub <id-b> feature-b
# Commit independently
but commit feature-a -m "feat: implement feature A"
but commit feature-b -m "feat: implement feature B"
# Both branches exist, zero conflicts, same directory
GitButler handles conflicts per-commit during rebase/update (unlike Git's all-or-nothing model):
but resolve to enter resolution mode per commit# Update base (may cause conflicts)
but pull
# Check which commits have conflicts
but status
# Enter resolution mode for a specific commit
but resolve <commit-id>
# Fix conflicts in your editor, then check remaining
but resolve status
# Finalize when done (or cancel to abort)
but resolve finish
For detailed conflict resolution workflows, see references/reference.md#conflict-resolution.
Set up workspace rules to auto-assign files to branches:
# Auto-assign new changes to auth-feature branch
but mark auth-feature
# Remove all rules
but unmark
Useful for multi-agent workflows where changes should route to a specific branch.
ALWAYS:
but for all work within virtual branchesgit only for integrating completed work into maingitbutler/workspace after git operations: git checkout gitbutler/workspacebut oplog snapshot --message "..."but rub <id> <branch>but status before using but rubNEVER:
Use git commit on virtual branches — breaks GitButler state
Use git add — GitButler manages index
Use git checkout on virtual branches — no checkout needed
Push gitbutler/integration to remote — it's local-only
Mix Graphite and GitButler in same repo — incompatible models
Pipe but status directly — causes panic; capture output first:
status_output=$(but status)
echo "$status_output" | head -5
| Symptom | Solution |
|---|---|
| Files not committing | Assign first: but rub <file-id> <branch> |
| Broken pipe panic | Capture output: output=$(but status) |
| Mixed git/but broke state | but pull or but setup |
| Lost work | but undo or but oplog restore <snapshot-id> |
For detailed troubleshooting (branch tracking, conflicts, filename issues), see references/reference.md#troubleshooting-guide.
Quick undo: but undo | Full restore: but oplog restore <snapshot-id> | View history: but oplog
For recovery from lost work or corrupted state, see references/reference.md#recovery-scenarios.
references/reference.md — Complete CLI reference, JSON schemas, troubleshootingreferences/examples.md — Real-world workflow patterns with commandsreferences/ai-integration.md — Hooks, MCP server, agent lifecycle