### Start Development Server

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/packages/shared/README.md

Run this command after installing dependencies to start the development server. The -- --open flag will automatically open the app in your browser.

```bash
npm run dev
```

```bash
npm run dev -- --open
```

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

### Install GitButler CLI

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/apps/web/src/routes/install.sh/README.md

Users can install the GitButler CLI by piping the installation script to bash.

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

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

### Install, Use, and Verify Node.js Version

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Commands to install the correct Node.js version using NVM, switch to it, and verify the installed version. Ensures compatibility with the project's requirements.

```bash
nvm install
nvm use
node -v
```

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

### Install Rust

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Installs Rust using the official rustup script. This is a prerequisite for building the Rust backend.

```bash
$ cd gitbutler-repo
$ curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
```

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

### Install and Run Skill Integration Tests

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/README.md

Navigate to the skill's evaluation directory, install dependencies, approve builds, and run the integration tests. Optionally, run the same harness with Codex.

```bash
cd crates/but/skill/eval
pnpm install --ignore-workspace
pnpm approve-builds --ignore-workspace
pnpm run eval
# Optional: run the same harness with Codex instead of Claude
pnpm run eval:codex
```

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

### Install GitButler via Direct Invocation

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but-installer/README.md

Alternative method for installing GitButler by directly invoking the installer binary. Allows installation of the latest stable, nightly, or specific versions.

```bash
but-installer                  # Install latest stable
```

```bash
but-installer nightly          # Install nightly
```

```bash
but-installer 0.18.7           # Install specific version
```

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

### Install Node.js via Vercel Script

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Installs the latest version of Node.js using a provided installation script from Vercel.

```bash
$ curl https://install-node.vercel.app/latest > install_node.sh
$ sudo ./install_node.sh
```

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

### Example `but status` command

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/RESEARCH.md

This example demonstrates a typical command used for checking the status of changes, often invoked when a user asks about modified files. It includes the `--format json` flag for structured output.

```bash
but status --format json
```

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

### Install GitButler via Bootstrap Script

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but-installer/README.md

Recommended method for installing GitButler using the provided bootstrap script. Supports installing the latest stable version, nightly builds, or specific version numbers.

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

```bash
curl -sSL https://gitbutler.com/install.sh | sh -s nightly
```

```bash
curl -sSL https://gitbutler.com/install.sh | sh -s 0.18.7
```

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

### Install GitButler CLI Skill

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/README.md

Use this command to install the GitButler CLI skill. It will prompt for scope and format. Ensure GitButler CLI is installed and an AI assistant with skills support is available.

```bash
but skill install    # Prompts for scope and format
```

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

### Install Playwright Browsers

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/e2e/README.md

Installs the necessary Playwright browsers for running Playwright tests. This command should be run from the 'e2e' directory.

```bash
cd e2e
pnpm install-playwright
```

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

### Build and Test but-installer

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but-installer/README.md

Commands to build the installer in release mode and run its tests using Cargo.

```bash
cargo build --release -p but-installer
```

```bash
cargo test -p but-installer
```

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

### Playwright Test Example

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/e2e/README.md

Example of a Playwright test file. It demonstrates setting up a GitButler instance, running setup scripts, navigating the UI, and making assertions. Ensure to use `data-testid` attributes for reliable element interaction.

```typescript
import { startGitButler, type GitButler } from "../src/setup.ts";
import { clickByTestId, waitForTestId } from "../src/util.ts";
import { expect, test } from "@playwright/test";

let gitbutler: GitButler;

test.afterEach(async () => {
	await gitbutler?.destroy();
});

test("should do something amazing", async ({ page, context }, testInfo) => {
	const workdir = testInfo.outputPath("workdir");
	const configdir = testInfo.outputPath("config");
	gitbutler = await startGitButler(workdir, configdir, context);

	// Setup test data
	await gitbutler.runScript("your-setup-script.sh");

	await page.goto("/");

	// Your test logic here
	await waitForTestId(page, "your-element");
	await clickByTestId(page, "your-button");

	// Assertions
	expect(await page.locator('[data-testid="result"]').textContent()).toBe("expected");
});
```

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

### FileList Minimal Consumer Example

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/apps/desktop/src/components/README.md

This snippet shows the minimal composition of FileListProvider and FileListItems, used when only the file list items are needed.

```svelte
<FileListProvider {changes} {selectionId}>
	<FileListItems {projectId} mode="list" onselect={(_, i) => (selectedIndex = i)} />
</FileListProvider>
```

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

