_     _ _        _ _
| |__ (_) |_ __ _(_) |_
| '_ \| | __/ _` | | __|
| |_) | | || (_| | | |_
|_.__/|_|\__\__, |_|\__|
            |___/

git + Bitbucket Data Center CLI with a hook-based plugin system.

Landing page · Plugin protocol · Config

Status: pre-alpha. Under active development. The CLI surface and plugin protocol are in place. Verbs (pr, commit, push, branch, doctor) are stubs — implementation is in flight. Watch the repo for v0.1.0.

---

What

bitgit is a generic-verb git CLI (bitgit pr create, bitgit pr show <id>, bitgit commit, bitgit push, bitgit doctor, …) that wraps git and Bitbucket Data Center — and lets you inject veto/mutate logic via plugins.

Plugins:

• Auto-attach based on git remote, project key, repo slug, or branch prefix.
• Speak JSON-RPC 2.0 over stdio — write them in any language.
• Hook into pre-pr-create, post-pr-create, pre-pr-merge, pre-commit, pre-push, …
• Can veto an operation (e.g. corp policy: "no force-push to release/*") or mutate it (e.g. "auto-prepend Jira key to PR title").

Designed for shops where every team has its own conventions and you want one CLI that respects all of them without forking.

Why

gh and tea don't speak Bitbucket DC. hub is unmaintained. None of them let you wedge in language-agnostic policy plugins.

Install

Pre-alpha; install methods become stable at v0.1.0.

# Once stable releases exist:
brew install exisz/tap/bitgit

# Always works from source:
go install github.com/exisz/bitgit/cmd/bitgit@latest

# Pre-built binaries (per release):
# https://github.com/exisz/bitgit/releases

Quick start

bitgit --help
bitgit doctor              # sanity-check chassis + plugins
bitgit plugin list         # installed plugins under ~/.bitgit/plugins/
bitgit pr create           # (stub — under development)

Plugins

Plugins live under ~/.bitgit/plugins/<name>/ with a plugin.toml manifest. Read docs/plugin-protocol.md for the full wire spec. A reference plugin in Go ships in plugins/example-github/.

Minimal plugin manifest:

name = "corp-policy"
version = "1.0.0"
entrypoint = "./corp-policy"
hooks = ["pre-pr-create", "pre-pr-merge"]

[match]
remote_host = ["bitbucket.example.com"]
project_key = ["PLAT"]

A plugin is just any executable that reads JSON-RPC requests on stdin and writes JSON-RPC responses on stdout. ~50 lines in any language.

Architecture

Layer	Repo	Purpose
Public chassis	exisz/bitgit (this repo)	CLI surface, plugin runtime, docs
Private overlay	exisz/bitgit-workspace	Shop-specific verb implementations + plugins (private)
User config	~/.bitgit/	config.toml, plugins/, secrets/, cache/

Token file naming

Default token paths under ~/.bitgit/secrets/ use the host type with underscores, not hyphens:

Host type	Token file	Env override
github	~/.bitgit/secrets/github.token	GITHUB_TOKEN
bitbucket-dc	~/.bitgit/secrets/bitbucket_dc.token	BITBUCKET_TOKEN

All secret files must be chmod 600 or bitgit refuses to read them.

The chassis works standalone. The private overlay is optional and never imported by the chassis.

Repo layout

cmd/bitgit/        CLI entrypoint
internal/cli/      cobra command tree + verb stubs
internal/plugin/   discovery, match-rule, JSON-RPC stdio, hook dispatcher
plugins/           in-repo reference plugins
docs/              landing page (index.html), plugin-protocol.md, config.md
.github/workflows/ ci.yml (PR gate) + release.yml (tag → goreleaser)
.goreleaser.yml    cross-platform binaries + Homebrew tap

PR watch lifecycle

bitgit ships its own scheduler — no external cron / agent needed.

• bitgit pr create, bitgit push, and bitgit pr watch add register the PR in ~/.bitgit/state/pr-watch.json, then inline poll the host until the build resolves (SUCCESSFUL/FAILED) and notify via the configured webhook.
• The loop sleeps watch.poll_interval_seconds (default 60s) between cycles and exits the moment the registry drains.
• SIGINT/SIGTERM exits cleanly; remaining entries stay in the registry and the next pr create / push / pr poll --loop resumes them.
• Pass --no-wait to register-only (returns immediately, no polling).
• bitgit pr watch status shows registry size + interval.
• bitgit pr poll is the single-shot variant (one cycle, exit). Still available for cron-style usage; --loop mounts the same self-draining loop without registering anything new.

[watch]
poll_interval_seconds = 60

Contributing

See CONTRIBUTING.md. The empire's Go OSS standard lives at ~/.openclaw/skills/empire-standard/references/go-oss-standard.md for internal contributors; external contributors only need to follow the guidelines in CONTRIBUTING.

License

MIT © Exis. See LICENSE.