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

| 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

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:

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

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.

<rules>

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
  

</rules>

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.

<references>

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

</references>