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 PR submission automation required end-to-end (use Graphite instead)

</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 init

# 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

Global flags come first: but --json status ✓ | 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. •Resolve conflicts per commit, then continue
4. •Partial resolution can be saved for later

# Update base (may cause conflicts)
but base update

# If conflicts appear, resolve them in affected files
# Use `but status` to see which commits have conflicts
# After resolving, GitButler auto-detects resolution

For detailed conflict resolution workflows, see references/reference.md#troubleshooting-guide.

Auto-Assignment with Marks

Set up workspace rules to auto-assign files to branches:

# Auto-assign all src/auth/* changes to auth-feature branch
but mark "src/auth/**/*.ts" auth-feature

# Auto-assign test files
but mark "**/*.test.ts" test-infrastructure

# Remove all rules
but unmark

Useful for multi-agent workflows where files follow predictable patterns.

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

  bash

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