### Setup Git Repository for GitButler

Source: https://docs.gitbutler.com/cli-guides/installation

Configures an existing Git repository to be managed by GitButler. Running 'but setup' in a repository initializes the necessary changes for GitButler's data management.

```shell
but setup
```

--------------------------------

### Install GitButler CLI via Curl

Source: https://docs.gitbutler.com/cli-guides/installation

Installs the GitButler CLI tool by executing a script from a provided URL using curl. This is a quick way to get the CLI installed on your system.

```shell
curl -fsSL https://gitbutler.com/install.sh | sh
```

--------------------------------

### Path Matching Regex Examples

Source: https://docs.gitbutler.com/features/branch-management/rules

Demonstrates regular expression patterns for matching file paths in GitButler rules. These examples cover matching all TypeScript files, files within a specific directory, and documentation files.

```regex
.*\.ts$
```

```regex
^src/components/.*
```

```regex
.*\.(md|mdx)$
```

--------------------------------

### Install Claude Code via Shell Script

Source: https://docs.gitbutler.com/features/coding-agents

This command installs the Claude Code SDK using a shell script. It's a prerequisite for using GitButler's agent integration. Ensure you have the necessary permissions to execute scripts and download files.

```shell
curl -fsSL https://claude.ai/install.sh | bash
```

--------------------------------

### Install GitButler Skill (CLI)

Source: https://docs.gitbutler.com/commands/but-skill

Installs GitButler AI skill files into the current repository or globally. The command can prompt for a skill folder format or accept a custom path. Use '--global' to install system-wide.

```bash
but skill install
but skill install --global
but skill install --path .claude/skills/gitbutler
but skill install --detect
```

--------------------------------

### Content Matching Regex Examples

Source: https://docs.gitbutler.com/features/branch-management/rules

Provides examples of regular expression patterns for matching the content of changed lines (added lines) in GitButler rules. These examples include matching TODO comments, specific function calls like console.log, and deprecated patterns.

```regex
TODO
```

```regex
console\.log
```

```regex
@deprecated
```

--------------------------------

### View GitButler Configuration Overview (Shell)

Source: https://docs.gitbutler.com/commands/but-config

Displays a summary of important GitButler settings, including user details, target branch, forge configuration, and AI setup. This command requires no arguments.

```shell
but config
```

--------------------------------

### GitButler Configuration Overview

Source: https://docs.gitbutler.com/commands/but-config

View an overview of important GitButler settings, including user information, target branch, forge configuration, and AI setup.

```APIDOC
## GET /config

### Description
Displays an overview of important GitButler settings.

### Method
GET

### Endpoint
/config

### Parameters
None

### Request Example
```
but config
```

### Response
#### Success Response (200)
- **user_info** (object) - User-specific configuration details.
- **target_branch** (string) - The currently configured target branch.
- **forge_config** (object) - Configuration related to integrated forges (e.g., GitHub, GitLab).
- **ai_setup** (object) - Configuration related to AI features.

#### Response Example
```json
{
  "user_info": {
    "name": "John Doe",
    "email": "john@example.com",
    "editor": "vscode"
  },
  "target_branch": "origin/main",
  "forge_config": {
    "github": {
      "authenticated": true
    }
  },
  "ai_setup": {
    "enabled": true
  }
}
```
```

--------------------------------

### Example Claude Code Prompt Templates (JSON)

Source: https://docs.gitbutler.com/features/coding-agents

This JSON structure defines various prompt templates for Claude Code. These templates can be used to quickly seed prompts for common tasks like bug fixing, code review, refactoring, and adding tests. Users can edit this file to customize their templates.

