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

• Create: but branch new <name>

• Edit: Make changes in working directory

• Check: but status to 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 resolve to 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 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

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