### Start the AI Agent Setup Wizard (No Subcommand)

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/ai-agents/getting-started.mdx

Starts the AI agent setup wizard when no subcommand is provided to `but agent`. This is an alternative way to launch the setup process.

```sh
but agent
```

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

### Setup GitButler Agent

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/ai-agents/overview.mdx

Run this command in your repository to set up the GitButler agent. The wizard guides you through installing the GitButler skill, configuring version-control instructions for your agent, and preparing the repository.

```sh
but agent setup
```

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

### Start Interactive AI Setup

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/commands/but-config.mdx

Initiates an interactive process to set up AI provider configurations.

```text
but config ai
```

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

### Start Development Server with PNPM

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/README.md

Start the local development server using PNPM. This command is used after installing dependencies.

```bash
pnpm dev
```

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

### Configure ansi-run.json

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/CLI-DOCS.md

Configure the ansi-run.json file with your example project path, starting commit hash, and cache settings.

```json
{
  "exampleProjectPath": "/path/to/example/project",
  "startingHash": "initial-commit-hash",
  "config": {
    "cacheDir": "content/cache",
    "outputFormat": "svg"
  }
}
```

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

### Install GitButler Skill Interactively

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/commands/but-skill.mdx

Use this command to interactively install GitButler skill files. It will prompt for the installation scope (repository or global) and the desired skill folder format.

```bash
but skill install
```

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

### Install the `but` CLI

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/ai-agents/getting-started.mdx

Installs the GitButler CLI tool. Run this command in your terminal for a terminal-only setup.

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

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

### Install Dependencies with PNPM

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/README.md

Install project dependencies using PNPM. Make sure PNPM is installed globally.

```bash
pnpm install
```

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

### Install or Update GitButler Skill

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/cli-guides/cli-tutorial/ai-stuff.mdx

Use this command to install or update the GitButler skill files without going through the full setup wizard prompts. The `--detect` flag allows for an update without interactive prompts.

```bash
but skill install --detect
```

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

### Valid Local GitButler Storage Path Examples

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/development/debugging.mdx

Examples of valid Git config commands for setting the local GitButler storage path.

```bash
git config --local gitbutler.storagePath gitbutler-alt
```

```bash
git config --local gitbutler.storagePath ../../gitbutler-projects
```

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

### Install GitButler Skill Globally

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/commands/but-skill.mdx

Installs the GitButler skill files globally in your home directory. This command will prompt for the skill folder format.

```bash
but skill install --global
```

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

### Generate PDFs with Dev Server

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/CHEAT-SHEET-README.md

Demonstrates the required setup for PDF generation: running the dev server in one terminal and the generation command in another.

```bash
# Terminal 1: Start dev server
pnpm dev

# Terminal 2: Generate PDFs
pnpm generate-cheat-pdfs
```

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

### Path Matches Regex Examples

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/features/branch-management/rules.mdx

Examples of regular expressions for matching file paths in rules.

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

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

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

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

### Example Workflow: Create and Update MDX with CLI Commands

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/CLI-DOCS.md

Demonstrates the workflow of creating a new MDX file with CLI commands and then running the update script to process and update the outputs.

```mdx
# Status Command

Check your workspace status:

```cli
but status
```
```

```bash
pnpm update-cli
```

```mdx
# Status Command

Check your workspace status:

```cli [abc123def456]
but status
```
```

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

### Git Status Output Example

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/cache/cli-output/rubbing-but-status-4.html

An example of the output from the 'but status' command, illustrating unstaged changes and commit details.

```shell
body {
  background-color: #ffffff;
  color: #24292e;
  font-family: 'Consolas', 'Courier New', monospace;
  padding: 20px;
  margin: 0;
}

pre {
  white-space: pre-wrap;
  word-wrap: break-word;
}

╭┄zz [**unstaged changes**]
┊     _no changes_
┊
┊╭┄sq [**squash-example**]
┊●   0fa2965 the second commit
┊●   080a970 the original commit
├╯
┊
┊● 32a2175 (upstream) ⏫ 2 new commits
├╯ 204e309 (common base) [**origin/main**] 2025-07-06 Merge pull request #10 from schacon/sc-description

Hint: run `but help` for all commands
```

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

### Install GitButler CLI with Curl

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/cli-guides/installation.mdx

Use this command to install the GitButler CLI directly from your terminal.

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

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