```json
{
  "templates": [
    {
      "label": "Bug Fix",
      "template": "Please fix the bug in this code:\n\n```\n// Your code here\n```\n\nExpected behavior:\nActual behavior:\nSteps to reproduce:"
    },
    {
      "label": "Code Review",
      "template": "Please review this code for:\n- Performance issues\n- Security vulnerabilities\n- Best practices\n- Code style\n\n```\n// Your code here\n```"
    },
    {
      "label": "Refactor",
      "template": "Please refactor this code to improve:\n- Readability\n- Performance\n- Maintainability\n\n```\n// Your code here\n```\n\nRequirements:"
    },
    {
      "label": "Add Tests",
      "template": "Please write comprehensive tests for this code:\n\n```\n// Your code here\n```\n\nTest cases should cover:\n- Happy path\n- Edge cases\n- Error conditions"
    }
  ]
}
```

--------------------------------

### Cherry-pick Specific Commit using SHA

Source: https://docs.gitbutler.com/commands/but-pick

This example demonstrates how to cherry-pick a specific commit, identified by its SHA, into a target branch. The command requires the commit SHA and the name of the target branch.

```bash
but pick abc1234 my-feature
```

--------------------------------

### Interactively Select Commits for Cherry-picking

Source: https://docs.gitbutler.com/commands/but-pick

This example demonstrates how to initiate an interactive commit selection process from an unapplied branch. The command takes the unapplied branch name as input, and GitButler will prompt the user to select commits and a target branch.

```bash
but pick feature-branch
```

--------------------------------

### View GitButler Configuration

Source: https://docs.gitbutler.com/cli-guides/cli-tutorial/updating-the-base

Displays the current GitButler configuration, including user details, target branch, and forge settings. This command helps in understanding the project's setup and available subcommands for configuration.

```bash
but config
```

--------------------------------

### Get Commit Details as JSON using GitButler CLI

Source: https://docs.gitbutler.com/cli-guides/cli-tutorial/scripting

This snippet demonstrates how to retrieve detailed commit information in JSON format using the `but show --json` command. The output can be piped to tools like `jq` for further processing. This method is applicable to various GitButler commands for scripting purposes.

```bash
$ but show --json 2672465 | jq
{
  "commit": "26724656b8856871542da1e69c888b2e7330294a",
  "author": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com"
  },
  "committer": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com"
  },
  "date": "2026-02-04 07:22:53 +0100",
  "message": "hero update - new branding\n",
  "files": [
    {
      "path": "app/models/user.rb",
      "status": "modified"
    },
    {
      "path": "app/views/home/index.html.erb",
      "status": "modified"
    },
    {
      "path": "test.md",
      "status": "added"
    }
  ],
  "changeId": "pzyoupplvookqoqpussrpnnlrwqsnzkr"
}

```

--------------------------------

### Teardown Git Repository from GitButler Management

Source: https://docs.gitbutler.com/cli-guides/installation

Reverts the changes made by GitButler to a repository, returning it to a standard Git project. This command undoes GitButler's management without removing its metadata.

```shell
but teardown
```

--------------------------------

### but oplog snapshot

Source: https://docs.gitbutler.com/commands/but-oplog

Creates an on-demand snapshot of the current repository state. This is useful for marking a known good state that can be easily returned to later. An optional message can be provided to describe the snapshot.

```APIDOC
## but oplog snapshot

### Description
Creates an on-demand snapshot of the current repository state. This is useful for marking a known good state that can be easily returned to later. An optional message can be provided to describe the snapshot.

### Method
CLI Command

### Endpoint
N/A (CLI command)

### Parameters
#### Query Parameters
- **-m, --message** (string) - Optional - Message to include with the snapshot

### Request Example
```bash
but oplog snapshot
but oplog snapshot -m "My important state"
```

### Response
#### Success Response (200)
- **snapshot SHA** (string) - The SHA of the newly created snapshot.

#### Response Example
```json
{
  "snapshot_sha": "<new-snapshot-sha>"
}
```
```

--------------------------------

### Check GitButler Skill Updates (CLI)

Source: https://docs.gitbutler.com/commands/but-skill

Checks if installed GitButler skills are up-to-date with the CLI version. It scans local and global installations and can optionally update outdated skills. Use '--global' or '--local' to specify the scope.

```bash
but skill check
but skill check --update
but skill check --global
but skill check --local
```

--------------------------------

### but oplog list

Source: https://docs.gitbutler.com/commands/but-oplog

Lists the operation history of the repository, showing past operations with timestamps and descriptions. This command allows users to view previous states and identify specific oplog SHAs for restoration.

```APIDOC
## but oplog list

