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/forge.md
View on GitHub# Forge Integration — Push, Pull, and PRs
Commands for interacting with remote repositories and forges (GitHub).
> **Source of truth**: <https://docs.gitbutler.com/cli-guides/cli-tutorial/forges>
## Supported Forges
Currently supports **GitHub** (GitLab Merge Requests planned). Supports GitHub Enterprise via PAT or device flow.
## `but push` — Push Branch to Remote
Push changes in a branch to the remote repository.
```bash
but push <branch>
```
Positional argument is the branch name to push.
## `but pull` — Update from Upstream
Fetch and rebase active branches on new upstream changes.
```bash
but pull # Fetch + rebase active branches
but pull --check # Preview what pull would do
```
`but pull` fetches the latest from the remote and updates the merge base. All applied branches are rebased onto the new upstream.
## `but pr` — Pull Request Management
Parent command for PR operations.
### `but pr new`
Create a new pull request for a branch.
```bash
but pr new <branch>
but pr new --file <template-file> <branch>
```
| Flag | Short | Description |
|------|-------|-------------|
| `--file` | | PR template file to use |
PRs are created with the branch targeting the default branch (or the parent branch for stacked PRs). Stacked PRs maintain correct base branch metadata automatically.
### `but pr setDraft`
Set a PR to draft status.
```bash
but pr setDraft <branch-or-pr>
```
Accepts CLI IDs (branches, stacks) or local branch names, comma-separated.
### `but pr setReady`
Mark a PR as ready for review (remove draft status).
```bash
but pr setReady <branch-or-pr>
```
### `but pr autoMerge`
Enable auto-merge for a PR.
```bash
but pr autoMerge <branch-or-pr>
```
Accepts CLI IDs (branches, stacks) or local branch names, comma-separated.
### `but pr template`
Manage PR templates.
```bash
but pr template
```
Uses the git worktree as the base directory for template files.
## Authentication
### `but config forge` — Forge Configuration
View and manage forge (GitHub) settings.
```bash
but config forge # View forge config
but config forge auth # Authenticate to forge (device flow or PAT)
but config forge forget # Forget a stored authentication
but config forge list-users # List authenticated forge users
```
### Authentication Methods
| Method | Description |
|--------|-------------|
| Device flow (OAuth) | Browser-based OAuth flow, no token management |
| Personal Access Token (PAT) | Manual token entry |
| GitHub Enterprise | Custom server URL with PAT or device flow |
### Forge Users
`but config forge list-users` shows authenticated users with their auth type:
```
- OAuth: user1
- PAT: user2
```
## Stacked PRs
When working with stacked branches, GitButler automatically creates stacked PRs:
- The bottom branch's PR targets the default branch (e.g. `main`)
- Each stacked branch's PR targets its **parent branch**
- GitHub automatic branch deletion is highly recommended
- The "Merge" strategy on GitHub offers the best experience for stacked PRs
```bash
but pr new feature-part1 # PR targets main
but pr new feature-part2 # PR targets feature-part1 (stacked)
```
## Review Information
Several commands support `--review` to fetch and display review information:
```bash
but branch list --review # Show PR/MR status for branches
but branch show --review # Show review info for a specific branch
```
## Related
- [branches.md](branches.md) — Branch management including stacked branches
- [config.md](config.md) — Forge configuration commands
- [workspace.md](workspace.md) — Upstream and merge base concepts
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 |