bgit

bgit is a Git-like CLI for repositories stored directly in Google Cloud Storage. It keeps a normal .git checkout on disk, so developers can use familiar Git commands locally, while bgit handles syncing branches and tags to a gs:// repository.

Use it when you want a lightweight Git backend in GCS without running a Git server.

Project

• Homepage: https://bucketgit.com/
• Author: Dennis Vink
• License: MIT

Features

• Clone, initialize, fetch, pull, and push repositories backed by GCS.
• Store a repository at any gs://bucket/path/to/repo.git prefix.
• Work in a normal Git checkout with a standard .git directory.
• Use common Git workflows: branches, tags, merges, checkout, revert, reset, stash, diff, log, show, add, commit, rm, and mv.
• Push branches and tags back to GCS with bgit push.
• Configure an origin with bgit origin or bgit remote add origin.
• Create the target GCS bucket automatically when permissions allow it.
• Run direct GCS inspection commands for scripts and automation.

Requirements

• Go 1.22 or newer to build from source.
• The git executable available on PATH.
• Google Cloud Storage access through the environment where bgit runs.

bgit uses the standard Google Cloud client libraries. In local development, that usually means Application Default Credentials:

gcloud auth application-default login
gcloud auth application-default set-quota-project PROJECT_ID

When bgit push, bgit put, or bgit --bucket ... init targets a bucket that does not exist, bgit attempts to create it in the active Google Cloud project. The project is read from GOOGLE_CLOUD_PROJECT, GCLOUD_PROJECT, GCP_PROJECT, or gcloud config get-value project.

If Google returns an ADC reauthentication error such as invalid_rapt, invalid_grant, or USER_PROJECT_DENIED, refresh ADC outside of bgit:

gcloud auth application-default print-access-token
gcloud auth application-default set-quota-project PROJECT_ID

If that still fails, recreate ADC for the intended account and project:

gcloud auth application-default revoke
gcloud auth application-default login
gcloud auth application-default set-quota-project PROJECT_ID

Build

go build -o bgit .

Install

With Homebrew:

brew tap bucketgit/bgit
brew install bgit

Or build from source:

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

Quickstart

Clone an existing GCS-backed repository:

bgit clone gs://my-bucket/repositories/demo.git ./demo
cd demo

git status
git log --oneline

Make a change and push it:

echo "hello" > README.md
bgit add README.md
bgit commit -m "Add README"
bgit push

Create a new repository from an existing directory:

mkdir demo
cd demo

bgit init
echo "hello" > README.md
bgit add README.md
bgit commit -m "Initial commit"

bgit origin gs://my-bucket/repositories/demo.git
bgit push

Repository URLs

Repository URLs use the gs:// scheme:

gs://bucket-name/path/to/repo.git

The bucket is the GCS bucket name. Everything after the bucket is the repository prefix. For example, this repository:

gs://my-bucket/repositories/demo.git

is stored under:

gs://my-bucket/repositories/demo.git/HEAD
gs://my-bucket/repositories/demo.git/objects/...
gs://my-bucket/repositories/demo.git/refs/...

Common Commands

bgit clone gs://my-bucket/repositories/demo.git [directory]
bgit init [directory]
bgit origin gs://my-bucket/repositories/demo.git

bgit fetch
bgit pull
bgit push
bgit push --tags
bgit push --delete feature
bgit ls-remote

bgit checkout -b feature
bgit checkout main
bgit branch
bgit merge feature
bgit tag v1.0.0
bgit revert HEAD

bgit status
bgit add -A
bgit commit -m "Update"
bgit diff
bgit log --oneline
bgit show HEAD

Most local workflow commands are passed through to the local Git client. This preserves normal Git flag combinations such as bgit add -A, bgit commit -am "message", bgit checkout -b feature, and bgit merge main.

Origins

bgit clone writes the GCS origin into .git/config automatically. To attach a GCS origin to an existing checkout, run:

bgit origin gs://my-bucket/repositories/demo.git

You can also use Git-style remote commands:

bgit remote add origin gs://my-bucket/repositories/demo.git
bgit remote set-url origin gs://my-bucket/repositories/demo.git

If bgit push is run without an origin, it prints a copy-pasteable example:

No configured push destination.
Either specify the GCS repository from the command-line:

    bgit --bucket bucket-name --prefix path/to/repo.git push

or configure a bgit origin:

    bgit origin gs://bucket-name/path/to/repo.git

and then push:

    bgit push

Branches And Tags

New repositories default to the main branch. Use --branch when cloning or using direct GCS mode to target another branch:

bgit --branch develop clone gs://my-bucket/repositories/demo.git
bgit --branch release fetch

Tags are regular Git tags in the GCS-backed bare repository:

bgit tag v1.0.0
bgit tag -a v1.0.1 -m "Release v1.0.1"
bgit push --tags
bgit ls-remote --tags

Direct GCS Mode

Most developers should use clone, init, origin, and push. Direct GCS mode is available for scripts and one-off inspection without a checkout:

bgit --bucket my-bucket --prefix repositories/demo.git ls docs/
bgit --bucket my-bucket --prefix repositories/demo.git cat docs/readme.md
bgit --bucket my-bucket --prefix repositories/demo.git log --limit 10
bgit --bucket my-bucket --prefix repositories/demo.git put docs/readme.md --file README.md -m "Add readme" --author "Ada Lovelace" --email ada@example.com

How It Works

bgit stores Git objects and refs in a GCS prefix using the normal Git repository layout. Remote operations read and write those objects and refs directly through the GCS API.

Local checkouts remain normal Git worktrees. Regular Git can inspect history, show diffs, stage changes, and create commits. GCS-backed remote updates go through bgit.

Unsupported Commands

Some Git commands depend on Git's network protocol, server-side hooks, packfile maintenance, or repository features that bgit does not emulate. Unsupported commands return:

Unsupported: '<command>' is not supported by bgit

Unsupported commands include daemon, submodule, lfs, gc, fsck, repack, prune, worktree, credential helpers, server helpers, and related maintenance commands.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the fork-to-pull-request workflow and the checks to run before opening a PR.

License

bgit is released under the MIT License. See LICENSE.

Disclaimer

bgit is provided as-is, without warranty of any kind. You are responsible for testing it against your own repositories, access controls, backup strategy, and operational requirements before relying on it in production.

Help

bgit help
bgit help push
bgit push --help
bgit --help push
bgit push help