GitButler: a Git client built around stacked and parallel branches

The problem GitButler takes on: branch switching as the unit of work

Vanilla Git assumes one working tree belongs to one branch at a time. If you are midway through a feature and a hotfix lands, you either stash, commit half-finished work, or create a second checkout. GitButler's answer is to stop treating the working directory as belonging to a branch. The README describes parallel branches as a way to "organize work on multiple branches simultaneously, rather than constantly switching branches," and stacked branches as branches created on top of other branches with automatic restacking when you amend or edit a commit in the middle of the stack.

The target user is not someone learning Git. It is someone who already knows rebase, cherry-pick and interactive rebase, and finds them expensive. The README frames the commit tools as a replacement: "Forget about `rebase -i`, you don't need it anymore." That is a claim about the interface, not about the object model. Underneath, the repository is still a Git repository, and the README says the tool "works instantly in any existing Git repo as a friendlier and more powerful drop-in Git user interface replacement."

How the Rust backend, Svelte frontend and `but` CLI share one engine

The README is explicit about the split: the desktop app is Tauri-based, the UI is Svelte with TypeScript, and the backend is Rust. The `but` CLI is described as "the same Rust backend engine with a Rust command line UI." That matters more than it sounds. A GUI-only client has to reimplement anything you want to script; here the same engine is exposed as a binary, so a hook or an agent can call `but` instead of driving a window.

The Cargo workspace shows how the engine is carved up. The workspace manifest groups crates by maturity, with a self-aware comment that the classification "isn't truly objective." The top group is labelled exemplary and includes `crates/but-core` (core types), `crates/but-graph` ("classification and analysis of commit-graphs"), `crates/but-ctx` (cache and database connection reuse), `crates/but-db` (SQLite abstractions with transaction and synchronization support), `crates/but-error` (error codes and JSON errors for frontends), `crates/but-testsupport`, `crates/but-feedback`, `crates/but-askpass` ("Broker prompts from Git back to the application") and `crates/but-project-handle`. A second group is labelled "Needs work" and the header comment admits "Substantial legacy code or legacy dependencies" and "Partial or incomplete documentation." The existence of a `check-modern-but` target in the Makefile, which runs `cargo check -p but --all-targets --no-default-features`, tells you the project is actively trying to build a version of the CLI without that legacy layer.

Two details in that crate list are worth pausing on. `but-db` implies GitButler keeps its own SQLite state alongside the repository, which is how an undo timeline and virtual branch metadata can exist at all. `but-askpass` implies credentials and prompts are brokered back from Git into the application rather than handled in a terminal. Neither is unusual for a client, but both mean GitButler is not a thin wrapper: there is persistent local state that vanilla Git does not have.

Installing GitButler and making a first stacked branch with `but`

The README does not give install commands. It links to https://gitbutler.com/downloads for the desktop application, and the repository's DEVELOPMENT.md is the place it points contributors who want to compile the code. So the honest sequence is: download the app from the downloads page, or build the CLI from source. The repository requires Node `>=24` and pins `[email protected]` in package.json, and the Rust toolchain is pinned in `rust-toolchain.toml`.

To build the CLI from a checkout, the root package.json exposes a desktop dev script that compiles the two binaries first:

pnpm install
pnpm dev:desktop

That script runs `cargo build -p but && cargo build -p gitbutler-git` before launching the Tauri dev server, so a successful run leaves a `but` binary in the Cargo target directory. The same package.json also defines a web-target variant that points the frontend at a running backend on port 6978:

pnpm dev:desktop-http

with `VITE_BUTLER_PORT=6978` and `VITE_BUTLER_HOST=localhost` set by the script. That is useful if you want to run the UI in a browser against a local backend rather than inside Tauri.

Once `but` is on your PATH, the CLI tutorial linked from the README covers branching and committing, including the stacked and parallel branch sections. The README does not reproduce those commands, so treat the docs site as the reference for the exact subcommands rather than guessing at flags. What you should see, per the README's feature list, is that amending or editing a commit in a stack triggers an automatic restack, and that a rebase which would normally stop on a conflict instead completes with the commit marked conflicted for later resolution.