### Get npm Prefix on Windows

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Check the npm installation prefix on Windows. This is useful for troubleshooting `pnpm` installation issues.

```bash
npm config get prefix
```

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

### Run FE Dev Server

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/apps/desktop/README.md

Start the frontend development server concurrently with the but-server. This command packages local dependencies, builds the web target, and serves the application from http://localhost:1420, connecting to the but-server at http://localhost:6978.

```bash
pnpm dev:desktop-http
```

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

### Run Web Unit Tests

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/apps/web/src/routes/install.sh/README.md

Execute unit tests for the web application, including tests for the install script.

```bash
cd apps/web
pnpm test
```

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

### Install App Dependencies

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Installs the project's JavaScript dependencies using pnpm. This command may prompt for confirmation to use pnpm via Corepack.

```bash
$ pnpm install
```

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

### Install svelte-comment-injector

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/packages/svelte-comment-injector/README.md

Install the package as a development dependency using npm.

```bash
npm install @gitbutler/svelte-comment-injector --save-dev
```

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

### Run App in Development Mode

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Starts the Gitbutler desktop application in development mode.

```bash
$ pnpm dev:desktop
```

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

### Blackbox Test Example

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/e2e/README.md

Example of a WebdriverIO (Blackbox) test file. It shows how to set up test repositories using bash scripts and interact with the application's elements. Use `data-testid` attributes for element selection and ensure proper cleanup.

```typescript
import { spawnAndLog, findAndClick, setElementValue } from "../utils.js";

describe("Your Feature", () => {
	before(() => {
		// Setup test repositories
		spawnAndLog("bash", ["-c", "./blackbox/scripts/your-setup-script.sh ../target/debug/but"]);
	});

	it("should perform an action", async () => {
		await findAndClick('button[data-testid="your-button"]');

		const element = $("input[data-testid="your-input"])";
		await setElementValue(await element.getElement(), "test value");

		// Add assertions
		const result = await $("div[data-testid="result"])").getElement();
		await expect(result).toExist();
	});
});
```

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

### Incoming Hunk Modification Example

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but-hunk-dependency/README.md

Demonstrates how an incoming hunk, with specific old and new start/line counts, modifies the existing hunk range list. This example shows a hunk splitting an existing range.

```rust
old_start: 3
old_lines: 1
new_start: 3
new_lines: 1
```

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

### Commit Below a Branch (Example: Top)

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/but-cli-revamp/commit.md

Demonstrates creating a new commit below the 'top' branch.

```bash
but commit --below top
```

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

### Basic svelte.config.js Setup

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/packages/svelte-comment-injector/README.md

Integrate the svelte-comment-injector preprocessor into your Svelte configuration file.

```javascript
// svelte.config.js
import svelteInjectComment from "@gitbutler/svelte-comment-injector";

export default {
	preprocess: [svelteInjectComment()],
	// ...rest of your config
};
```

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

### Run Vite + Electron Development Server

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/apps/lite/README.md

Use this script to start the Vite development server with Electron for local development. It filters the command to only apply to the '@gitbutler/lite' package.

```bash
pnpm --filter @gitbutler/lite dev
```

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

### Commit Above a Branch (Example: Top)

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/but-cli-revamp/commit.md

Demonstrates creating a new commit above the 'top' branch.

```bash
but commit --above top
```

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

### Handle CLI Install Cancellation

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/error-cleanup-checklist.md

Tags the CLI installation cancellation status with `Code::CliInstallCancelled` on the Rust side. The frontend then matches this code to display an info toast, providing a clearer user experience than matching on English strings.

```rust
pub enum Code { CliInstallCancelled, ... }

// ... in but-action/src/cli.rs ...
Context::new_static(Code::CliInstallCancelled, "CLI install cancelled")
```

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

### Run Web E2E Tests

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/apps/web/src/routes/install.sh/README.md

Execute end-to-end tests for the web application, specifically verifying the install script endpoint.

```bash
cd apps/web
pnpm test:e2e:web
```

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

### Example tsconfig.json paths

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/packages/no-relative-imports/README.md

Illustrates common 'paths' configurations in tsconfig.json that the rule supports. These include direct file mappings, glob mappings, and path mappings with globs.

