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 .

Authentication

For gs:// remotes, bgit asks gcloud for an OAuth token with gcloud auth print-access-token. Use --profile to select a named gcloud configuration.

bgit clone gs://my-bucket/repositories/app.git --profile gcp-dev
bgit push --profile gcp-dev

For s3:// remotes, bgit uses the AWS SDK credential chain. That includes AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, IAM roles, SSO, and AWS CLI profiles. Region selection follows AWS_REGION, then AWS_DEFAULT_REGION, then us-east-1.

bgit clone s3://my-bucket/repositories/app.git --profile aws-dev
bgit push --profile aws-dev

Save auth defaults in a checkout:

bgit config bucketgit.auth gcloud
bgit config bucketgit.profile team-dev
bgit config bucketgit.profile

Create a gcloud profile and save it in the current checkout:

bgit create-gcloud-profile team-dev
bgit create-gcloud-profile --yes ci-profile

Use ADC explicitly for CI or service-account environments:

bgit push --auth adc
bgit config bucketgit.auth adc

Repositories

Repository URLs use the gs://bucket/path/repo.git or s3://bucket/path/repo.git form. The bucket is the cloud bucket name. The path is the repository prefix where bgit stores Git objects and refs.

bgit clone gs://my-bucket/repositories/app.git
bgit clone s3://my-bucket/repositories/app.git
bgit init
bgit origin gs://my-bucket/repositories/app.git
bgit origin s3://my-bucket/repositories/app.git
bgit push

bgit clone and bgit init create standard .git directories, so local tools can still inspect the checkout. Read-only remote operations try anonymous public access first, then retry with configured credentials for private repos.

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 bucketgit.profile
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 --skip-broker
bgit push --delete feature
bgit ls-remote
bgit --bucket my-bucket --prefix repositories/app.git log --limit 10
bgit --bucket my-bucket --prefix repositories/app.git cat README.md

SSH Broker

bgit ssh setup configures a repository so standard Git clients use bgit as the SSH command. The broker stores repository registrations and SSH public keys, authorizes fetch and push, and coordinates compare-and-swap ref updates for safer concurrent pushes on both GCS and S3 backends.

bgit ssh setup gs://my-bucket/repositories/app.git
bgit ssh setup s3://my-bucket/repositories/app.git --profile work

GIT_SSH_COMMAND="bgit ssh" git clone git@git.bucketgit.com:my-bucket/repositories/app.git

Key roles are read, write, and admin. Suspended keys are rejected. If a broker is configured, bgit push and native git push through the SSH bridge use broker CAS before mirroring refs to object storage. bgit push --skip-broker is an operator escape hatch for direct bucket writes.

Broker-mediated web reads use the broker runtime's cloud permissions. The generated AWS broker role includes S3 read/list permissions. On GCP, grant the Cloud Run function service account storage read/list access when repository buckets are outside its default project access.

bgit ssh keys list
bgit ssh keys add --user ada --role write --key ~/.ssh/ada.pub
bgit ssh keys suspend KEY_OR_COMMENT
bgit ssh keys remove KEY_OR_COMMENT

Web UI

bgit web serves a local repository browser on 127.0.0.1:8042. By default it reads the configured remote repository using the same public-first, authenticated-retry path as read-only remote commands. If a broker is configured, it can fall back to SSH-key-signed broker reads for users who do not have direct cloud credentials.

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

The web UI includes a branch/tag selector, clone command copy buttons, file browsing, raw blob views, commit metadata, and per-commit diffs.

Access Control

bgit admin grants bucket access using the selected cloud profile. Run inside a checkout to infer the bucket and prefix, or pass --bucket.

# GCS
bgit admin grant-read user:dev@example.com
bgit admin grant-write serviceAccount:ci@project.iam.gserviceaccount.com
bgit admin --bucket my-bucket grant-admin admin@example.com
bgit admin make-public
bgit admin make-private

# S3
bgit admin grant-read arn:aws:iam::123456789012:role/Developer
bgit admin grant-write 123456789012
bgit admin --bucket s3://my-bucket/repositories/app.git grant-admin arn:aws:iam::123456789012:role/Admin
bgit admin --bucket s3://my-bucket/repositories/app.git make-public
bgit admin --bucket s3://my-bucket/repositories/app.git make-private

GCS grants update bucket IAM. S3 grants update the bucket policy for the repository prefix. Public repositories are discovered with anonymous reads first; private repositories automatically retry with configured credentials. S3 public/private toggles also manage bucket-level Block Public Access. AWS identities must be IAM/STS ARNs, 12 digit AWS account IDs, or *.

# GCS: add anonymous bucket read roles
bgit admin make-public

# S3: disable Block Public Access,
# then add anonymous read for this prefix
bgit admin --bucket s3://my-bucket/repositories/app.git make-public

# GCS: remove anonymous bucket read roles
bgit admin make-private

# S3: remove bgit's anonymous policy statements,
# then restore bucket-level Block Public Access
bgit admin --bucket s3://my-bucket/repositories/app.git make-private

Current Limits

rebase, repository maintenance commands, LFS, submodules, and server-side hooks are not implemented. Local merge, cherry-pick, revert, blame, and diff support focus on practical non-conflicting workflows rather than the complete Git porcelain surface. The SSH bridge implements the Git fetch/push protocol used by normal Git clients for bucket-backed repositories.