Initializing a Repository

If you run any but command in a repository that has never been seen by GitButler before, it will automatically ask you if you want to setup the repository for GitButler.

It will guess most things needed, but everything can be changed later if it got anything wrong. The most important thing is to figure out the target branch - the main branch that you'll want to merge things into and you consider 'production' or 'golden'. Normally this is something like origin/main, but GitButler should be pretty good at guessing.

You can also run but setup manually to set everything up explicitly:

Setting up GitButler project...

→ Adding repository to GitButler project registry
  ✓ Repository added to project registry

→ Configuring default target branch
  ✓ Using existing push remote: origin
  ✓ Set default target to: origin/main

GitButler project setup complete!
Target branch: origin/main
Remote: origin


We are switching you to GitButler's special `gitbutler/workspace` branch     

To return to normal Git mode, either:
    - Directly checkout a branch (`git checkout master`)
    - Run `but teardown`

More info: https://docs.gitbutler.com/workspace-branch                    

As the command says, it does a few things to prepare your repository for being managed by GitButler.

Unlike a tool like Jujutsu or Sapling, GitButler mainly operates on normal Git repositories, so nearly all Git commands will work with anything produced or managed by GitButler. You can think of it more like a new porcelain than a different system.

However, one thing we need to do in order to enable having parallel applied branches is create a "megamerge" commit that automatically merges in the heads of all your applied branches, so that other tools git status will correctly show you what you expect.

This means that we do two things:

• We create a new branch called gitbutler/workspace pointing to a constantly rewritten and ephemeral merge commit and check this branch out so HEAD is pointing to it (again, for git status reasons in tools like VSCode or whatever)
• We add custom pre-commit and post-checkout hooks (moving and continuing to call any existing hooks) to try to prevent you from accidentally committing on top of our managed mega-merge commit.

Both of these things can be quickly and easily undone by running but teardown, doing any Git committing stuff you need to do and then re-running but setup to go back to GitButler tooling.

You can also simply checkout a git branch with git checkout <branch> and the post-checkout hook we installed should clean up after itself.