```json
{
	"compilerOptions": {
		"paths": {
			"$lib": "./lib", // Without glob. IE pointing directly to a file
			"$lib/*": "./lib/*", // Both with glob, IE anything starting in ./lib/... results in $lib/...
			"$lib": "./lib/*" // Path with, IE anything starting in ./lib/... results in $lib
		}
	}
}
```

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

### FileList Consumer with Conflict Display

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/apps/desktop/src/components/README.md

This example demonstrates composing FileListProvider with both FileListConflicts and FileListItems for displaying optional conflict information alongside the file list.

```svelte
<FileListProvider {changes} {selectionId} {allowUnselect}>
	<FileListConflicts {projectId} {conflictEntries} {ancestorMostConflictedCommitId} />
	<FileListItems {projectId} mode={listMode} {conflictEntries} {onselect} />
</FileListProvider>
```

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

### Example `but branch new` command

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/RESEARCH.md

This command is used to create a new branch, as demonstrated in the test case for creating a branch for specific changes.

```bash
but branch new auth
```

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

### GitButler CLI Command Examples with IDs

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/references/concepts.md

Demonstrates how to use the short CLI IDs as arguments for common GitButler commands like committing, amending, and squashing commits.

```bash
but commit <branch-id> -m "message"      # Commit to branch
but amend <commit-id> --changes <file-or-hunk-id>,<file-or-hunk-id>  # Amend file(s) or hunk(s) into commit
but rub <commit-id> <commit-id>          # Squash commits
```

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

### Install Linux Tauri Dependencies

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Installs necessary system dependencies for Tauri on Debian-based Linux distributions.

```bash
$ sudo apt update
$ sudo apt install libwebkit2gtk-4.1-dev \
  build-essential \
  curl \
  wget \
  file \
  libxdo-dev \
  libssl-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  cmake
```

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

### Commit Below a Branch (Example: Bottom)

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/but-cli-revamp/commit.md

Demonstrates creating a new commit below the 'bottom' branch.

```bash
but commit --below bottom
```

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

### Main Process Model in Electron

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/packages/but-sdk/README.md

Import and use native bindings directly in the Electron main process. This example shows how to expose a typed IPC API.

```typescript
import { listProjectsStatelessNapi } from '@gitbutler/but-sdk';

export function listProjects() {
	return listProjectsStatelessNapi();
}
```

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

### Run but-server

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/apps/desktop/README.md

Execute this command to start the but-server, which provides the API surface for the Rust backend. The server defaults to port 6978.

```bash
cargo run -p but-server
```

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

### Example `but push` command

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/RESEARCH.md

This is the expected command for pushing changes, contrasting with the native `git push` command. It's used when a user requests to push their work.

```bash
but push
```

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

### Commit Below a Branch (Example: Middle)

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/but-cli-revamp/commit.md

Demonstrates creating a new commit below the 'middle' branch.

```bash
but commit --below middle
```

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

### Get Detailed Help for a Specific GitButler CLI Command

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/references/reference.md

To understand the usage and options of a particular subcommand, append --help to the subcommand name. This provides detailed information for that specific command.

```bash
but <subcommand> --help
```

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

### Set npm Prefix on Windows

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Configure the npm prefix directory in PowerShell. This ensures `pnpm` installs packages in a writable location.

```powershell
mkdir -p $APPDATA\npm
npm config set prefix $env:APPDATA\npm
```

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

### Example `but squash` command

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/RESEARCH.md

This command is used for squashing commits, as shown in the test case for squashing the last few commits. It's an alternative to `git rebase -i`.

```bash
but squash
```

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

### Build Production Showcase App

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/packages/shared/README.md

This command builds a production-ready version of your showcase application.

```bash
npm run build
```

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

### HunkRange Structure Example

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but-hunk-dependency/README.md

Illustrates the structure of a HunkRange, including its start line and the number of lines it encompasses. This is a fundamental data structure used in tracking changes.

```rust
HunkRange {
    start: 1
    lines: 10
  }
```

```rust
HunkRange {
    start: 11
    lines: 1
  }
```

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

### Build and Run CLI

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Builds the 'but' CLI using Cargo and demonstrates how to run it with help and for a specific repository.

```bash
$ cargo build -p but
$ cargo run -p but -- --help
$ cargo run -p but -- -C /path/to/git-repo status
```

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

### Prepare Git Askpass Helper

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/apps/lite/README.md

Builds the 'gitbutler-git-askpass' executable and copies it to the 'resources/bin' directory. This helper is used for Git credential prompts within Lite.

```bash
pnpm --filter @gitbutler/lite prepare-askpass
```

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