Where GitButler's model breaks down

The virtual branch model is the biggest departure and the biggest risk. Because the working directory is not tied to one branch, tools that assume it is will misread the repository. Anything that runs `git status`, `git stash`, or inspects `HEAD` from a script and expects a conventional answer is operating on a repository whose visible state is partly managed by GitButler's own metadata. The README does not document what a plain `git` command sees while GitButler holds virtual branches, and that silence is the thing to test before you put it in a pipeline.

The second limitation is the licence. The README's own summary is that you "can use it, view the source, contribute, etc. You just can't build a competitor with it. It also becomes MIT after 2 years." The repository's licence field is NOASSERTION, and the README links to fair.io and describes the terms as "MIT with an expiring non-compete clause." For an individual that is close to irrelevant. For a company that wants to embed the engine in a product, the non-compete is the whole question, and the two-year conversion means the terms differ by release date. The README does not state which releases have already converted.

Third, the workspace manifest itself flags legacy code and incomplete documentation in a substantial group of crates. That is a normal state for a fast-moving project, but it means the crate-level docs are not a reliable map of the system yet.

GitButler compared with `git worktree` and with Jujutsu

The most direct comparison is `git worktree`, which is what people reach for when they want to work on two branches at once. Worktrees solve it by giving each branch its own directory on disk. GitButler solves it by keeping one directory and letting multiple branches share it. The difference shows up in cost: worktrees multiply disk usage and require you to move between directories, while GitButler keeps everything in one place but requires the client to be running and aware of the repository. If your tooling is built around `git worktree` paths, GitButler is the wrong layer.

The second comparison is Jujutsu, which shares the goal of making history editing cheap but takes a different route: it replaces the commit model with its own, including a working-copy commit. GitButler instead keeps Git's commit graph and adds a layer above it, which is why the README can say it works in any existing repository as a drop-in interface. The trade-off is that GitButler's extra state lives in its own database, while Jujutsu's lives in its own repository format. If you want to stop using GitButler, the repository is still a Git repository; if you want to stop using a tool that changed the model, the exit is less trivial.

Against GUI clients such as GitHub Desktop or Fork, the difference is the branch model rather than the interface. Those tools show you the repository Git already has. GitButler changes what the working directory means.

Maintenance, upgrade cost and the licence question

The last push to the default branch was on 2026-09-20, and the most recent tagged release in the repository is release/0.22.3 from 2026-08-29, preceded by 0.22.2 on 2026-08-28 and 0.22.1 on 2026-08-24. The repository is not archived. The 0.x versioning and the pace of patch releases mean you should expect to upgrade often, and the version number is a fair warning that interfaces can move between releases.

Upgrade cost has two parts. The desktop app is a self-contained Tauri binary, so upgrading is a download. The CLI is a Rust binary, and if you build it yourself you inherit the workspace requirements: Node `>=24`, `[email protected]`, and the pinned toolchain in `rust-toolchain.toml`. If you script against `but` in CI, pin the binary version rather than tracking master, because the Makefile's `check-modern-but` target shows the CLI is being deliberately reshaped by removing default features.

On licensing: the README states the Fair Source terms and the two-year conversion to MIT, and the repository field reports NOASSERTION. Read LICENSE.md and the linked fair.io page for the actual terms. Nothing here is legal advice, and the practical question (whether your use counts as building a competitor) is not one the README answers.

Editorial conclusion

Adopt GitButler if you already have a Git repository and want stacked or parallel branch work without learning rebase -i, and if the desktop app plus the `but` CLI fit how you and your agents commit. Do not adopt it if you need a permissively licensed dependency today, or if your team's workflow is built on `git worktree`, which GitButler's branch model replaces rather than wraps. Verify first that the binary you install is the one you intend to run: the README points at gitbutler.com/downloads for the app, while the CLI is a separate Rust binary named `but` that the repository builds from the workspace. Check the LICENSE.md text for the two-year MIT conversion before you vendor it.

Frequently asked questions

Official sources

1. gitbutlerapp/gitbutler on GitHub
2. Issues
3. Project website
4. README
5. Releases