### Description
Lists the operation history of the repository, showing past operations with timestamps and descriptions. This command allows users to view previous states and identify specific oplog SHAs for restoration.

### Method
CLI Command

### Endpoint
N/A (CLI command)

### Parameters
#### Query Parameters
- **--since** (string) - Optional - Start from this oplog SHA instead of the head.
- **-s, --snapshot** (boolean) - Optional - Show only on-demand snapshot entries

### Request Example
```bash
but oplog list
but oplog list --since <oplog-sha>
but oplog list -s
```

### Response
#### Success Response (200)
- **oplog entries** (array) - A list of past operations, each containing timestamp, description, and SHA.

#### Response Example
```json
[
  {
    "sha": "<oplog-sha>",
    "timestamp": "<timestamp>",
    "description": "<operation description>"
  }
]
```
```

--------------------------------

### List All Configured Aliases

Source: https://docs.gitbutler.com/commands/but-alias

Retrieves and displays all currently configured command aliases.

```APIDOC
## `but alias list`

### Description
Lists all configured command aliases. This is the default action if no subcommand is specified for `but alias`.

### Method
GET (conceptually)

### Endpoint
`but alias list`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
but alias list
```

### Response
#### Success Response (200)
A list of configured aliases, typically showing the alias name and the command it expands to.

#### Response Example
```
current:
  st = status
  stv = status --verbose
  co = commit --only
```
```

--------------------------------

### View Git Log with GitButler Integration Details

Source: https://docs.gitbutler.com/troubleshooting/recovering-stuff

This command shows the Git log, including details about GitButler's integration commit. It lists the currently applied virtual branches and the files associated with each, providing a comprehensive overview of the repository's state managed by GitButler.

```bash
❯ git log
commit 2d8afe0ea811b5f24b9a6f84f6d024bb323a2db5 (HEAD -> gitbutler/workspace)
Author: GitButler <gitbutler@gitbutler.com>
Date:   Fri Feb 23 10:30:18 2024 +0100

    GitButler Integration Commit

    This is an integration commit for the virtual branches that GitButler is tracking.

    Due to GitButler managing multiple virtual branches, you cannot switch back and
    forth between git branches and virtual branches easily.

    If you switch to another branch, GitButler will need to be reinitialized.
    If you commit on this branch, GitButler will throw it away.

    Here are the branches that are currently applied:
     - Add database schema conversion script (refs/gitbutler/Add-database-schema-conversion-script)
       - butler/Gemfile
       - butler/README.md
       - butler/db/schema.rb
       - butler/db/migrate/20240209144600_change_mysql_charset.rb
       - .pscale.yml
     - Convert tables to utf8mb4 (refs/gitbutler/Convert-tables-to-utf8mb4)
       branch head: 841e4db701ca41206c03f1f4fe345f7e27d05eab
       - butler/create_column_conversions.rb

    Your previous branch was: refs/heads/sc-branch-comments

    The sha for that commit was: 5e16e99667db9d26f78110df807853a896120ff3

    For more information about what we're doing here, check out our docs:
    https://docs.gitbutler.com/features/branch-management/integration-branch
```

--------------------------------

### Cherry-pick Commit using CLI ID

Source: https://docs.gitbutler.com/commands/but-pick

This example shows how to cherry-pick a commit using its CLI ID, which is a shorthand identifier shown in the 'but status' command. The command requires the CLI ID and the name of the target branch.

```bash
but pick c5 my-feature
```

--------------------------------

### but oplog restore

Source: https://docs.gitbutler.com/commands/but-oplog

Restores the repository to a specific previous state identified by an oplog SHA. This command allows users to revert to a known good state or undo recent changes.

```APIDOC
## but oplog restore

### Description
Restores the repository to a specific previous state identified by an oplog SHA. This command allows users to revert to a known good state or undo recent changes.

### Method
CLI Command

### Endpoint
N/A (CLI command)

### Parameters
#### Path Parameters
- **<OPLOG_SHA>** (string) - Required - Oplog SHA to restore to.

#### Query Parameters
- **-f, --force** (boolean) - Optional - Skip confirmation prompt.

### Request Example
```bash
but oplog restore <oplog-sha>
but oplog restore <oplog-sha> -f
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful restoration.

