Git repositories on GCS and S3

Git repositories, stored directly in buckets.

bgit lets you push code to a GCS or S3 bucket without running a Git server.

$ bgit clone s3://team/app.git
Cloned s3://team/app.git into 'app'

$ cd app
$ bgit checkout -b feature/storage-backend
$ bgit commit -am "Ship storage layer"
$ bgit push

macOS arm64 macOS amd64 Linux arm64 Linux amd64 Windows arm64 Windows amd64

Build from source

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

Install with Homebrew

brew tap bucketgit/bgit
brew install bgit

Authentication

Use your existing cloud credentials.

bgit uses your default gcloud or AWS credentials. Add --profile only when you need a named gcloud or AWS profile.

Using the default credentials

bgit clone gs://team/repos/app.git
bgit clone s3://team/repos/app.git
bgit push

Use an existing profile

bgit clone gs://team/repos/app.git --profile gcp-dev
bgit clone s3://team/repos/app.git --profile aws-dev
bgit push --profile aws-dev

Configuring auth and profile for a single repo

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

Create a new profile for your repository

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

Use ADC credentials instead

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

Create A Repository

Start local, then point bgit at a bucket.

Create a normal Git checkout, set a gs:// or s3:// origin, and push. Missing buckets are created automatically when your cloud credentials have permission. S3 buckets start with AWS Block Public Access enabled.

GCS

mkdir app
cd app
bgit init
echo "# App" > README.md
bgit add README.md
bgit commit -m "Initial commit"
bgit origin gs://team-bucket/repos/app.git
bgit push

S3

mkdir app
cd app
bgit init
echo "# App" > README.md
bgit add README.md
bgit commit -m "Initial commit"
bgit origin s3://team-bucket/repos/app.git
bgit push

Native CLI

Git local work, bucket-backed remote state.

Local commands are implemented by bgit for normal checkout workflows. Remote commands read and write Git objects and refs directly through the GCS or S3 API.

Status

Stage, commit, inspect, and move through history without leaving the bgit CLI.

$ bgit status
 M README.md
?? docs/setup.md

1 / 25

Documentation

Run Git workflows on top of buckets.

bgit creates normal .git checkouts locally and stores remote Git objects, refs, branches, and tags in a bucket prefix.

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

Local workflow

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

Branches and tags

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

Search and inspect

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

Remote storage

bgit fetch
bgit pull
bgit push
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

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

Public repositories

# 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

Private repositories

# 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, server helpers, maintenance commands, and Git protocol server behavior 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.