# 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:
```bash
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:
```bash
git bra list
bra list
```
Or run it during development with:
```bash
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:
```toml
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:
```bash
bra open feature/sso
```
Initialize the current repository or worktree:
```bash
bra init
```
Print the path for a branch:
```bash
bra go master
bra go feature/sso
```
List worktrees for the current repository:
```bash
bra list
```
Manage scripts:
```bash
bra script add bootstrap ~/bin/bootstrap-my-project.sh
bra script list
bra script all
bra script run bootstrap
bra script remove bootstrap
```
Inspect config:
```bash
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:
```bash
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`:
```bash
brag() {
cd "$(bra go "$@")"
}
```
If you also want a helper that creates or reuses the worktree and then enters it:
```bash
branch() {
cd "$(bra open "$@")"
}
```
Example usage:
```bash
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:
```bash
cargo test
```
The repository also includes integration tests that create temporary Git repositories and exercise real worktree flows.