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/commits.md
View on GitHub# Commits and Staging
Commands for creating, editing, and managing commits in the GitButler workspace.
> **Source of truth**: <https://docs.gitbutler.com/cli-guides/cli-tutorial/branching-and-commiting> and <https://docs.gitbutler.com/cli-guides/cli-tutorial/editing-commits>
## `but commit` — Create a Commit
Commit changes to a stack (virtual branch). This is the primary commit command.
```bash
but commit -m "message" <branch>
but commit --ai -m "instructions" <branch>
but commit -p h0,i0 -m "message" <branch>
but commit --only -m "message" <branch>
```
### Flags
| Flag | Short | Description |
|------|-------|-------------|
| `--after` | | Insert the commit after this commit or branch |
| `--ai` | `-i` | Generate commit message using AI with optional user summary |
| `--all` | `-a` | No-op compatibility flag for `git commit -a` |
| `--before` | | Insert the commit before this commit or branch |
| `--changes` | `-p` | Uncommitted file or hunk CLI IDs to include (comma-separated or repeated) |
| `--create` | `-c` | Create a new branch for this commit |
| `--diff` | | Always show diff inside the editor |
| `--message` | `-m` | Commit message |
| `--message-file` | | Read commit message from file |
| `--no-diff` | | Never show the diff inside the editor |
| `--no-hooks` | `-n` | Bypass pre-commit hooks |
| `--no-verify` | | Bypass pre-commit hooks (hidden alias for `--no-hooks`) |
| `--only` | `-o` | Only commit staged files, not unstaged files |
The `--ai` flag uses `NoOptDefVal = " "`, so `--ai` by itself generates a message, or `--ai="your instructions"` provides guidance.
The `--after` and `--before` flags insert commits at specific positions in a stack, enabling fine-grained commit ordering without rebase.
### Positional Argument
The positional argument is the branch name to commit to. If `--create` is used and the branch doesn't exist, it's created.
### Committing Specific Files/Hunks
Use `--changes` (`-p`) with CLI IDs to commit specific files or hunks:
```bash
but commit -p h0,i0 -m "message" <branch> # Specific hunks by CLI ID
but commit -p app/models/foo.rb -m "msg" # By file path (via git changes)
```
CLI IDs are multi-part identifiers (e.g. `h0`, `i0`, `c3`) shown in `but status -f`. See [inspection.md](inspection.md) for the CLI ID system.
## `but commit empty` — Insert Blank Commit
Insert a blank commit before or after a specified commit. Used for splitting commits.
```bash
but commit empty --after <sha> # Insert blank commit after
but commit empty --before <sha> # Insert blank commit before
but commit empty --after <sha> -m "msg" # With a message (since 0.20.4)
```
| Flag | Short | Description |
|------|-------|-------------|
| `--after` | | Insert the blank commit after this commit or branch |
| `--before` | | Insert the blank commit before this commit or branch |
| `--message` | `-m` | Commit message for the inserted blank commit |
After creating a blank commit, use `but rub` to move changes into it. See [rubbing.md](rubbing.md).
## `but stage` — Stage Changes to a Branch
Assign file or hunk changes to a specific branch. This is like `git add` but for multiple virtual branches.
```bash
but stage <file> <branch>
but stage -b <branch> # Interactive mode (specify branch first)
but stage # Interactive hunk picker (no args)
```
| Flag | Short | Description |
|------|-------|-------------|
| `--branch` | `-b` | Branch to stage to (for interactive mode) |
The positional arguments are: changes (CLI IDs or file paths, comma-separated) and branch name.
Running `but stage` without arguments opens the interactive hunk picker in the TUI.
## `but amend` — Amend Changes into a Commit
Amend one or more file changes into a specific commit. Rebases any dependent commits.
```bash
but amend <commit>
but amend -p h0,i0 <commit> # Amend specific changes
```
| Flag | Short | Description |
|------|-------|-------------|
| `--changes` | `-p` | Uncommitted file or hunk CLI IDs to amend into the commit |
The positional argument is the commit to amend into (commit SHA or CLI ID).
## `but squash` — Squash Commits Together
Squash two commits into one.
```bash
but squash <source-commit> <target-commit>
but squash --ai <source> <target> # AI-generated combined message
but squash -d <source> <target> # Drop source message, keep target's
```
| Flag | Short | Description |
|------|-------|-------------|
| `--ai` | `-i` | Generate commit message using AI |
| `--drop-message` | `-d` | Drop source commit messages, keep only target's |
| `--message` | `-m` | Provide a new commit message for the resulting commit |
Two positional arguments: source commit and target commit (commit SHAs or CLI IDs).
## `but reword` — Edit Commit Message
Edit the commit message of the specified commit. Opens an editor.
```bash
but reword <commit>
```
Can also rename a branch:
```bash
but reword -m <new-name> <branch>
```
## `but move` — Move a Commit or Branch
Move a commit or branch to a different location.
```bash
but move <commit> <target>
```
| Flag | Short | Description |
|------|-------|-------------|
| `--after` | | Move after this commit or branch |
Two positional arguments: the entity to move (commit) and the target (commit or branch).
## `but pick` — Cherry-Pick a Commit
Cherry-pick a commit from an unapplied branch into an applied virtual branch.
```bash
but pick <commit> <branch>
```
Two positional arguments: the commit to pick and the target branch.
## `but absorb` — Auto-Amend Changes
Amends changes into the appropriate commits where they belong. GitButler automatically determines which commits each change should be amended into.
```bash
but absorb
but absorb --dry-run # Show the absorption plan without changes
```
| Flag | Description |
|------|-------------|
| `--dry-run` | Show the absorption plan without making any changes |
## `but uncommit` — Uncommit Changes
Uncommit changes from a commit to the unstaged area.
```bash
but uncommit <commit>
but uncommit --diff <commit> # Show resulting uncommitted diff (since 0.20.4)
but uncommit --discard <commit> # Discard instead of moving to uncommitted
```
| Flag | Short | Description |
|------|-------|-------------|
| `--diff` | | Show the resulting uncommitted diff after uncommitting |
| `--discard` | `-d` | Discard the selected committed changes instead of moving them to uncommitted |
## `but discard` — Discard Uncommitted Changes
Discard uncommitted changes from the worktree.
```bash
but discard <file>
```
Positional arguments are file paths or CLI IDs of changes to discard.
## Related
- [rubbing.md](rubbing.md) — The `but rub` command for combining entities
- [inspection.md](inspection.md) — CLI IDs and status output
- [branches.md](branches.md) — Branch management
- [oplog.md](oplog.md) — Undo/redo for commit operations
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 |