Opinionated Git branch workflow CLI
Why git-brx? • Core philosophy • Quick start • Platform support • Installation • Configuration • User guide wiki
Git's low-level CLI makes everyday team workflows harder than they need to be. As teams grow, three problems show up repeatedly:
- Destructive commands: Engineers hesitate to rebase, sync, or clean up branches when a single wrong flag (
git push --force,git reset --hard,git checkout .) can discard local work or overwrite a teammate's commits. - Inconsistent habits: Without shared tooling, everyone invents their own aliases, branch names, and merge habits. Some squash locally, some create tangled merge histories, and others leave stale branches on
origin. - Heavyweight branching models: Complex branching models built for large release trains add unnecessary overhead for teams shipping continuously.
git-brx wraps standard Git in a thin, guardrailed CLI. It enforces consistent branch naming, automates rebase/merge decisions, prevents accidental history overwrites, and links every branch to an issue and pull request.
There is no lock-in: git-brx runs standard Git plumbing under the hood. You can mix git-brx and raw git commands at any time.
Every tracked code change starts with an issue in Jira or GitHub:
- The issue defines "What" and "Why": Context, requirements, edge cases, and acceptance criteria live in the issue tracker.
- The pull request reviews "How": Code review focuses on design, correctness, test coverage, and security—not rediscovering requirements.
- Pushes default to
--force-with-lease(git brx publish) so you never blindly overwrite a colleague's remote commits. - Issue branches (
issue/*) rebase linearly ontomain, keeping history clean and bisectable. - Conflict resolution (
git brx resolve) opens your configured merge tool and stages only the resolved files—nevergit add .. - Branch cleanup (
git brx delete) checks that the branch has been merged and removed onoriginbefore deleting local refs.
git-brx uses three branch prefixes (issue/*, feature/*, epic/*):
- Consistent naming: No bikeshedding over branch names.
- Automated behavior: The branch prefix determines whether
git brx syncrebases or merges, and whethergit brx reviewrecommends a squash merge or a merge commit. - Local scratch work: For throwaway spikes without an issue, use standard
git checkout -b my-spike.
flowchart LR
A["1. Issue<br/>(Jira / GitHub)"] -->|"git brx create"| B["2. Topic branch<br/>(issue/TASK-101)"]
B -->|"git brx sync / update"| C["3. Work & sync<br/>(Rebase & leased push)"]
C -->|"git brx review"| D["4. Code review<br/>(PR with checklist & reviewers)"]
D -->|"git brx delete"| E["5. Cleanup<br/>(Local deleted & origin pruned)"]
Run the full branch lifecycle in 5 commands:
# 1. Validate the issue in your tracker and create the topic branch
git brx create issue/TASK-101
# ... write code, make regular git commits ...
# 2. Rebase onto the latest main branch
git brx sync
# 3. Push to origin with --force-with-lease and set upstream tracking
git brx publish
# 4. Open a pull request with automated reviewer routing and merge instructions
git brx review
# ... PR is approved and merged on GitHub / Bitbucket ...
# 5. Verify remote deletion, switch back to main, and prune the local branch
git brx deleteOnce git-brx is in your PATH, Git automatically exposes it as git brx <command>:
| Command | Purpose |
|---|---|
git brx create |
Validates the issue in your tracker and creates a local topic branch. |
git brx select |
Fetches remotes and switches branches with typo suggestions and dirty-tree warnings. |
git brx sync |
Syncs the active branch with base (rebases issue/*, merges feature/* and epic/*). |
git brx update |
Rebases local commits onto origin/<current-branch>. |
git brx resolve |
Runs your configured merge tool on conflicted files and continues the rebase/merge. |
git brx reset |
Aborts any active rebase/merge and hard-resets to origin/<current-branch>. |
git brx publish |
Pushes the current branch to origin with --force-with-lease and sets upstream tracking. |
git brx review |
Opens a pull request with automated reviewer assignment and merge instructions. |
git brx delete |
Verifies remote branch deletion, switches to main, and deletes the local branch. |
git brx history |
Prints a formatted commit graph (supports --topic branch filtering). |
git brx name |
Prints the active branch name to stdout for use in scripts. |
git brx config |
Prints the resolved cascading configuration and source provenance in YAML. |
git brx completion |
Generates shell completion scripts (bash, zsh, fish, powershell). |
All commands accept --help (-h), --verbose (-v), --quiet (-q), and --no-color.
| Platform / Backend | Issue tracker | Code review (PR / MR) | Status | Notes |
|---|---|---|---|---|
| ✅ GitHub | GitHub Issues | GitHub Pull Requests | Done | Tested and verified against GitHub.com |
| ⌛ Atlassian (Bitbucket + Jira) | Jira Server / DC | Bitbucket Server / DC | Implemented (untested) | Client and contract tests implemented; not yet verified on live instances |
| 🚧 Hybrid (Jira + GitHub) | Jira Server / DC | GitHub Pull Requests | Implemented (untested) | Client implemented; needs live verification |
| 🚧 GitLab | GitLab Issues | GitLab Merge Requests | Not yet implemented | Planned |
| 🚧 Bitbucket Cloud | Jira Cloud / Bitbucket | Bitbucket Cloud PRs | Not yet implemented | Planned |
See the Supported platforms & integration matrix and the GitHub integration guide for setup details.
Download and extract the latest release to /usr/local/bin:
curl -sSL https://github.com/bvarnai/git-brx/releases/latest/download/git-brx_linux_amd64.tar.gz | tar -xz
sudo mv git-brx /usr/local/bin/Install git-brx on Windows with Scoop:
scoop bucket add bvarnai https://github.com/bvarnai/scoop-bucket
scoop install git-brxgo install github.com/bvarnai/git-brx/cmd/git-brx@latestgit clone https://github.com/bvarnai/git-brx.git
cd git-brx
go build -o /usr/local/bin/git-brx ./cmd/git-brxVerify the installation:
git brx --version
# git-brx version v1.2.0 (86d244b linux/amd64)git-brx requires no configuration file for standard GitHub repositories—it detects your platform, owner, and repo directly from remote.origin.url.
To customize reviewer routing or branch mappings for your repo, add .git-brx.yaml to the repository root:
# Preset platform ('github' or 'bitbucket')
platform: github
# Reviewer routing based on modified paths or issue labels
review:
merge:
instructions: true
template: .github/pull_request_template.md
mapping:
labels:
backend: [alice, bob]
frontend: [carol, dave]
default: [charlie]See the Configuration guide for all options.
git-brx is packaged as a native Google Antigravity (agy) plugin (plugin.json) so AI coding agents use git brx commands instead of raw Git (git checkout -b, git push -f).
-
Install from GitHub (
agy>= 1.5.11):agy plugin install https://github.com/bvarnai/git-brx
-
Install from a local clone (symlink):
mkdir -p ~/.gemini/config/plugins ln -sfn "<path-to-git-brx>" ~/.gemini/config/plugins/git-brx
See the AI agent integration guide for per-project setup and always-on rules (GEMINI.md / AGENTS.md).
- 📖 User guide index: Table of contents and reading paths.
- 🎯 Philosophy & mental model: Issue-driven workflow, branch roles, and PR hygiene.
- 🚀 Getting started: Installation, shell completion, credentials, and configuration cascade.
- 🔄 Branch lifecycle guide: Walkthrough from
createtodelete. - ⚡ Synchronization & rebasing: Rebasing with
syncandupdate, resolving conflicts, and resetting. - 🌐 Supported platforms & matrix: Platform support and setup guides for GitHub and Atlassian.
- 📚 Command reference: Flags, arguments, and examples for every command.
- 💡 Troubleshooting & FAQ: Common errors and recovery steps.
- 🤖 AI assistant rule template: Workspace rule for AI coding agents.
- 🧠 Antigravity / agent skill: Workflow runbook skill for coding agents.
See CONTRIBUTING.md for architecture rules, test requirements, and branch workflow. Command specifications live in docs/spec/.
Licensed under the MIT License.
Developed with the assistance of AI tools. All AI-generated code is reviewed, tested, and refined by human maintainers.