#### Response Example
```json
{
  "message": "Repository successfully restored to <oplog-sha>."
}
```
```

--------------------------------

### Git Commit Pre-commit Hook Error in GitButler Mode

Source: https://docs.gitbutler.com/features/branch-management/integration-branch

This example demonstrates the error message received when attempting to commit directly to the `gitbutler/workspace` branch. It shows the `pre-commit` hook preventing the commit and providing instructions on how to use GitButler for committing or how to exit GitButler mode.

```bash
❯ git commit -am 'commit on the workspace branch'

GITBUTLER_ERROR: Cannot commit directly to gitbutler/workspace branch.

GitButler manages commits on this branch. Please use GitButler to commit your changes:
  - Use the GitButler app to create commits
  - Or run 'but commit' from the command line

If you want to exit GitButler mode and use normal git:
  - Run 'but teardown' to switch to a regular branch
  - Or directly checkout another branch: git checkout <branch>

If you no longer have the GitButler CLI installed, you can simply remove this hook and checkout another branch:
  rm ".git/hooks/pre-commit"


```

--------------------------------

### but pr new

Source: https://docs.gitbutler.com/commands/but-pr

Creates a new pull request for a specified branch. If no branch is provided, the user will be prompted to select one. This command allows for setting the PR title and description via arguments or a file, and provides options for force pushing, skipping protection checks, and running hooks.

```APIDOC
## POST /api/gitbutler/pr/new

### Description
Creates a new pull request for a specified branch. If no branch is provided, the user will be prompted to select one. This command allows for setting the PR title and description via arguments or a file, and provides options for force pushing, skipping protection checks, and running hooks.

### Method
POST

### Endpoint
`/api/gitbutler/pr/new`

### Parameters
#### Path Parameters
* **BRANCH** (string) - Optional - The branch to create a PR for.

#### Query Parameters
* **-m, --message** (string) - Optional - PR title and description. The first line is the title, the rest is the description.
* **-F, --file** (string) - Optional - Read PR title and description from file. The first line is the title, the rest is the description.
* **-f, --with-force** (boolean) - Optional - Force push even if it's not fast-forward (defaults to true).
* **-s, --skip-force-push-protection** (boolean) - Optional - Skip force push protection checks.
* **-r, --run-hooks** (boolean) - Optional - Run pre-push hooks (defaults to true).
* **-t, --default** (boolean) - Optional - Use the default content for the PR title and description, skipping any prompts. If the branch contains only a single commit, the commit message will be used (default: `false`).

### Request Example
```json
{
  "branch": "feature-branch",
  "message": "feat: Implement new feature\n\nThis PR adds the new feature as discussed.",
  "with_force": true,
  "skip_force_push_protection": false,
  "run_hooks": true,
  "default": false
}
```

### Response
#### Success Response (200)
* **status** (string) - Indicates the success of the operation.
* **pr_url** (string) - The URL of the created pull request.

#### Response Example
```json
{
  "status": "success",
  "pr_url": "https://github.com/user/repo/pull/123"
}
```
```

--------------------------------

### Edit Commit Message with GitButler

Source: https://docs.gitbutler.com/cli-guides/cli-tutorial/editing-commits

This command allows you to edit the commit message of any commit in your workspace. It opens your default editor with the existing message, and upon saving and exiting, it updates the commit message and rebases subsequent commits. Ensure GitButler is installed and configured.

```bash
$ but reword <sha>
# Editor opens with commit message
# Save and exit editor to apply changes
```

--------------------------------

### but pr template

Source: https://docs.gitbutler.com/commands/but-pr

Configures the template to be used for pull request descriptions. This command lists available templates in the repository and allows the user to select one.

```APIDOC
## POST /api/gitbutler/pr/template

### Description
Configures the template to be used for pull request descriptions. This command lists available templates in the repository and allows the user to select one.

### Method
POST

### Endpoint
`/api/gitbutler/pr/template`

### Parameters
#### Path Parameters
* **TEMPLATE_PATH** (string) - Required - Path to the PR template file within the repository.

### Request Example
```json
{
  "template_path": ".github/pull_request_template.md"
}
```

