but branch

This includes creating, deleting, listing, and showing details about branches.

By default without a subcommand, it will list the branches.

To apply or unapply branches, use but apply and but unapply.

To rename an applied branch, use but reword <branch> -m <new-name>.

Usage: but branch <COMMAND>

Subcommands

but branch new

Create a new branch.

Use --above or --below to created stacked branches. Omitting these create a new unstacked branch.

For more details about CLI IDs, see but help cli-ids.

Usage: but branch new [NAME] [OPTIONS]

Arguments:

• <NAME> — Name of the new branch.

If omitted the new branch will get a generated name.

Options:

• -A, --above <BRANCH_OR_COMMIT> — Place the branch above BRANCH_OR_COMMIT, which must be an applied branch or commit.

If BRANCH_OR_COMMIT is a commit, the new branch is created above the commit.

If BRANCH_OR_COMMIT is a branch, the new branch is created above the targeted branch.

• -B, --below <BRANCH_OR_COMMIT> — Place the branch below BRANCH_OR_COMMIT, which must be an applied branch or commit.

If BRANCH_OR_COMMIT is a commit, the new branch is created below the commit.

If BRANCH_OR_COMMIT is a branch, the new branch is created below the targeted branch.

• -s, --switch — Switch to the newly created branch instead of applying it to the GitButler workspace
• --allow-merged — Allow targeting branches and commits that are already merged upstream.

By default, mutations refuse to touch history that has landed in the target branch, since the results tend to conflict on the next but pull.

but branch delete

Delete branchs from the workspace

Usage: but branch delete <BRANCHES>

Arguments:

• <BRANCHES> — One or more branches to delete (required)

but branch list

List the branches in the repository

By default, shows the active branch and the 20 most recently updated branches.

You can use the --all flag to show all branches, --local to show only local branches, or --remote to show only remote branches.

You can also filter branch names by specifying a substring, such as but branch list feature to show only branches with "feature" in the name.

If you want to check for review status, you can add --review to fetch and display pull request or merge request information for each branch. This will make the command slower as it needs to query the forge.

By default, the command checks if each branch merges cleanly into the upstream base target branch (not your workspace). You can disable this check with --no-check to make the command faster.

By default it also calculates the number of commits each branch is ahead of the base branch. You can disable this with --no-ahead to make the command faster.

Usage: but branch list [FILTER] [OPTIONS]

Arguments:

• <FILTER> — Filter branches by name (case-insensitive substring match)

Options:

• -l, --local — Show only local branches
• -r, --remote — Show only remote branches
• -a, --all — Show all branches (not just active + 20 most recent)
• --no-ahead — Don't calculate and show number of commits ahead of base (faster)
• --review — Fetch and display review information (PRs, MRs, etc.)
• --no-check — Don't check if each branch merges cleanly into upstream
• --empty — Include branches with no commits on them (hidden by default)

but branch show

Show commits ahead of base for a specific branch

This shows the list of commits that are on the specified branch but not yet integrated into the base target branch.

You can also choose to fetch and display review information, show files modified in each commit with line counts, generate an AI summary of the branch changes, and check if the branch merges cleanly into upstream.

Usage: but branch show <BRANCH> [OPTIONS]

Arguments:

• <BRANCH> — CLI ID or name of the branch to show (required)

Options:

• -r, --review — Fetch and display review information
• -f, --files — Show files modified in each commit with line counts
• --ai — Generate AI summary of the branch changes
• --check — Check if the branch merges cleanly into upstream and identify conflicting commits

but branch update

Update your local branch with the content of its remote counterpart.

This allows you to resolve the divergence between your local branch and its tracked remote in different ways.

Usage: but branch update <BRANCH> [OPTIONS]

Arguments:

• <BRANCH> — Name of the local branch to integrate (required)

Options:

• -s, --strategy <STRATEGY> — Strategy to use for the integration. If no strategy is specified, we default to pull-rebase (default: pull-rebase)
• --dry-run — Preview the resulting branch state without persisting changes
• -v, --verbose — Show additional dry-run details like the current divergence
• -i, --interactive — Open the generated integration script in an editor