Skip to content

carapace-sh/carapace-bin / skills/but

Use when working with the GitButler CLI (`but`) — virtual branches, stacked branches, workspace model, commit editing (rub, amend, squash, reword), CLI IDs, forge integration, PRs, operations log, conflict resolution, TUI, AI agent setup, skills, aliases, configuration. Triggers on: "but", "gitbutler", "but rub", "but commit", "but status", "but branch", "but apply", "but unapply", "but push", "but pull", "but pr", "but oplog", "but undo", "but redo", "but resolve", "but stage", "but squash", "but amend", "but reword", "but config", "but alias", "but setup", "but teardown", "but tui", "but diff", "but show", "but agent", "but skill", "but clean", "but move", "but pick", "but absorb", "but update", "but completions", "virtual branch", "stacked branch", "integration branch", "gitbutler workspace", "but oplog restore", "but oplog snapshot", "CLI ID", "hunk ID".

FileKindSize
SKILL.mdskill md5.5 KB
references/ai-agents.mdmarkdown6.2 KB
references/branches.mdmarkdown5.4 KB
references/commits.mdmarkdown6.9 KB
references/config.mdmarkdown4.5 KB
references/conflicts.mdmarkdown2.1 KB
references/forge.mdmarkdown3.6 KB
references/inspection.mdmarkdown4.5 KB
references/misc.mdmarkdown3.4 KB
references/oplog.mdmarkdown3.3 KB
references/rubbing.mdmarkdown3.0 KB
references/tui.mdmarkdown2.1 KB
references/workspace.mdmarkdown4.6 KB

references/workspace.md

View on GitHub
# Workspace Model

The GitButler workspace model — how virtual branches, the integration branch, and the merge base enable parallel branch work in a single working directory.

## Overview

GitButler replaces Git's single-HEAD checkout model with a **workspace** where multiple branches are applied simultaneously. The `but` CLI operates on this workspace, managing branches, commits, and changes without requiring `git checkout` or worktrees.

> **Source of truth**: <https://docs.gitbutler.com/overview> and <https://docs.gitbutler.com/features/branch-management/integration-branch>

## The Integration Branch

GitButler maintains a special internal branch: `gitbutler/workspace`. This is a **merge commit** that GitButler rebuilds as you modify branches. It exists because stock Git has no concept of having several branches applied at once.

### How It Works

- When other tools run `git status` / `git diff` / `git log`, GitButler modifies your index to look like the **union of all committed states** of all applied parallel branches
- This makes normal Git commands behave mostly as expected
- The merge base (target branch, e.g. `origin/main`) is the common ancestor all virtual branches are based on

### Commit Protection

Git pre-commit and post-checkout hooks prevent committing directly to `gitbutler/workspace` — they tell you to use `but commit` instead. This prevents corrupting the workspace state.

### Setup and Teardown

```bash
but setup     # Initialize GitButler workspace in a git repository
but teardown  # Exit GitButler mode, return to vanilla Git workflow
```

`but setup` makes the necessary changes for GitButler to manage your data. `but teardown` undoes those changes and checks out a normal branch. Use `--checkout-to` to specify which branch to land on:

```bash
but teardown --checkout-to main
```

`but setup` also supports `--init` to initialize a new git repository with an empty commit if one doesn't exist.

## Virtual Branches (Parallel Branches)

Virtual branches are GitButler's core innovation — the ability to work on **multiple branches simultaneously** in a single working directory.

### Key Concepts

- Each virtual branch is kept in a vertical lane (like a Kanban board)
- Files and changes are like cards you can drag between lanes
- You don't "switch" branches (which implies replacement) — you **apply** or **unapply** branches
- Applying adds changes to your working directory; unapplying removes only those changes
- Each branch has its own staging area
- Since all branches start from changes in one working directory, they merge cleanly

### How Commits Work

When you commit, GitButler calculates what the branch would look like if only those changes existed, and commits that file tree. Pushed commits look like single-branch changes on GitHub — the virtual branch abstraction is invisible to remotes.

### Creating Virtual Branches

```bash
but branch new <name>              # Create a parallel branch
but apply <branch>                  # Apply a branch to the workspace
but unapply <branch>                # Remove a branch from the workspace
```

For stacked branches (dependent branches), see [branches.md](branches.md).

## Merge Base and Upstream

The **merge base** is the target branch (typically `origin/main`) that all virtual branches are based on. The workspace tracks how far behind the upstream the merge base is.

```bash
but status -u              # Show upstream info
but pull                   # Fetch + rebase active branches on new upstream
but pull --check           # Preview what pull would do
```

View or change the target branch:

```bash
but config target                   # Show current target branch
but config target origin/develop    # Change target branch
```

## Unassigned Changes

Changes in the working directory that haven't been assigned to a branch are called **unassigned changes** (labeled "uncommitted" in output since 0.20.4). The special ID `zz` refers to the unassigned area.

To assign changes to a branch, use `but stage` or `but rub`:

```bash
but stage <file> <branch>     # Assign file changes to a branch
but rub <file> <branch>       # Alias for staging via rub
but rub <file> zz             # Move changes back to unassigned
```

See [rubbing.md](rubbing.md) for the full `but rub` reference.

## Status Output

`but status` shows the workspace state: applied stacks, branches, commits, and unassigned changes. See [inspection.md](inspection.md) for details.

## Related

- [branches.md](branches.md) — Branch management commands
- [commits.md](commits.md) — Commit creation and editing
- [inspection.md](inspection.md) — Status, diff, and CLI IDs
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall