# GitButler Version Control

Commits, branches, and manages history and PRs with the GitButler but CLI.

- Repository: https://github.com/gitbutlerapp/gitbutler (21903 stars)
- Category: Git and review
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add gitbutlerapp/gitbutler --skill but -g -a claude-code -y`
Codex: `npx skills add gitbutlerapp/gitbutler --skill but -g -a codex -y`
Cursor: `npx skills add gitbutlerapp/gitbutler --skill but -g -a cursor -y`
Gemini CLI: `npx skills add gitbutlerapp/gitbutler --skill but -g -a gemini-cli -y`

## Description

Commit, push, branch, and manage version control with GitButler. Use for commits, selective dirty-file or hunk commits, branches, diffs, PRs, history edits, squashes, amends, undo, merge, fetching, pulling and syncing a branch with its remote, apply, unapply, and linked worktrees. For selected dirty files or hunks, inspect with `but diff`; use compact `but status` for commit order, branch/stack placement, or conflict overview; use `but status -fv` when file IDs or per-commit file details matter. Replaces git write commands, including fetch and pull. Applies in every checkout of the repository, even when a plain branch is checked out, including linked worktrees such as `.claude/worktrees/*`, and to git writes made while testing or cleaning up (stash, checkout -- <file>, restore, reset).

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# GitButler CLI Skill

Use GitButler CLI (`but`) as the default version-control interface.

## Start Here

Choose the narrowest first command by task; avoid ritual status checks:

```bash
# Selected dirty files/hunks:
but diff

# Commit order, branch/stack placement, conflict overview:
but status

# File IDs, per-commit files, amend details:
but status -fv

# What one applied branch or commit changed, for review:
but diff <branch-or-commit>

# Details for one known branch or commit:
but show <id>
```

Do not run plain `but status` and then `but status -fv` unless the compact output lacks file details needed for the task.

For "commit just/only/specific changes on a new branch", use the fast path:

```bash
but diff
but commit -b <branch> -m "<msg>" <id> <id>
```

`but commit -b <branch> ...` creates the branch when it does not exist and prints the created commit. Do not run a separate `but branch new`, status command, or verification diff unless the task needs workspace information that the result does not provide.

In a linked worktree, such as `.claude/worktrees/*`, omit `-b` so the commit goes on the branch the worktree has checked out. Use that branch as the new branch; do not stack another one on it. A worktree with a detached HEAD has no branch yet. There, `but commit -b <new-name> -m "<msg>"` creates the branch at HEAD, checks it out in that worktree, and commits to it.

## IDs

The first token on each `but diff` / `but status` line is that line's ID. When a command needs an ID, copy it exactly from the current output; never hardcode or invent one. ID lifetimes differ by entity:

The rest: https://github.com/gitbutlerapp/gitbutler/blob/HEAD/crates/but/skill/SKILL.md