### Configure AI Provider Settings

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/llms-full.txt

Configure AI provider settings non-interactively or start an interactive setup flow. Use `--local` to configure local repository git config.

```text
but config ai
```

```text
but config ai show
```

```text
but config ai openai --key-option bring-your-own --api-key-env OPENAI_API_KEY --model gpt-5.4-nano
```

```text
but config ai --local ollama --endpoint localhost:11434 --model llama3.1
```

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

### Initialize Git Repository and Setup GitButler

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/commands/but-setup.mdx

Use this command to initialize a new Git repository and set up GitButler simultaneously. It ensures a Git repository exists with an initial commit, which is particularly useful for non-interactive environments like CI/CD pipelines.

```bash
but setup --init
```

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

### Manually Setup GitButler Workspace

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/cli-guides/cli-tutorial/initializing-a-repository.mdx

Run this command to explicitly set up your repository for GitButler management. It configures necessary branches and hooks.

```bash
but setup
```

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

### Install Puppeteer for PDF Generation

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/CHEAT-SHEET-README.md

Install the Puppeteer package using pnpm to resolve '503' errors during PDF downloads. After installation, restart your development server.

```bash
pnpm add puppeteer
```

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

### Generate PDFs for Production

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/CHEAT-SHEET-README.md

Steps to generate PDFs for a production environment, including building the site, starting the production server, and running the PDF generation command with a specified base URL.

```bash
# Build the site
pnpm build

# Start production server
pnpm start &

# Generate PDFs
NEXT_PUBLIC_BASE_URL=http://localhost:3000 pnpm generate-cheat-pdfs

# Or set your production URL
NEXT_PUBLIC_BASE_URL=https://yourdomain.com pnpm generate-cheat-pdfs
```

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

### Start a Parallel Agent Session

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/ai-agents/parallel-agents.mdx

Initiate a new coding session for an agent by providing a task description. The agent will work on this task without requiring a separate worktree.

```text
Work on checkout validation.
```

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

### Install GitButler Skill to Custom Path

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/commands/but-skill.mdx

Installs the GitButler skill files to a specified custom path. This path can be relative to the repository root or an absolute path. When outside a git repository, relative paths require the --global flag.

```bash
but skill install --path .agents/skills/gitbutler
```

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

### Example Commit Message Editor

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/cli-guides/cli-tutorial/editing-commits.mdx

This is an example of what the commit message editor looks like when using `but reword`. It displays the current message and includes comments for guidance.

```text
add user changes

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Changes in this commit:
#       modified:   app/models/user.rb
#       modified:   config/routes.rb
#
~
~
~
~
```

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

### Authenticate to a Forge

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/cli-guides/cli-tutorial/forges.mdx

Set up authentication for a forge, such as GitHub, by running `but config forge auth`. This command guides you through selecting an authentication method like Device flow or Personal Access Token.

```bash
❯ but config forge auth
? Select an authentication method:
> Device flow (OAuth)
  Personal Access Token (PAT)
  GitHub Enterprise
```

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

### JSON Example with Level Filtering

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/CHEAT-SHEET-README.md

Illustrates how to use the 'level' property to control the visibility of sections and items. 'advanced' items are hidden in basic mode.

```json
{
  "title": "Branch Management",
  "level": "basic",
  "items": [
    {
      "command": "but branch",
      "description": "List branches"
      // Defaults to "basic"
    },
    {
      "command": "but branch --advanced-flag",
      "description": "Advanced operation",
      "level": "advanced"
      // Hidden in basic mode
    }
  ]
}
```

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

### Pick a Commit using CLI ID

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/commands/but-pick.mdx

This example demonstrates picking a commit identified by its CLI ID into a target branch.

```text
but pick c5 my-feature
```

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

### Set Up the Repository for Workspace Mode

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/ai-agents/getting-started.mdx

Configures the current repository to use GitButler's workspace mode, which is necessary for its multi-branch model. This can also be run automatically by the agent setup wizard.

```sh
but setup
```

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

### Clone GitButler Repository

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/README.md

Use this command to clone the GitButler documentation repository. Ensure you have Git installed.

```bash
git clone https://github.com/gitbutlerapp/gitbutler-docs.git
```

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

### Authenticate to a Forge with GitButler CLI

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/llms-full.txt