### Build Project Bins

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Builds the Rust project, ensuring supplementary binaries like 'gitbutler-git-askpass' are created in the default 'target' folder.

```bash
$ cargo build
```

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

### Build Svelte Library

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/packages/shared/README.md

Execute this command to build your Svelte library for distribution.

```bash
npm run package
```

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

### Example HTML Comment Structure

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/packages/svelte-comment-injector/README.md

This is an example of the HTML comment structure that the preprocessor injects into Svelte components.

```html
<!-- Begin MyComponent.svelte -->
<div class="my-component">
	<!-- Component content -->
</div>
<!-- End MyComponent.svelte -->
```

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

### Manage GitButler Skills

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/references/reference.md

Manage installed GitButler skill files. Supports checking for available skills, updating existing ones, and automatically detecting and installing skills.

```bash
but skill check
```

```bash
but skill check --update
```

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

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

### Connect to Tokio Console (Production)

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Connect to the Tokio console for runtime tracing information in a production environment. Ensure you use the correct port for the production Tokio runtime.

```bash
$ tokio-console http://127.0.0.1:6667
```

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

### Check for CLI and App Updates

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/references/reference.md

Manage updates for the GitButler CLI and desktop application. Supports checking for updates, installing the latest release, or installing specific versions including nightly builds.

```bash
but update check
```

```bash
but update install
```

```bash
but update install [nightly|release|0.18.7]
```

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

### Bundle Local Application with Nightly Settings

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/apps/lite/README.md

Builds and packages the application locally using Electron Builder with production-like settings. This build is slower due to release optimizations but is otherwise similar to 'bundle-local'.

```bash
pnpm --filter @gitbutler/lite bundle-local-nightly
```

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

### Get GitButler Status Overview

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/references/reference.md

Use `but status` to get a compact overview of branch, stack, commit IDs, and subjects. For more detailed information, use the `--verbose` flag. To see upstream relationships, use `--upstream`.

```bash
but status              # Compact overview with branch, stack, commit IDs, and commit subjects
```

```bash
but status -fv          # File-centric view with full commit details and file IDs
```

```bash
but status --verbose    # Detailed information
```

```bash
but status --upstream   # Show upstream relationship
```

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

### Publish to npm

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/packages/shared/README.md

After configuring your package.json, use this command to publish your library to npm.

```bash
npm publish
```

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

### Enable Performance and Debug Logging for Release Build

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Execute the development build with performance logging and debug log level, specifically for a release build. This provides more realistic performance data by simulating a production-like environment.

```bash
GITBUTLER_PERFORMANCE_LOG=1 LOG_LEVEL=debug pnpm tauri dev --release
```

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

### Connect to Tokio Console (Nightly)

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Connect to the Tokio console for runtime tracing information in the nightly build environment. This requires specifying the correct address for the Tokio runtime.

```bash
$ tokio-console http://127.0.0.1:6668
```

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

### Commit Below a Commit (Example: b440dea)

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/but-cli-revamp/commit.md

Creates a new commit directly below the commit with hash 'b440dea'.

```bash
but commit --below b440dea
```

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

### Commit Above a Commit (Example: b440dea)

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/but-cli-revamp/commit.md

Creates a new commit directly above the commit with hash 'b440dea'.

```bash
but commit --above b440dea
```

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

### Generate MDX Documentation

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but-clap/README.md

Run this command to generate MDX files for each CLI command in the `cli-docs` directory. The `raw-clap-docs` feature is required for this process.

```bash
cargo run -p but-clap --features raw-clap-docs
```

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

### Produce Nightly Release Build for Windows

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Command to generate a nightly release build for Windows, including specific features and configuration.

```bash
pnpm tauri build --features windows,devtools --config  crates/gitbutler-tauri/tauri.conf.nightly.json
```

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

### Commit to a New Branch with Custom Name

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/but-cli-revamp/commit.md

Creates a new branch with a user-specified name and commits to it, effectively starting a new stack.

```bash
but commit -b new-branch
```

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

### Build Renderer and Electron Code

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/apps/lite/README.md

This script builds the renderer process code and the Electron main process code for the '@gitbutler/lite' package. This is typically used for production builds.

```bash
pnpm --filter @gitbutler/lite build
```

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

### Commit to a New Branch with Canned Name

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/but-cli-revamp/commit.md

Creates a new branch with a default name and commits to it. This is useful for starting a new line of work.

```bash
but commit -b
```

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

