GitButler Virtual Branches
Virtual branches → parallel development → post-hoc organization.
- Multiple unrelated features in same workspace simultaneously
- Multi-agent concurrent development (agents in same repo)
- Exploratory coding where organization comes after writing
- Post-hoc commit reorganization needed
- Visual organization preferred (GUI + CLI)
NOT for: projects using Graphite (incompatible models), simple linear workflows (use plain git)
This, Not That
| 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.
Core Concepts
| 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 |
Quick Start
# 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"
Core Loop
- Create:
but branch new <name> - Edit: Make changes in working directory
- Check:
but statusto see file IDs - Assign:
but rub <file-id> <branch-name> - Commit:
but commit <branch> -m "message" - Repeat: Continue with other features in parallel
The Power of but rub
Swiss 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) |
Essential Commands
| 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
Parallel Development
# 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
Conflict Handling
GitButler handles conflicts per-commit during rebase/update (unlike Git's all-or-nothing model):
- Rebase continues even when some commits conflict
- Conflicted commits marked in UI/status
- Use
but resolveto enter resolution mode per commit - Partial resolution can be saved for later
# 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.
Auto-Assignment with Marks
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:
- Use
butfor all work within virtual branches - Use
gitonly for integrating completed work into main - Return to
gitbutler/workspaceafter git operations:git checkout gitbutler/workspace - Snapshot before risky operations:
but oplog snapshot --message "..." - Assign files immediately after creating:
but rub <id> <branch> - Check file IDs with
but statusbefore usingbut rub
NEVER:
Use
git commiton virtual branches — breaks GitButler stateUse
git add— GitButler manages indexUse
git checkouton virtual branches — no checkout neededPush
gitbutler/integrationto remote — it's local-onlyMix Graphite and GitButler in same repo — incompatible models
Pipe
but statusdirectly — causes panic; capture output first:status_output=$(but status) echo "$status_output" | head -5
Troubleshooting
| 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.
Recovery
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.
Reference Files
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
Related Skills
- gitbutler-multi-agent — Multi-agent coordination
- gitbutler-stacks — Stacked branches
- gitbutler-complete-branch — Merging to main
External
- GitButler Docs — Official documentation
- GitButler AI Integration — Hooks and MCP
Converted and distributed by TomeVault — claim your Tome and manage your conversions.