Run `but config forge auth` to initiate the authentication process for a forge. This command guides you through selecting an authentication method, such as Device flow (OAuth) or Personal Access Token (PAT).

```bash
❯ but config forge auth
? Select an authentication method:
> Device flow (OAuth)
  Personal Access Token (PAT)
  GitHub Enterprise
```

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

### Example Commit Message Format

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/llms-full.txt

This format demonstrates a professional commit message structure with a semantic prefix, a concise title, and a detailed body explaining the changes and their rationale.

```markdown
feat: add user authentication system

Implements JWT-based authentication with login and registration
endpoints. Includes password hashing and session management
to secure user accounts.
```

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

### Create a Manual Snapshot

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/cli-guides/cli-tutorial/operations-log.mdx

Manually create a snapshot of the current project state, which can be restored to later using its SHA.

```cli
but oplog snapshot
```

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

### Dockerfile for Puppeteer Dependencies

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/CHEAT-SHEET-README.md

Example Dockerfile snippet to install necessary Chrome dependencies for Puppeteer to function in a Dockerized environment.

```dockerfile
# Add to your Dockerfile
RUN apt-get update && apt-get install -y \
    chromium \
    chromium-sandbox \
    fonts-liberation \
    && rm -rf /var/lib/apt/lists/*
```

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

### View Configuration Overview

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/commands/but-config.mdx

Displays a summary of important GitButler settings when no subcommand is provided.

```text
but config
```

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

### Install or Update GitButler Application

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/llms-full.txt

Installs or updates the GitButler desktop application or CLI. It auto-detects the channel (release/nightly) and installs the latest version. For Linux, it updates only the CLI.

```text
but update install
```

```text
but update install nightly
```

```text
but update install release
```

```text
but update install 0.18.7
```

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

### View and Set User Configuration

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/llms-full.txt

Manage user-specific settings like name and email. Use `--global` to set configuration globally.

```text
but config user
```

```text
but config user set name "John Doe"
```

```text
but config user set --global email john@example.com
```

```text
but config user unset name
```

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

### Initialize Git Repository with GitButler

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/llms-full.txt

Use this command to initialize a new Git repository and set up GitButler if one doesn't already exist. This is particularly useful for non-interactive environments like CI/CD pipelines.

```text
but setup --init
```

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

### Check All Installed GitButler Skills

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/commands/but-skill.mdx

Scans all installed GitButler skill files (both local and global) and checks if they are up to date with the current CLI version.

```bash
but skill check
```

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

### View GitButler Settings

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/development/debugging.mdx

Display the contents of the settings.json file, which holds top-level application preferences.

```bash
cat settings.json
{
  "appAnalyticsConfirmed": true,
  "appNonAnonMetricsEnabled": true
}
```

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

### Content Matches Regex Examples

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/features/branch-management/rules.mdx

Examples of regular expressions for matching content within changed lines in rules. This filter only considers added lines.

```regex
TODO
```

```regex
console\.log
```

```regex
@deprecated
```

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

### Example Commit Message Format

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/features/branch-management/ai-assistance.mdx

This is an example of a professionally formatted commit message generated by AI, including semantic prefixes, a concise title, and a detailed body.

```text
feat: add user authentication system

Implements JWT-based authentication with login and registration
endpoints. Includes password hashing and session management
to secure user accounts.
```

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

### GitButler CLI Help Command

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/cache/cli-output/updating-the-base-but-status-1.html

Displays available commands and usage information for the GitButler CLI. Run this to see all available options.

```bash
but help
```

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

### ASCII Diagram JSON Structure

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/CHEAT-SHEET-README.md

Example of embedding an ASCII diagram within the cheat sheet JSON structure.

```json
{
  "diagram": {
    "type": "ascii",
    "content": "    Workspace\n       |\n   +---+---+\n   |   |   |\nBranch1 Branch2 Branch3"
  }
}
```

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

### Manual Run with ansi-senor

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/CLI-DOCS.md

Manually run `ansi-senor <command>` to generate an HTML file that can be copied to `public/cli-examples/` and referenced in documentation.

```ansi
but setup-5faf7f36
```

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

### Check Only Global GitButler Skills

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/commands/but-skill.mdx

Specifically checks only the GitButler skill installations located in the global home directory for updates.

```bash
but skill check --global
```

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

### Navigate and List Log Files

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/llms-full.txt

Commands to navigate to the log directory and list the available log files using the 'tree' command.

