Parallel Branches

You don't switch branches, and you don't need a folder per branch. All the branches you're working on are in the same folder at the same time, so you open one editor window on the repository. When you commit, you choose which branch each change goes to.

What is in your folder

Your folder contains the changes from all your branches, combined. For example, with two branches, but status shows each branch and its commits:

╭┄ @ [uncommitted] (no changes)
┊
┊╭┄ li [liked-tweets]
┊●   qnl Add liked tweets
├╯
┊
┊╭┄ us [user-bookmarks]
┊●   nsr Add bookmarks
├╯
┊
┴ c257f1a (common base, main) 2026-10-28 Initial commit

Hint: run `but help` for all commands

Git sees this combination as a single merge commit on a branch called gitbutler/workspace, so your editor and other Git tools work as usual.

*   b125093 (HEAD -> gitbutler/workspace) GitButler Workspace Commit
|\  
| * 27c6f03 (user-bookmarks) Add bookmarks
* | 62736c3 (liked-tweets) Add liked tweets
|/  
* c257f1a (origin/main, main, gitbutler/target) Initial commit

Check each branch's changes

To see only one branch's changes, pass its name to but diff:

────────────────────╮
 A src/bookmarks.ts │
────────────────────╯

@@ -1,0 +1,3 @@
───────────────
  ┊ 1 │ +export function addBookmark(id: string) {
  ┊ 2 │ +  return id;
  ┊ 3 │ +}

────────────────────╮
 A src/bookmarks.ts │
────────────────────╯

@@ -1,0 +1,3 @@
───────────────
  ┊ 1 │ +export function addBookmark(id: string) {
  ┊ 2 │ +  return id;
  ┊ 3 │ +}

────────────────╮
 A src/likes.ts │
────────────────╯

@@ -1,0 +1,3 @@
───────────────
  ┊ 1 │ +export function likeTweet(id: string) {
  ┊ 2 │ +  return id;
  ┊ 3 │ +}

────────────────╮
 A src/likes.ts │
────────────────╯

@@ -1,0 +1,3 @@
───────────────
  ┊ 1 │ +export function likeTweet(id: string) {
  ┊ 2 │ +  return id;
  ┊ 3 │ +}

Hide a branch

To take a branch's changes out of your folder, unapply it:

Unapplied stack with 'liked-tweets' from workspace

but status now shows only user-bookmarks:

╭┄ @ [uncommitted] (no changes)
┊
┊╭┄ us [user-bookmarks] [HEAD]
┊●   nsr Add bookmarks
├╯
┊
┴ c257f1a (common base, main) 2026-10-28 Initial commit

Hint: run `but help` for all commands

With only one branch left, GitButler switches back to that branch, like a plain Git checkout, and the workspace commit is gone:

* 27c6f03 (HEAD -> user-bookmarks) Add bookmarks
* c257f1a (origin/main, main, gitbutler/target) Initial commit

liked-tweets still exists, and but branch lists it under unapplied branches:

Applied branches
active  ✓ *user-bookmarks        today      Markus Butler

Unapplied Branches
local   ✓ liked-tweets ↑1     today      Markus Butler

To bring the branch back, apply it, and GitButler switches to gitbutler/workspace again:

Applied branch 'liked-tweets' to workspace

Run several agents at once

You can run several agent sessions in the same folder, and each session commits the changes it made to a separate branch. There is nothing to set up per session: once your agents use GitButler, start another session in the same folder. Parallel agents explains how.

Next steps

For step-by-step workflows, follow the CLI tutorial.