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 open --from <branch> [branch-name]
• bra close [branch-name]
• bra prune
• 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

When no branch is provided, bra open creates a new branch from the current branch using <current-branch>-YYMMDD-HHMMSS-nnnnnnnnn in UTC.

bra open

Create a worktree from a specific base branch instead of the current branch:

bra open --from develop feature/sso
bra open --from develop

Remove a worktree by branch name, optionally deleting the local branch:

bra close feature/sso
bra close feature/sso --delete-branch

Prune stale worktree metadata. Branch cleanup is explicit: --merged also deletes local branches already merged into the current HEAD.

bra prune
bra prune --merged

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. Without branch, it generates one from the current branch and timestamp.
• bra open --from <branch> [branch] creates new branches from the selected local or origin/<branch> base instead of HEAD.
• bra close [branch] removes the worktree for a branch. It only deletes the local branch when --delete-branch is passed.
• bra prune runs git worktree prune. Branch deletion is opt-in through --merged.
• 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.