```bash
❯ cd ~/Library/Logs/com.gitbutler.app

❯ tree -L 1

├── GitButler.log
├── GitButler.log.2023-09-02
├── GitButler.log.2023-09-03
├── GitButler.log.2023-09-04
├── GitButler.log.2023-09-05
├── GitButler.log.2023-09-06
├── GitButler.log.2023-09-07
├── GitButler.log.2023-09-08
├── GitButler.log.2023-10-10
├── GitButler.log.2024-01-30
└── tokio-console
```

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

### Launch GitButler Desktop Client GUI

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/ai-agents/review-agent-work.mdx

Use this command to open the GitButler Desktop Client GUI. This provides a visual overview of branches, commits, and changes, and is ideal for adjusting commit history.

```sh
but gui
```

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

### Header Gradient Styling

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/CHEAT-SHEET-README.md

Example of how to apply a background gradient to the header using Tailwind CSS classes in the page component.

```tsx
className="bg-gradient-to-r from-teal-600 to-teal-700"
```

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

### Windows Settings File Path

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/troubleshooting/fetch-push.mdx

Locate the GitButler settings file on Windows.

```bash
```bash C:\Users\[username]\AppData\Roaming\gitbutler\settings.json ```
```

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

### View Target Branch Configuration

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/cli-guides/cli-tutorial/updating-the-base.mdx

Get detailed information about the currently configured target branch in GitButler. This helps in understanding the base for your feature branches.

```cli
but config target
```

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

### View UI Configuration

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/commands/but-config.mdx

Displays the current UI settings, including TUI mode preferences.

```text
but config ui
```

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

### Set review title and description from file

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/llms-full.txt

Use the `-F` option to read the review title and description from a file. The first line of the file will be the title.

```text
-F, --file <FILE> — Read review title and description from file. The first line is the title, the rest is the description
```

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

### Customize Branch Names

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/ai-agents/tuning-agent-behavior.mdx

Adapt agent-created branch names to your team's convention. This example shows a format including a ticket ID and a short description.

```md
- When creating a GitButler branch for an agent session, use `feature/<ticket-id>-<short-description>` when a ticket ID is available.
```

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

### Initiate Conflict Resolution

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/cli-guides/cli-tutorial/conflict-resolution.mdx

Start the conflict resolution process by running `but resolve`. This command identifies conflicted commits and prompts you to select one to begin resolving.

```cli
but resolve
```

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

### CLI Hints for Viewing Diffs and Staging Files

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/cache/cli-output/branching-and-commiting-but-status-8.html

Provides guidance on how to view uncommitted changes and stage them to the current branch using Git Butler CLI commands.

```shell
Hint: run `but diff` to see uncommitted changes and `but stage <file>` to stage them to a branch
```

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

### Configure OpenAI Non-interactively

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/commands/but-config.mdx

Sets up OpenAI configuration using specified options like API key environment variable and model.

```text
but config ai openai --key-option bring-your-own --api-key-env OPENAI_API_KEY --model gpt-5.4-nano
```

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

### View and Set User Configuration

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/commands/but-config.mdx

Manage user-specific settings like name and email. Use 'set' to update values and 'unset' to remove them. Global settings can be applied with the --global flag.

```text
but config user
```

```text
but config user set name "John Doe"
```

```text
but config user set email john@example.com
```

```text
but config user set --global email john@example.com
```

```text
but config user unset name
```

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

### Git Log Output with GitButler Workspace Branch

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/workspace-branch.mdx

This is a typical output of `git log` when in a GitButler-managed repository, showing the special `gitbutler/workspace` commit and an example applied branch.

```git
commit de56d20e282f7641d48d288b510141996c3c3cfc (HEAD -> gitbutler/workspace)
Author: GitButler <gitbutler@gitbutler.com>
Date:   Wed Sep 9 09:06:03 2020 +0800

    GitButler Workspace Commit

    This is is a merge commit of the parallel branches in your workspace.

    For GitButler to manage multiple parallel branches, we maintain
    this commit automatically so other tooling works properly.

    If you switch to another branch, GitButler will need to be
    reinitialized.

    Here are the branches that are currently applied:

     - update-homepage (refs/gitbutler/update-homepage)
       branch head: a32f33273948837078e5f5a4e1677ab6274a4629

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

commit a32f33273948837078e5f5a4e1677ab6274a4629 (update-homepage)
Author: Scott Chacon <schacon@gmail.com>
Date:   Mon Jan 26 07:33:31 2026 +0500

    hero update - new branding

```

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

