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
• store scripts as executable paths or inline shell text
• 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>

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"

[[scripts.my-project]]
name = "install"
text = "bun install"

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. Each script must define exactly one of path or non-empty text.

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 add install --text "bun install"
printf 'bun test\n' | bra script add test --text
bra script list
bra script all
bra script run bootstrap
bra script run test -- --watch
bra script remove bootstrap

Path scripts are executed directly. Inline scripts are executed through $SHELL -c, falling back to /bin/sh when SHELL is not set. Passing --text without a value reads the inline script from stdin.

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 add <name> <path> stores a path-based script
• bra script add <name> --text [text] stores an inline script, reading from stdin when text is omitted
• bra script run <name> -- <args> runs the configured script in the repository or worktree directory and forwards trailing arguments

Development

Run tests with:

cargo test

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