Skip to content
bvarnaiPublic

About

Opinionated, simple Git workflow driven by easy commands

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

git-brx logo

git-brx

Opinionated Git branch workflow CLI

CI GitHub Release Scoop Go Version License: MIT Platform

Why git-brx? • Core philosophy • Quick start • Platform support • Installation • Configuration • User guide wiki


Why git-brx?

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.


The git-brx philosophy

1. Issue-first development

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.

2. Built-in safety rails

  • Pushes default to --force-with-lease (git brx publish) so you never blindly overwrite a colleague's remote commits.
  • Issue branches (issue/*) rebase linearly onto main, keeping history clean and bisectable.
  • Conflict resolution (git brx resolve) opens your configured merge tool and stages only the resolved files—never git add ..
  • Branch cleanup (git brx delete) checks that the branch has been merged and removed on origin before deleting local refs.

3. Convention over configuration

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 sync rebases or merges, and whether git brx review recommends a squash merge or a merge commit.
  • Local scratch work: For throwaway spikes without an issue, use standard git checkout -b my-spike.

4. The branch lifecycle

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)"]
Loading

Quick start

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 delete

Available commands

Once 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 support

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.


Installation

Precompiled binary (Linux / macOS)

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/

Via Scoop (Windows)

Install git-brx on Windows with Scoop:

scoop bucket add bvarnai https://github.com/bvarnai/scoop-bucket
scoop install git-brx

Via Go install (Go 1.22+)

go install github.com/bvarnai/git-brx/cmd/git-brx@latest

From source

git clone https://github.com/bvarnai/git-brx.git
cd git-brx
go build -o /usr/local/bin/git-brx ./cmd/git-brx

Verify the installation:

git brx --version
# git-brx version v1.2.0 (86d244b linux/amd64)

Configuration

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.


Antigravity integration

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).


Documentation wiki


Contributing

See CONTRIBUTING.md for architecture rules, test requirements, and branch workflow. Command specifications live in docs/spec/.


License

Licensed under the MIT License.


🤖 AI Disclosure

AI Assisted

Developed with the assistance of AI tools. All AI-generated code is reviewed, tested, and refined by human maintainers.

About

Opinionated, simple Git workflow driven by easy commands

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages