GitButler Virtual Branches

Virtual branches → parallel development → post-hoc organization.

<when_to_use>

• 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)

</when_to_use>

This, Not That

Key difference from Git: All branches visible at once. Organize files to branches after editing. No checkout.

Core Concepts

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

1. Create: but branch new <name>
2. Edit: Make changes in working directory
3. Check: but status to see file IDs
4. Assign: but rub <file-id> <branch-name>
5. Commit: but commit <branch> -m "message"
6. Repeat: Continue with other features in parallel

The Power of but rub

Swiss Army knife — combines entities to perform operations:

Essential Commands

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):

1. Rebase continues even when some commits conflict
2. Conflicted commits marked in UI/status
3. Use but resolve to enter resolution mode per commit
4. 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 but for all work within virtual branches
• Use git only for integrating completed work into main
• Return to gitbutler/workspace after 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 status before using but rub

NEVER:

• 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
  

Troubleshooting

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, troubleshooting
• references/examples.md — Real-world workflow patterns with commands
• references/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