### Response
#### Success Response (200)
* **status** (string) - Indicates the success of the configuration.
* **message** (string) - Confirmation message.

#### Response Example
```json
{
  "status": "success",
  "message": "PR template configured successfully."
}
```
```

--------------------------------

### Unassigning File Changes with 'but rub'

Source: https://docs.gitbutler.com/cli-guides/cli-tutorial/rubbing

Demonstrates how to unassign file changes from a branch by 'rubbing' them to the 'zz' identifier, which represents unassigned changes. This is useful for reverting previous assignments or moving changes to a different lane.

```bash
but status
# Output showing staged and unstaged changes
# ...
but rub h0 zz
```

--------------------------------

### Configure GitButler Cursor Hooks in hooks.json

Source: https://docs.gitbutler.com/features/ai-integration/cursor-hooks

This JSON configuration sets up GitButler hooks for Cursor. The `afterFileEdit` hook triggers the 'but cursor after-edit' command after each file edit, and the `stop` hook runs 'but cursor stop' when a task is completed. This enables automatic branch creation, assignment to active branches, and commit message generation based on prompts.

```json
{
  "version": 1,
  "hooks": {
    "afterFileEdit": [
      {
        "command": "but cursor after-edit"
      }
    ],
    "stop": [
      {
        "command": "but cursor stop"
      }
    ]
  }
}
```

--------------------------------

### Push Git Butler Reference to GitHub

Source: https://docs.gitbutler.com/troubleshooting/recovering-stuff

This command demonstrates how to push a GitButler virtual branch reference to a remote repository (GitHub in this case) as a standard Git branch. This allows for collaboration and backup of virtual branches.

```bash
❯ git push origin refs/gitbutler/Convert-tables-to-utf8mb4:refs/heads/convert-tables
Enumerating objects: 6, done.
Counting objects: 100% (6/6), done.
Delta compression using up to 10 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 474 bytes | 474.00 KiB/s, done.
Total 4 (delta 2), reused 1 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
remote:
remote: Create a pull request for 'convert-tables' on GitHub by visiting:
remote:      https://github.com/gitbutlerapp/web/pull/new/convert-tables
remote:
To github.com:gitbutlerapp/web.git
 * [new branch]        refs/gitbutler/Convert-tables-to-utf8mb4 -> convert-tables
```

--------------------------------

### Add GitButler MCP Server in Claude Code

Source: https://docs.gitbutler.com/features/ai-integration/mcp-server

This snippet demonstrates the command-line usage for adding the GitButler MCP server to Claude Code. It shows the command to add the server and how to list configured servers.

```bash
❯ claude mcp add gitbutler but mcp
Added stdio MCP server gitbutler with command: but mcp to local config

❯ claude mcp list
gitbutler: but mcp
```

--------------------------------

### Configure GitButler Custom CSP Hosts

Source: https://docs.gitbutler.com/troubleshooting/custom-csp

Add custom hosts to GitButler's Content Security Policy by editing the `settings.json` file. This allows connections to self-hosted instances of GitHub, GitLab, or Ollama. The `extraCsp` object contains a `hosts` array where you can specify your custom domains.

```json
{
  "extraCsp": {
    "hosts": ["https://subdomain.example.com", "http://another-subdomain.example.com"]
  }
}
```

--------------------------------

### Forge Configuration Management

Source: https://docs.gitbutler.com/commands/but-config

View and manage forge configurations, including authentication status and account details.

```APIDOC
## Forge Configuration

### Description
Manages forge configurations, allowing users to view, authenticate, and forget forge accounts.

### Method
GET, POST, DELETE

### Endpoint
/config/forge

### Parameters
#### Query Parameters
- **action** (string) - Required - The action to perform (e.g., 'view', 'auth', 'list-users', 'forget').
- **username** (string) - Optional - The username of the account to forget.

### Request Example
```bash
# View configured forge accounts
but config forge

# Authenticate with a forge
but config forge auth

# List authenticated accounts
but config forge list-users

# Forget an account
but config forge forget username
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the operation or list of accounts.

#### Response Example
```json
{
  "message": "Forge account 'username' forgotten successfully."
}
```
```