### Build but-sdk Native Addon

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but-napi/README.md

Build the native addon, JS loader, and type declarations for but-sdk. This command is the source of truth for local development.

```bash
pnpm --filter @gitbutler/but-sdk build
```

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

### Contributor Flow for Changes

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/packages/but-sdk/README.md

Recommended workflow after changing bindings or types includes building, checking, and optionally testing types.

```bash
pnpm --filter @gitbutler/but-sdk build
pnpm --filter @gitbutler/but-sdk check
# optional
pnpm --filter @gitbutler/but-sdk testTypes
```

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

### Renderer Consumes IPC API

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/packages/but-sdk/README.md

The renderer process can consume the typed IPC API exposed by the main process. This example demonstrates calling the listProjects function.

```typescript
const projects = await window.lite.listProjects();
```

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

### promptfoo Configuration for Claude Agent SDK (YAML)

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/RESEARCH.md

This YAML configuration sets up promptfoo to use the Claude Agent SDK provider. It specifies model, working directory, allowed tools, permission mode, and budget, along with test assertions for agent behavior.

```yaml
providers:
  - id: anthropic:claude-agent-sdk
    config:
      model: claude-sonnet-4-5-20250929
      working_dir: ./test-repo
      append_allowed_tools: ['Bash', 'Read', 'Edit']
      permission_mode: acceptEdits
      max_turns: 10
      max_budget_usd: 0.25
      ask_user_question:
        behavior: first_option  # Auto-answer prompts

tests:
  - vars:
      prompt: "Commit my auth changes"
    assert:
      - type: contains
        value: "but commit"
      - type: not-contains
        value: "git commit"
      - type: cost
        threshold: 0.25
      - type: javascript
        value: |
          const text = String(output).toLowerCase();
          return text.includes('--format json') && text.includes('--status-after');

```

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

### Reinstall GitButler CLI Skill

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/README.md

Re-run the install command to overwrite existing skill files with the latest version. This can be used as an alternative to the --detect flag for updating.

```bash
but skill install
```

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

### Show Session Details

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but-agentlog/skill/SKILL.md

When `skim` output is thin, ambiguous, or missing context, use `show <session-key> --limit 20` to retrieve detailed session information. Summarize previews from this output.

```sh
show <session-key> --limit 20
```

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

### Build GitButler in Production Mode

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Use this command to create a production build of the app with specific features and configuration.

```bash
pnpm tauri build --features devtools,builtin-but,disable-auto-updates --config crates/gitbutler-tauri/tauri.conf.nightly-local.json
```

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

### Fetch and Rebase Applied Branches

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/references/reference.md

Updates your local branches with the latest changes from the target branch (usually `main`). This is the recommended way to 'get latest' in a GitButler workspace.

```bash
but pull
```

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

### Create a Svelte Project

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/packages/shared/README.md

Use npm to create a new Svelte project. You can create it in the current directory or specify a directory name.

```bash
npm create svelte@latest
```

```bash
npm create svelte@latest my-app
```

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

### Split an Existing Commit

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/SKILL.md

Replace an existing commit with multiple smaller commits. Use `but uncommit --diff` to get IDs for the new commits from the exposed changes.

```bash
but status -fv
```

```bash
but uncommit <source-commit-id> --diff
```

```bash
but commit batch <branch> [--before <target>|--after <target>] -m "<message 1>" --changes <id>,<id> -m "<message 2>" --changes <id>,<id>
```

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

### Connect to Tokio Console (Development)

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Connect to the Tokio console for runtime tracing information in a development environment. This helps in monitoring and debugging asynchronous tasks managed by Tokio.

```bash
$ tokio-console
```

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

### Complete Feature Development Workflow with GitButler

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/references/examples.md

A comprehensive workflow for developing a feature from start to finish, including branching, committing, absorbing changes, squashing, and creating pull requests.

```bash
# 1. Update to latest
but pull

# 2. Create branch for feature
but branch new user-dashboard

# 3. Make initial changes
# (create dashboard.js, add routes)

# 4. Check status and gather file IDs
but status -fv

# 5. First commit
but commit bu -m "Add dashboard route and basic layout" --changes <file-ids>

# 6. Continue iterating
# (add widgets, styling)
but commit bu -m "Add dashboard widgets" --changes <file-ids>
but commit bu -m "Style dashboard components" --changes <file-ids>

# 7. Make small fix
# (fix typo in widget)
but absorb a1    # Absorb specific file into appropriate commit

# 8. Clean up if needed
but squash bu    # Combine all commits (optional)

# 9. Create pull request (auto-pushes the branch)
but pr new bu

# Output:
# Created PR #123: https://github.com/org/repo/pull/123

# 10. After PR is merged, update
but pull
```

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

