Starting in a Repository

GitButler needs no setup step. Run any but command in an existing Git repository and it works:

but status

GitButler picks a target branch, the branch you eventually merge into, such as main or origin/main. To see it or change it, use but config target:

but config target
but config target main

Unlike a tool like Jujutsu or Sapling, GitButler operates on normal Git repositories, so nearly all Git commands work with anything GitButler produces. You can think of it as a new porcelain rather than a different system.

One branch or several

With one branch applied, your repository stays a normal checkout of that branch, like plain Git.

When you apply a second branch, GitButler creates a branch called gitbutler/workspace and checks it out. It points to a merge commit of all your applied branches, so git status and your editor show what you expect. GitButler rewrites this commit as your branches change. See Workspace Branch for details.

When you unapply branches until one is left, GitButler switches back to that branch.

Leave the workspace

To go back to a single checked-out branch, run:

but teardown

This checks out your first applied branch and unapplies the others, which you can apply again later with but apply.