Git repositories, stored directly in buckets.

Install

Install with Homebrew, download a release binary, or build from source.

brew tap bucketgit/bgit
brew install bgit

bgit --version

git clone https://github.com/bucketgit/bgit.git
cd bgit
go build -o bgit .

Setup

The default workflow starts with bgit setup. It discovers cloud profiles, lets you choose broker regions, imports owner SSH keys, deploys or updates the broker, and writes ~/.bgit/config.yaml.

bgit setup
bgit setup profile create --provider gcp work
bgit setup profile create --provider aws work

Profiles are provider- and region-aware. If a profile has more than one configured region, pass --region or use a region-qualified profile name.

bgit init --noninteractive --repo app --profile work.europe-west1
bgit push --profile work --region europe-west1

Direct cloud credentials are still useful for initial setup, broker upgrades, and recovery commands under bgit direct. Day-to-day clone, fetch, pull, push, review, and web browsing use SSH-key-signed broker access.

Repositories

Normal repositories are flat logical names managed by the broker. The broker maps each logical repo to a physical bucket and prefix, creates missing buckets when allowed, and hides collision-resistant bucket suffixes from everyday commands.

bgit init
bgit init --noninteractive --repo app --profile work.eu-west-1
bgit clone https://broker.example.com/app.git ./app
bgit push

bgit clone and bgit init create standard .git directories. bgit init also writes core.sshCommand, so native Git fetch and push use the BucketGit SSH bridge.

Commands

bgit status
bgit add -A
bgit commit -m "Update"
bgit diff
bgit show HEAD
bgit restore README.md
bgit reset --hard HEAD
bgit stash
bgit revert HEAD

bgit checkout -b feature/storage
bgit branch
bgit merge feature/storage
bgit tag v0.3.0
bgit push --tags

bgit grep broker
bgit blame README.md
bgit describe
bgit ls-files
bgit ls-tree -r HEAD
bgit archive HEAD > source.tar
bgit rev-parse HEAD

bgit fetch
bgit pull
bgit push
bgit push --delete feature
bgit ls-remote
bgit whoami
bgit repos mine

SSH Broker

bgit setup deploys the broker and imports owner SSH keys. bgit init configures a repository so standard Git clients use bgit as the SSH command. The broker stores logical repositories, SSH public keys, PRs, branch protection, and compare-and-swap ref updates.

bgit setup
bgit init

git fetch
git push
bgit clone https://broker.example.com/app.git ./app

Key roles are owner, admin, maintainer, developer, triage, and read. Suspended keys are rejected. If branch protection requires PRs, direct pushes to protected refs are rejected unless owner/admin override is enabled.

Broker-mediated object transfer uses short-lived capabilities. AWS brokers can issue scoped STS credentials. GCP brokers issue V4 signed URLs and resumable upload sessions. Final ref updates stay broker-owned and are protected by role checks, branch rules, and compare-and-swap.

bgit admin keys list
bgit admin keys add --user ada --role developer --key ~/.ssh/ada.pub
bgit admin keys import-github octocat --role triage
bgit admin keys suspend KEY_OR_FINGERPRINT
bgit admin keys remove KEY_OR_FINGERPRINT

Web UI

bgit web serves a local repository browser on 127.0.0.1:8042. By default it uses the repository's broker configuration, seeds from local state for fast rendering, then synchronizes remote state in the background.

bgit web
bgit web --port 9000
bgit web --local

The web UI includes branch and tag navigation, clone commands, file browsing, commit diffs, pull requests, issues, repo settings, capability-aware controls, local dirty/staged/unpushed state, and live refresh from the local daemon.

Access Control

bgit admin manages broker users, roles, and branch protection. Direct cloud IAM and bucket-policy recovery commands live under bgit direct admin.

bgit admin keys list
bgit admin keys add --user ada --role developer --key ~/.ssh/ada.pub
bgit admin keys import-github octocat --role triage
bgit admin invite-user --broker https://broker.example.com --user ada --role developer app.git
bgit admin accept-invite CODE
bgit admin protect add main

bgit pr create --title "Add docs" --source feature --target main
bgit pr merge 1

bgit issue create "Missing docs" --body "The setup page needs examples."
bgit issue list
bgit issue comment 1 "I can take this."
bgit issue close 1

Roles are owner, admin, maintainer, developer, triage, and read. Protected branches can require pull-request merges, with optional owner/admin override.

bgit admin repo visibility public
bgit admin repo visibility private
bgit admin repo readonly on
bgit admin repo readonly off
bgit admin repo issues on
bgit admin repo issues off
bgit admin repo rename new-name
bgit admin repo delete --yes

bgit admin confirm-ownership-transfer --broker https://broker.example.com app.git
bgit admin accept-ownership-transfer CODE
bgit admin cancel-ownership-transfer --broker https://broker.example.com app.git

bgit direct help
bgit direct clone gs://bucket/path/app.git
bgit direct clone s3://bucket/path/app.git
bgit direct admin grant-read user:dev@example.com

Current Limits

rebase, LFS, submodules, worktrees, server-side hooks, credential helpers, and repository maintenance commands such as gc, fsck, repack, and prune are not implemented. Local merge, cherry-pick, revert, blame, and diff support covers practical day-to-day workflows, but does not aim to be a complete reimplementation of every Git porcelain edge case. The SSH bridge implements the native Git fetch/push protocol used by normal Git clients for BucketGit repositories.