### Update GitButler CLI Skill

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/README.md

Run this command with the --detect flag to automatically find and update your existing GitButler CLI skill installation. This is useful for applying the latest version.

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

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

### Build Local Workspace Dependencies

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/apps/desktop/README.md

If running the desktop package's `dev` script directly, ensure local package outputs exist first by running this command.

```bash
pnpm turbo run package --filter=...@gitbutler/desktop
```

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

### Commit Selected Files or Hunks

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/SKILL.md

Commit specific files or hunks of changes. Use `but diff` first to get file and hunk IDs. For new branches, use the `-c` flag.

```bash
but diff
```

```bash
but commit <branch> -c -m "<msg>" --changes <id1>,<id2>
```

```bash
but commit <branch> -m "<msg>" --changes <id1>,<id2>
```

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

### CLI IDs for GitButler Objects

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/references/concepts.md

Shows examples of short, human-readable CLI IDs used in GitButler for commits, branches, files, hunks, and stacks, which are unique within a session and used as arguments for commands.

```text
Commits:    1b, 8f, c2     (short hex prefixes of the SHA, long enough to be unique)
Branches:   fe, bu, ui     (unique 2–3 char substring of the branch name, e.g. "fe" from "feature-x";
                             falls back to auto-generated ID if no unique substring exists)
Files:      g0, h0, i0     (auto-generated, 2–3 chars)
Hunks:      j0, k1, l2     (auto-generated, 2–3 chars)
Stacks:     m0, n0          (auto-generated, 2–3 chars)
```

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

### Enable Performance and Debug Logging

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/DEVELOPMENT.md

Run the development build with performance logging enabled and debug log level. This is useful for identifying performance bottlenecks and detailed application behavior during development.

```bash
GITBUTLER_PERFORMANCE_LOG=1 LOG_LEVEL=debug pnpm tauri dev
```

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

### Skim Agent Log History

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but-agentlog/skill/SKILL.md

Use `skim` to get a table-of-contents view of all related sessions and turns, abbreviated and shown chronologically. Run without arguments to discover the current branch's agent work.

```sh
but agentlog skim
```

```sh
but agentlog skim branch <branch-name-or-ref>
```

```sh
but agentlog skim review <review-id-or-pull-request-key>
```

```sh
but agentlog skim change <change-id-or-key>
```

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

### Show Info Toast for Unsupported Paths

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/error-cleanup-checklist.md

Uses `showToast({style: "info"})` to inform users about unsupported path types, such as those encountered in WSL2 or UNC paths. This provides guidance without presenting it as a critical error.

```typescript
showToast({ message: "Unsupported path", style: "info" });
```

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

### Mark Review as Ready

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/references/reference.md

Sets the status of a review to 'ready'. This indicates that the review is complete and ready for further action or merging.

```bash
but pr set-ready <selector>
```

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

### Start Independent Parallel Workflows with GitButler CLI

Source: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/but/skill/references/examples.md

Use this workflow to create and manage two independent features concurrently. It covers checking status, creating parallel branches, committing specific files, and creating pull requests. Always use actual IDs from `but status -fv`.

```bash
# 1. Check current state
but status -fv

# 2. Create two independent (parallel) branches
but branch new api-endpoint
but branch new ui-styling

# 3. Make changes to multiple files
# (edit api/users.js and components/Button.svelte)

# 4. Check what's uncommitted
but status -fv

# 5. Commit specific files directly using --changes (recommended for agents)
# Use CLI ID values from but status -fv output (e.g., branch IDs and file IDs)
# For multiple IDs, use one comma-separated argument or repeat --changes.
but commit <api-branch-id> -m "Add user details endpoint" --changes <api-file-id>
but commit <ui-branch-id> -m "Update button hover styles" --changes <ui-file-id>

# Follow-up fix that belongs in a commit you just made? Amend it in.
# Each mutation returns updated workspace state — take fresh IDs from it before the next command.
# but amend <api-commit-id> --changes <api-fix-file-id>,<api-fix-hunk-id>

# 6. Create pull requests (auto-pushes the branches)
but pr new <api-branch-id>
but pr new <ui-branch-id>
```