carapace-sh/carapace-bin / skills/but
but
VerifiedUse 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".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.5 KB |
| references/ai-agents.md | markdown | 6.2 KB |
| references/branches.md | markdown | 5.4 KB |
| references/commits.md | markdown | 6.9 KB |
| references/config.md | markdown | 4.5 KB |
| references/conflicts.md | markdown | 2.1 KB |
| references/forge.md | markdown | 3.6 KB |
| references/inspection.md | markdown | 4.5 KB |
| references/misc.md | markdown | 3.4 KB |
| references/oplog.md | markdown | 3.3 KB |
| references/rubbing.md | markdown | 3.0 KB |
| references/tui.md | markdown | 2.1 KB |
| references/workspace.md | markdown | 4.6 KB |
references/branches.md
View on GitHub# Branch Management
Commands for managing virtual branches and stacked branches in the GitButler workspace.
> **Source of truth**: <https://docs.gitbutler.com/cli-guides/cli-tutorial/branching-and-commiting> and <https://docs.gitbutler.com/features/branch-management/virtual-branches>
## Command Groups
Branch commands are in the `branching and committing` group. The `branch` command is a parent with subcommands.
## `but branch` — Branch Subcommands
Parent command for branch management operations.
```bash
but branch <subcommand>
```
### `but branch list`
List branches in the repository. Shows applied and unapplied branches.
| Flag | Short | Description |
|------|-------|-------------|
| `--all` | `-a` | Show all branches (not just active + 20 most recent) |
| `--empty` | | Include branches with no commits (hidden by default) |
| `--local` | `-l` | Show only local branches |
| `--no-ahead` | | Don't calculate commits ahead of base (faster) |
| `--no-check` | | Don't check if each branch merges cleanly into upstream |
| `--remote` | `-r` | Show only remote branches |
| `--review` | | Fetch and display review information (PRs, MRs, etc.) |
### `but branch new`
Create a new branch in the workspace.
```bash
but branch new <name> # Create a parallel branch
but branch new --anchor <base> <name> # Create a stacked branch
```
| Flag | Short | Description |
|------|-------|-------------|
| `--anchor` | `-a` | Anchor point — commit ID or branch name to create from |
The `--anchor` flag creates **stacked branches** — dependent branches where each is based on the previous one. See [Stacked Branches](#stacked-branches) below.
### `but branch show`
Show commits ahead of base for a specific branch.
```bash
but branch show <branch>
```
| Flag | Short | Description |
|------|-------|-------------|
| `--ai` | | Generate AI summary of the branch changes |
| `--check` | | Check if branch merges cleanly into upstream, identify conflicting commits |
| `--files` | `-f` | Show files modified in each commit with line counts |
| `--review` | `-r` | Fetch and display review information |
### `but branch update`
Update a local branch with the content of its remote counterpart.
```bash
but branch update <branch>
```
| Flag | Short | Description |
|------|-------|-------------|
| `--dry-run` | | Preview resulting branch state without persisting |
| `--interactive` | `-i` | Open the generated integration script in an editor |
| `--strategy` | `-s` | Strategy for integration (see below) |
| `--verbose` | `-v` | Show additional dry-run details like current divergence |
#### Update Strategies
| Strategy | Description |
|----------|-------------|
| `pull-rebase` | Rebuilds the branch picking first remote commits, then local commits (default) |
| `smart-squash` | Folds matching remote work into related local commits via Change IDs, falls back to pull-rebase |
| `merge` | Keeps local history and merges the remote tip into it |
| `pick-remote` | Rebuilds the branch picking only the commits on the remote |
### `but branch delete`
Delete a branch from the workspace.
```bash
but branch delete <branch>
```
## `but apply` — Apply a Branch
Apply a branch to the workspace. Adds the branch's changes to your working directory.
```bash
but apply <branch>
```
Accepts local or remote branch names. The branch becomes "applied" and its changes are visible in the working directory.
## `but unapply` — Unapply a Branch
Remove a branch from the workspace. Only removes that branch's changes, leaving other applied branches intact.
```bash
but unapply <branch>
```
## `but clean` — Remove Empty Branches
Remove empty branches from the workspace.
```bash
but clean
but clean --dry-run # Preview which branches would be removed
but clean --include-upstream # Also remove branches with only upstream commits
but clean --pull # Pull latest changes before cleaning
```
| Flag | Description |
|------|-------------|
| `--dry-run` | Preview which branches would be removed |
| `--include-upstream` | Also remove branches with upstream-only commits but no local commits |
| `--pull` | Pull latest changes from the remote before cleaning |
## Stacked Branches
Stacked branches are ordered, **dependent** branch sequences where each branch is based on the previous one. They allow reviewing and merging changes in sequence.
### Creating Stacks
```bash
but branch new -a <base-branch> <new-branch> # Create a stacked branch
```
The `--anchor` (`-a`) flag specifies the base. Each stacked branch depends on the one below it.
### Stack Structure
```
main (merge base)
└── feature-part1 (bottom of stack, PR targets main)
└── feature-part2 (PR targets feature-part1)
└── feature-part3 (PR targets feature-part2)
```
### Stacked PRs
When you run `but pr` on a stacked branch, GitButler creates a PR that targets the **parent branch** (not `main`). The bottom branch targets the default branch. GitHub automatic branch deletion is highly recommended for stacked PR workflow.
### Parallel vs Stacked
- **Parallel branches** are independent — no dependency between them
- **Stacked branches** depend on the ones before them
- They are complementary, not mutually exclusive — a workspace can have both
## Related
- [workspace.md](workspace.md) — Workspace model and virtual branch concepts
- [commits.md](commits.md) — Committing changes to branches
- [forge.md](forge.md) — Push and PR creation
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |