git-bra

bra is a worktree manager that covers up the interesting parts of git with a project-aware config

It will help you:

• create or reuse worktrees by branch name
• resolve the path for your worktree branch with bra go
• run project-specific scripts after initialization
• list worktrees and configured scripts

Current Status

The current implementation supports:

• bra init
• bra open <branch-name>
• bra go <branch-name>
• bra list
• bra config path
• bra config init
• bra config show
• bra script add
• bra script list
• bra script all
• bra script run
• bra script remove

Install

Build and install locally with Cargo:

cargo install --path .

This package is set up to install two binaries:

• git-bra so Git can dispatch git bra ...
• bra as the short direct command

That means both of these forms work once the package is installed:

git bra list
bra list

Or run it during development with:

cargo run --bin bra -- <args>

If you package this for AUR later, it can simply ship both installed binaries. You do not need to rely on AUR-specific aliasing or shell configuration for git bra support.

Config

bra reads a global config from the XDG config location:

• $XDG_CONFIG_HOME/bra/config.toml
• fallback: ~/.config/bra/config.toml

For tests and manual overrides, BRA_CONFIG can point to a specific config file.

Example:

worktree_destination = "/home/user/worktrees"
project_prefix = true
branch_separator = "-"

[[scripts.my-project]]
name = "bootstrap"
path = "~/bin/bootstrap-my-project.sh"

[[scripts.my-project]]
name = "test-data"
path = "~/bin/seed-my-project.sh"

Config fields:

• worktree_destination: base directory where worktrees are created
• project_prefix: when true, nests worktrees under <destination>/<project-alias>/
• branch_separator: optional replacement for / in branch names
• scripts: per-project named scripts, keyed by project alias

Project Resolution

--project is a global option and may be passed to any command.

It accepts either:

• a project alias like my-project
• a path to an existing cloned repository

If --project is omitted, bra tries to infer the project from the current Git repository.

The default alias is taken from the last part of the origin URL:

• git@github.com:some-org/my-project.git -> my-project

Usage

Create or reuse a worktree for a branch:

bra open feature/sso

Initialize the current repository or worktree:

bra init

Print the path for a branch:

bra go master
bra go feature/sso

List worktrees for the current repository:

bra list

Manage scripts:

bra script add bootstrap ~/bin/bootstrap-my-project.sh
bra script list
bra script all
bra script run bootstrap
bra script remove bootstrap

Run a script directly using the external command shortcut:

bra bootstrap
bra build --release

Unknown subcommands are treated as script names and forwarded to script run with any additional arguments.

Inspect config:

bra config path
bra config init
bra config show

bra config init creates the config file with commented defaults. The config file is still created automatically the first time a command saves configuration, such as bra script add.

Run a command for another project explicitly:

bra --project my-project script list
bra --project /path/to/repo list

Shell Integration

bra go prints only the resolved path, so shell wrappers stay simple.

Example for bash or zsh:

brag() {
  cd "$(bra go "$@")"
}

If you also want a helper that creates or reuses the worktree and then enters it:

branch() {
  cd "$(bra open "$@")"
}

Example usage:

brag master
brag feature/sso

Command Notes

• bra init refuses to reset if the target repository has uncommitted changes
• bra init fetches origin and hard-resets to origin/<branch> when that remote branch exists
• bra open <branch> creates the worktree if needed, runs the init flow there, and prints the final path
• bra go <branch> prints the parent repository path when that branch is currently checked out in the primary worktree; otherwise it prints the configured worktree path
• bra script run <name> runs the configured script in the repository or worktree directory

Development

Run tests with:

cargo test

The repository also includes integration tests that create temporary Git repositories and exercise real worktree flows.