This document covers the purpose, major components, and top-level architectural patterns of the GitButler repository. It is intended as an entry point for developers who are new to the codebase. For deeper treatment of individual subsystems, see the linked child pages throughout.
GitButler is a Git client that extends standard Git with a concept of virtual branches (often organized into stacks). Instead of requiring developers to switch branches before starting new work, GitButler lets multiple branches exist simultaneously in a single working directory. It tracks which uncommitted file changes (at the hunk level) belong to which branch, applies them to a special gitbutler/workspace reference, and orchestrates complex Git operations like rebasing and pushing.
Core functionality and data structures:
Stack (crates/gitbutler-stack/Cargo.toml) and StackBranch (crates/gitbutler-branch/src/branch.rs13) types.but-hunk-assignment crate (Cargo.toml38).gitbutler/workspace integration branch via but-workspace (Cargo.toml42).but-graph (Cargo.toml16).Sources: Cargo.toml15-43 crates/but/Cargo.toml78-106 README.md57-82
The project ships as several distinct applications and tools:
| Deliverable | Technology | Binary/Entry Point | Path |
|---|---|---|---|
| Desktop GUI application | Tauri v2 + SvelteKit | gitbutler-tauri binary | apps/desktop, crates/gitbutler-tauri |
| Web application | SvelteKit | N/A (static build) | apps/web |
| HTTP/WebSocket server | Axum (Rust) | but-server binary | crates/but-server |
| CLI tool | Clap (Rust) | but binary | crates/but |
| Node.js SDK | napi-rs | but-napi cdylib | crates/but-napi |
Sources: crates/gitbutler-tauri/Cargo.toml19-22 crates/but/Cargo.toml20-22 Cargo.toml110-127 package.json11-17
The repository is a monorepo combining a pnpm workspace for TypeScript/JavaScript packages and a Cargo workspace for Rust crates. The monorepo uses turbo for task orchestration (package.json80).
Monorepo top-level layout:
apps/
desktop/ # Tauri desktop app (SvelteKit frontend)
web/ # Web app (SvelteKit)
lite/ # Electron + React lite client
packages/
ui/ # @gitbutler/ui – Svelte component library <FileRef file-url="https://github.com/gitbutlerapp/gitbutler/blob/e2c7f0c8/packages/ui/package.json#L2-L2" min=2 file-path="packages/ui/package.json">Hii</FileRef>
shared/ # @gitbutler/shared – Shared frontend logic
core/ # @gitbutler/core – Generated TypeScript types
but-sdk/ # @gitbutler/but-sdk – napi-rs Node.js bindings
crates/
but-api/ # Unified API layer used by CLI, GUI, etc <FileRef file-url="https://github.com/gitbutlerapp/gitbutler/blob/e2c7f0c8/Cargo.toml#L100-L100" min=100 file-path="Cargo.toml">Hii</FileRef>
but-server/ # HTTP/WebSocket server (Axum-based)
but-*/ # Modern crates (exemplary quality tier)
gitbutler-*/ # Legacy crates (being incrementally migrated)
Sources: Cargo.toml1-137 package.json11-31 DEVELOPMENT.md39-53
The Cargo workspace documents an explicit migration strategy from gitbutler-* legacy crates to but-* modern crates. Crates are classified by quality tier to guide contributors:
Quality tier table:
| Tier | Crates | Documentation | Tests | Legacy Dependencies | Goal |
|---|---|---|---|---|---|
| Exemplary 🏆 | but-core, but-graph, but-ctx, but-db, but-error | #![deny(missing_docs)] | Exhaustive | None | Production-ready |
| Needs Work 👷 | but-rebase, but-workspace, but-claude, but-action, but-llm | Partial | Core tests | Some legacy deps | Remove legacy |
| Soon Obsolete | but-utils, but-oxidize | Minimal | Minimal | N/A | Delete when legacy removed |
| API Layer | but-api, but-api-macros | Moderate | Partial | Yes (via legacy feature) | Port legacy functions |
| Binaries | but, but-server, gitbutler-tauri | Varies | Varies | Some | Functional |
| Legacy | gitbutler-* (e.g., gitbutler-stack, gitbutler-repo) | Legacy patterns | Legacy patterns | N/A | Port to but-* |
Sources: Cargo.toml1-137 crates/but/Cargo.toml25-51 crates/but-api/Cargo.toml1-103
Component map with code entity names:
Sources: Cargo.toml1-137 crates/gitbutler-tauri/Cargo.toml27-43 crates/but/Cargo.toml65-106 apps/desktop/package.json22-42
but-api Central Interfacecrates/but-api serves as a unified API layer that all clients consume. It provides a single source of truth for the API surface, with platform-specific bindings generated via feature flags.
Feature flag matrix:
| Feature flag | Effect | Used by |
|---|---|---|
tauri | Generates #[tauri::command] wrappers | gitbutler-tauri |
napi | Generates #[napi] Node.js SDK bindings | but-napi |
legacy | Enables gitbutler-* crate dependencies | All current clients |
path-bytes | Adds byte-based path handling for CLI | but, gitbutler-tauri |
Sources: crates/but-api/Cargo.toml1-100 crates/gitbutler-tauri/Cargo.toml37 crates/but/Cargo.toml79
Request lifecycle through the stack (example: merge_commits):
Sources: crates/gitbutler-repo/src/rebase.rs83-160 crates/gitbutler-tauri/Cargo.toml68-76 apps/desktop/package.json34-42
The frontend uses Redux Toolkit Query (RTK Query) for state management and backend communication (apps/desktop/package.json31). The backend uses gix (gitoxide) for high-performance tree operations and git2 (libgit2) for legacy compatibility (crates/gitbutler-tauri/Cargo.toml68-74).
GitButler uses a dual-backend strategy for Git operations:
| Library | Primary use cases |
|---|---|
git2 (libgit2) | Legacy operations: checkout, index manipulation, and references. |
gix (gitoxide) | Modern operations: high-performance diffs, merges, and tree traversal (crates/gitbutler-tauri/Cargo.toml68). |
but-oxidize | Conversion layer between git2::Oid and gix::ObjectId (Cargo.toml92). |
gitbutler-git | Subprocess execution for fetch, push, and clone using the git binary, including the askpass credential system (crates/gitbutler-tauri/Cargo.toml47). |
Sources: crates/gitbutler-repo/src/rebase.rs103-111 Cargo.toml92 crates/gitbutler-tauri/Cargo.toml68-74
| Topic | Page |
|---|---|
| Domain concepts (stacks, hunks, workspace) | Core Concepts |
| Full architecture with data flow diagrams | System Architecture |
| All Rust crates in detail | Backend Architecture |
| SvelteKit frontend structure | Frontend Architecture |
| CLI tool | Command-Line Interface |
| AI integration | AI Integration |
| Developer setup | Developer Guide |