### Show Commit Details as JSON

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/cli-guides/cli-tutorial/scripting.mdx

Append the `--json` option to `but show` to get machine-readable JSON output. Pipe this output to `jq` for easy parsing and manipulation.

```cli
but show --json 2672465 | jq
```

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

### Set review title and description from message

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/llms-full.txt

Use the `-m` option to provide a review title and description directly. The first line is the title, and the rest forms the description.

```text
-m, --message <MESSAGE> — review title and description. The first line is the title, the rest is the description
```

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

### Show Branch Information

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/cache/cli-output/inspecting-but-branch-4.html

Displays detailed information about a specific branch, including commits and associated reviews. Use this to get a quick overview of a branch's status and changes.

```bash
/usr/local/bin/but branch show sc-branch-28 --ai -r -f body
```

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

### Windows Configuration File Path

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/troubleshooting/custom-csp.mdx

Locate the GitButler settings file on Windows to edit its configuration.

```bash
C:\Users\[username]\AppData\Roaming\gitbutler\settings.json
```

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

### Print Default Agent Steering Text

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/commands/but-agent.mdx

Displays the default generated steering text for GitButler agents without initiating the interactive setup or modifying any files. Useful for previewing configurations.

```text
but agent setup --print
```

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

### Configure Global Git Signing Settings

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/features/branch-management/signing-commits.mdx

Set your signing key, GPG format, and enable GitButler commit signing globally. This ensures all your repositories are configured for signed commits.

```bash
git config --global user.signingkey "/Users/schacon/.ssh/id_ed25519.pub"
git config --global gpg.format ssh
git config --global gitbutler.signCommits true
```

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

### Pre-commit Hook Rejection on GitButler Workspace Branch

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/llms-full.txt

This example shows the output when attempting to commit directly to the `gitbutler/workspace` branch, which is disallowed by the pre-commit hook. It provides instructions on how to resolve the issue.

```git
❯ 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"

```

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

### Example JSON Output for a Commit

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/cache/cli-output/scripting-but-show-2.html

This JSON represents the output of the 'but show --json' command, detailing commit hash, author, committer, date, message, and file changes.

```json
{
  "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"
}
```

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

### Show Git Branches with Head

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/cli-guides/cli-tutorial/inspecting.mdx

List the first 10 branches from the output of `git branch`. This is a standard Git command for viewing local branches.

```cli
git branch | head -10
```

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

### Initiate Conflict Resolution

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/llms-full.txt

Run `but resolve` to begin the process of resolving conflicted commits. GitButler will identify conflicted commits and prompt you to select one to start with, defaulting to the earliest one.

```cli
but resolve
```

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

### Linux Settings File Path

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/troubleshooting/fetch-push.mdx

Locate the GitButler settings file on Linux.

```bash
```bash ~/.config/gitbutler/settings.json ```
```

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

### Create New Branch and Reset Hard

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/llms-full.txt

Use these commands to create a new branch and reset it to the state of 'origin/master' to begin reconstructing a branch.

```bash
git switch -c reconstruction
git reset --hard origin/master
```

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

### Edit Commit Message

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/public/llms-full.txt

Open your default editor to modify a commit message. The editor will display the current message and comments explaining how to proceed. Any lines starting with '#' are ignored, and an empty message will abort the change.

```cli
but reword <sha>
```

```text
add user changes

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Changes in this commit:
#       modified:   app/models/user.rb
#       modified:   config/routes.rb
#
~
~
~
~

```

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

### Open Draft Pull Requests by Default

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/ai-agents/tuning-agent-behavior.mdx

Configure the agent to create pull requests as drafts by default, even when allowed to publish. This ensures a review process starts before the work is considered ready for merging.

```markdown
- When I ask you to open a pull request, create it as a draft with GitButler
  unless I say it is ready for review.
```

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

### Inspect Branch with PR Info, File Diffs, and AI Summary

Source: https://github.com/gitbutlerapp/gitbutler-docs/blob/main/content/docs/cli-guides/cli-tutorial/inspecting.mdx

Combine options with `but branch show` to view PR information, files modified in each commit, and an AI-generated summary of changes.

```cli
but branch show sc-branch-28 --ai -r -f
```