# 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:
```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>
```
## 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"
[[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:
```bash
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.
```bash
bra open
```
Create a worktree from a specific base branch instead of the current branch:
```bash
bra open --from develop feature/sso
bra open --from develop
```
Remove a worktree by branch name, optionally deleting the local branch:
```bash
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.
```bash
bra prune
bra prune --merged
```
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 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:
```bash
bra bootstrap
bra build --release
```
Unknown subcommands are treated as script names and forwarded to `script run` with any additional arguments.
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. 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:
```bash
cargo test
```
The repository also includes integration tests that create temporary Git repositories and exercise real worktree flows.