GitButler and Git Worktree

What is GitButler?

GitButler is a modern, open-source Git client built in Rust and Tauri. It was created by one of the co-founders of GitHub and 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
• Open source: Fully open-source under the FSL license, available 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 worktrees (virtual branches): Stay in a single directory. GitButler tracks which changes belong to which branch and manages the separation for you internally.

Under the hood, GitButler uses git's low-level worktree machinery to maintain its internal state. When GitButler manages your repository, it creates its own reference structure that coexists with your regular Git data. However, the worktrees GitButler creates are for its own bookkeeping — they are not the same as the worktrees you create with git worktree add.

GitButler Virtual Branches vs Git Worktree

Here is a side-by-side comparison of how GitButler worktrees (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.