gitbutler-virtual-branches

# 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 ```bash # 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 ```bash # 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 ```bash # 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: ```bash # 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: ```bash 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/SKILL.md) — Multi-agent coordination - [gitbutler-stacks](../stacks/SKILL.md) — Stacked branches - [gitbutler-complete-branch](../complete-branch/SKILL.md) — Merging to main ### External - [GitButler Docs](https://docs.gitbutler.com/) — Official documentation - [GitButler AI Integration](https://docs.gitbutler.com/features/ai-integration/) — Hooks and MCP </references>