GitButler and Git Worktree

What is GitButler?

GitButler is a modern Fair Source Git client built in Rust and Tauri. It focuses on improving the daily developer workflow. Its standout feature is virtual branches, which allow you to have multiple branches applied to your working directory at the same time.

Traditional Git requires you to commit or stash changes before switching branches. GitButler removes this friction by letting you assign uncommitted changes to different virtual branches. Each virtual branch tracks its own set of files and hunks, and you can push any of them independently as real Git branches.

Key features of GitButler include:

• Virtual branches: Work on multiple branches at once without switching or stashing
• Drag-and-drop changes: Assign individual files or hunks to different branches visually
• Built-in conflict resolution: Handles overlapping changes between virtual branches
• AI-powered commit messages: Optional AI integration to generate commit messages
• Source model: Distributed under the Fair Source License and developed in public on GitHub

How GitButler Relates to Git Worktree

Both GitButler and git worktree address the same developer pain point: context switching between tasks. When you need to work on a feature and a bug fix simultaneously, you have two main options:

• Git worktree: Create a separate directory for each branch. Each worktree has its own working copy of the files, and you switch between them by changing directories.
• GitButler virtual branches: Stay in a single directory. GitButler tracks which changes belong to which branch and manages the separation for you internally.

GitButler's virtual branches are not built on top of git worktree. Instead, GitButler uses its own internal data structures — centered around a single target branch and one working directory — to track which changes belong to which virtual branch. The problem it solves is similar to what git worktree addresses (parallel work on multiple branches), but the underlying mechanism is entirely different.

GitButler Virtual Branches vs Git Worktree

Here is a side-by-side comparison of how GitButler virtual branches and traditional git worktree handle common scenarios:

When to Use GitButler vs Git Worktree

Choose GitButler When

• You frequently make small, unrelated changes across different branches in a single session
• You want to split uncommitted work into multiple branches after the fact
• Disk space is a concern and you want to avoid duplicating working directories
• You prefer a GUI-driven workflow with visual change assignment
• Your changes rarely touch the same files across different tasks

Choose Git Worktree When

• You need full build isolation (separate node_modules, build output, etc.)
• You run long-running processes (dev servers, tests) per branch
• You want to use any editor or IDE, not just GitButler
• You work on large features that touch many of the same files as other branches
• You prefer standard Git tools and concepts without additional abstractions
• You need to review or compare two branches side by side in separate editor windows

Using GitButler and Git Worktree Together

While GitButler and git worktree address the same problem, it is possible to use them together in a limited way. GitButler manages its own workspace, so you should not create manual worktrees inside a GitButler-managed repository. However, you can use them side by side:

# Scenario: GitButler for daily work, worktrees for long-running tasks

# 1. Use GitButler in your main working directory for quick feature work
#    (virtual branches handle small, parallel tasks)

# 2. Create a traditional worktree for a long-running task that needs isolation
git worktree add ../project-perf-testing perf/load-test

# 3. Open the worktree in your preferred editor (not managed by GitButler)
code ../project-perf-testing

# 4. The worktree and GitButler's main directory are independent
#    - GitButler manages virtual branches in the main directory
#    - The worktree operates as a standard Git checkout

# 5. When done, clean up the worktree
git worktree remove ../project-perf-testing

The key rule: let GitButler manage its directory, and keep manual worktrees separate. Do not try to open a manually-created worktree in GitButler or enable GitButler's virtual branches in a linked worktree.

GitButler Setup Guide

Installation

GitButler is available for macOS, Linux, and Windows. Download it from the official website or install via a package manager:

# macOS (via Homebrew)
brew install --cask gitbutler

# Linux (via the official .deb / AppImage)
# Download from https://gitbutler.com

# Or build from source
git clone https://github.com/gitbutlerapp/gitbutler.git
cd gitbutler
cargo build --release

Getting Started with Virtual Branches

Once installed, open your repository in GitButler:

# GitButler virtual branches workflow (GUI-driven):

# 1. Open GitButler and select your repository
# 2. GitButler detects your current branch and shows uncommitted changes
# 3. Create a virtual branch:
#    - Click "New Virtual Branch" in the sidebar
#    - Name it (e.g., "feature/sidebar")
# 4. Drag files or hunks to assign them to virtual branches
#    - sidebar.tsx → "feature/sidebar"
#    - header-fix.tsx → "fix/header-bug"
# 5. Commit and push each virtual branch independently
#    - Each push creates a real Git branch on the remote
# 6. Create pull requests as usual from each pushed branch

Integrating with Your Editor

GitButler works alongside your existing editor. Keep your editor open on the same directory and use GitButler as your Git interface. Popular combinations include:

• VS Code + GitButler: Edit in VS Code, manage branches in GitButler
• Neovim + GitButler: Terminal editing with GitButler for visual branch management
• IntelliJ + GitButler: JetBrains IDE for code, GitButler for branch operations

If you prefer a fully terminal-based workflow without a GUI, consider Lazygit instead, which has built-in git worktree support with keyboard shortcuts for every operation.