repository·master·Indexed 10 days ago
https://github.com/gitbutlerapp/gitbutlerA modern Git-based version control system featuring a GUI and a CLI (`but`). It is designed to support advanced workflows including stacked branches, parallel development, and AI-powered agentic automation.
GitButler is a desktop Git client designed for managing Git branches with advanced workflows. Key features include:
GitButler is a modern Git-based version control interface designed for both humans and AI agents. It provides a GUI (built with Tauri, Svelte, and TypeScript) and a CLI named but (built with Rust). It is designed to work as a drop-in replacement for standard Git interfaces in any existing Git repository.
Key capabilities include:
rebase -i.The @gitbutler/lite package is an Electron application scaffold using React (Vite) and TanStack Router. The application is split into two distinct process boundaries to maintain security and runtime separation:
ui/ (Renderer Process): Contains the frontend React code. It communicates with the main process via a secure IPC bridge and never accesses native bindings or Node.js APIs directly.electron/ (Main/Preload Process): Contains the privileged Electron code, including the main process and the preload script. This layer handles Node.js operations, native Rust bindings via @gitbutler/but-sdk, and manages the IPC contract.Security is enforced using contextIsolation: true and nodeIntegration: false, with all privileged capabilities exposed to the UI through a contextBridge in the preload script.
The but-hunk-dependency crate calculates the dependency graph between commits and uncommitted changes.
main and to each other.To achieve high performance, the crate maintains an ordered list of line ranges (hunk ranges) that track which commit 'owns' specific lines in a file. This data structure acts similarly to a git-blame for a file, representing the file as a one-dimensional vector of line changes.
RefInfo behavior changes. In these modes, the system provides unmanaged RefInfo that may behave differently than the standard workspace-managed projection, specifically regarding how segments and legacy stacks are presented.To avoid the high-severity risk of accidentally committing an entire file because selected hunks were stale, implement the following logic in uncommittedService.svelte.ts:
Instead of pushing hunkHeaders: [] (which the backend interprets as a command to commit the whole file), track the stale-skip count per path. If every selected hunk in a file is stale, drop that file from the commit process and notify the user via an info toast.
The application uses a contract-first IPC model to ensure end-to-end type safety between the Electron main process and the React renderer:
electron/src/ipc.ts.window.lite using Electron's contextBridge.ui/src/electron.d.ts) and uses type-only imports from the Electron subtree (often via the #electron/* path alias).This pattern ensures that the renderer can call window.lite.* methods with full TypeScript support without having runtime access to the underlying IPC or native modules.
The SDK provides two flavors depending on how you want WorkspaceState to project data. You must import the correct entry point to ensure your TypeScript types match the underlying native binary:
@gitbutler/but-sdk (linear flavor): Built without the graph-workspace feature. WorkspaceState uses the legacy RefInfo-based headInfo projection.@gitbutler/but-sdk/graph (graph flavor): Built with the --features graph-workspace feature. WorkspaceState uses the graphWorkspace (DetailedGraphWorkspace) projection.Note: If you are using the desktop app, you must keep your import flavor in lockstep with the gitbutler-tauri backend's graph-workspace feature setting.
import { ... } from '@gitbutler/but-sdk'; // Linear flavor
import { ... } from '@gitbutler/but-sdk/graph'; // Graph flavorThe architecture distinguishes between deduplicating the resource (the Rust watcher) and the listeners (the subscriptions):
WatcherManager in Node ensures there is at most one active Rust watcher per project ID. If multiple requests to subscribe to the same project occur concurrently, the system reuses the existing watcher state or the pending promise from pendingProjectWatchers to avoid spawning duplicate Rust processes.
While the Rust watcher is shared, subscriptions are not deduplicated. Every call to subscribeToProject(...) creates:
subscriptionId.eventChannel.watcherSubscriptions.This allows multiple consumers (e.g., different windows or independent listeners in one window) to coexist for the same project, each with its own channel lifecycle. Note: The UI is expected to create only one subscription per project.
The but-server uses a security middleware (localhost_only_middleware) to prevent unauthorized remote access.
The middleware performs the following checks on every connection:
127.0.0.1 for IPv4 or ::1 for IPv6).HTTP 403 Forbidden error.In addition to IP checks, the server validates the Origin header. It only allows origins that use the http scheme and have localhost as the host (e.g., http://localhost or http://localhost:3000).
If a connection is rejected by the security middleware, it is logged with the following warning format:
Rejected non-localhost connection from: <ip_address>
Unlike traditional Git which uses serial branching (one branch at a time via git checkout), GitButler uses a Parallel Stacks model.
In a GitButler workspace, you work on multiple branches simultaneously. All applied branches are merged into your working directory at once, meaning you don't need to switch contexts to work on different tasks.
Key concepts:
gitbutler/workspace branch: A merge commit containing all applied stacks. Do not interact with this branch directly; use but commands instead.but apply or but unapply to toggle their state.