sgit-ai — git for encrypted vaults

Clone, commit, branch and merge files that are encrypted before they leave your machine.

sgit is a git-shaped command-line tool for version-controlling files the storage provider cannot read. Every object is encrypted client-side with AES-256-GCM and stored under an opaque, content-addressed id — the server never receives a key, and never sees a filename, a file's contents, or a commit message.

📖 Documentation: sgit.ai — quickstart, the git-to-sgit command mapping, the security model, and the honest page about when not to use this. 🤖 Reading this as an AI agent? sgit.ai/llms.txt is an annotated map of the whole site; sgit.ai/llms-full.txt is every page in one document. Every page is also available as markdown at the same path.

Not to be confused with SGit, the Android Git client, or SGIT, the engineering college. This is sgit-ai on PyPI — the encrypted-vault CLI, documented at https://sgit.ai.

Why this exists

You have files that need version control and collaboration, and the place they are stored must not be able to read them. git gives you the workflow and hands the host your content; encrypted sync tools give you privacy and no history worth the name. sgit is the two together — see sgit.ai/why/, including a straight comparison of where git is still better (performance at scale, ecosystem, bisect/blame/rebase) and where the vault model changes what is possible.

Install

pip install sgit-ai

This gives you two CLI commands: sgit-ai and the shorthand sgit.

Pre-releases (the dev channel)

Releases come from main. Every change merged to dev is also published, as a pre-release (X.Y.Z.dev0), which a plain pip install sgit-ai never selects. To try the newest one:

pip install --pre sgit-ai      # or: sgit update --pre
sgit update                    # on a pre-release: the newest pre-release (stays on the dev channel)
sgit update --stable           # back to the newest release

Quick Start

# Create a new encrypted vault
sgit init my-vault

# Add files to the working directory
cp important-doc.pdf my-vault/

# Commit and push
sgit commit "initial upload" -d my-vault
sgit push my-vault

# Clone an existing vault on another machine
sgit clone <vault-key>

Features

Encrypted Vault Sync

Clone, commit, push, and pull encrypted vaults — just like git, but every object is AES-256-GCM encrypted before upload.

sgit clone <vault-key>          # Download and decrypt a vault
sgit status                     # Show uncommitted changes
sgit commit "my changes"        # Snapshot local changes
sgit pull                       # Fetch and merge remote changes
sgit push                       # Upload to remote
sgit branches                   # List all branches

Client-Side Encryption

All crypto runs locally. The server stores only ciphertext.

• AES-256-GCM for file encryption with per-file HKDF-derived keys
• PBKDF2-SHA256 (600k iterations) for vault key derivation
• Content-addressable storage — encrypted objects stored by hash
• Web Crypto API compatible — byte-for-byte interop with browser implementations

PKI and Digital Signatures

Built-in public key infrastructure for signing and encrypting files between users.

sgit pki keygen                             # Generate RSA-4096 + ECDSA P-256 key pair
sgit pki sign doc.pdf --fingerprint <fp>    # Create detached signature
sgit pki verify doc.pdf sig.json            # Verify signature
sgit pki encrypt doc.pdf --recipient <fp>   # Hybrid RSA-OAEP + AES-256-GCM encryption
sgit pki decrypt doc.pdf.enc --fingerprint <fp>

Signing Your Own Commits

As in Git: your own SSH or OpenPGP key, configured in your Git config, verified against your allowed-signers file or keyring. Every commit also carries its clone's signature, so this is about who you are, not which clone wrote it.

git config --global gpg.format ssh
git config --global user.signingKey ~/.ssh/id_ed25519
git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers
git config --global sgit.gpgSign true          # sign every sgit commit (Git's commit.gpgSign is not read)

sgit commit -S "signed change"                 # or one commit at a time
sgit push
sgit vault tag create -s v1.0                  # a signed tag (of a pushed commit)
sgit history log --show-signature              # Good "git" signature for you@example.com with ED25519 key …
sgit check verify --require-user-signature     # fail unless every commit carries a good one (--limit N: the newest N)
sgit doctor                                    # the Signing block: what sgit will use, and from where

Vault Inspection

Debug and inspect the internals of any vault.

sgit inspect                    # Vault state overview
sgit log --oneline --graph      # Commit history
sgit inspect-tree               # Current tree entries
sgit inspect-stats              # Object store statistics
sgit cat-object <id>            # Decrypt and display an object
sgit fsck --repair              # Verify integrity and repair

History, Blame and Search

The Git commands for reading history, with Git's output formats (checked against git in the tests).

sgit history log --oneline --graph              # Commit history
sgit history log --file docs/a.md --follow      # One file's history, across renames
sgit history log -S needle                      # Commits that add or remove "needle" (-G <regex>: changed lines)
sgit history show HEAD                          # A commit's patch; renames as "rename from / rename to"
sgit history diff -M90 HEAD~3..HEAD             # Rename threshold (--no-renames: plain adds and deletes)
sgit history blame -L 10,+5 src/app.py          # Who last changed each line (--porcelain, --json)
sgit grep -n -i todo                            # Search the working copy (git grep options, exit 0/1/2)
sgit grep -n todo HEAD~5 -- '*.py'              # Search a commit

Only the files a commit changed are opened and decrypted, so history show and log -S cost what changed, not the vault's size.

Static Publishing — serve a vault with no server

Publish a vault as a plain folder of files that any static host (GitHub Pages, S3, a USB stick) can serve, and that sgit clone can read back over ordinary GETs. No server, no auth, no API.

sgit publish                          # write the plaintext surface to .sg_vault/publish/
sgit publish --visibility public      # ...including the read key (irreversible; confirms)
sgit publish --bundles --api-docs     # + head/delta zips + a Swagger UI docs page
sgit vault serve                      # read-only loopback server for the published folder

publish emits only a small plaintext surface — loader, cover.json, manifest.json and, at public, the read key. It never copies ciphertext: the encrypted store is the store, composed into the served root at deployment. Publishing twice from the same head produces byte-identical output, and it needs only the read key, so read-only clones and zero-secret CI can republish.

Reading back needs nothing special:

sgit clone <vault-key> ./dest --transport auto     # folder, static host, or live API

Custody, Attaching, and Ignore Rules

sgit vault mirror <url> ./copy      # keyless verifiable copy — custody without access
sgit vault attach --read-key <key>  # bind a key to an existing bare checkout (CI, git clone)
sgit vault ignore                   # show always-ignored folders
sgit vault ignore --apply .github   # untrack a now-ignored folder in one visible commit

mirror re-hashes every content-addressed object rather than trusting the manifest, so a hostile host cannot substitute content into a copy you are holding for someone else.

Machine-Readable Command Reference

sgit help --format json -o cli-reference.json   # diffable contract, for docs tooling
sgit help --format markdown                     # drop-in command reference page
sgit help --format llms                         # llms.txt-style index for agents

Generated by walking the CLI's own parser, so it cannot describe a command that does not exist or miss one that does — which is what keeps sgit.ai and llms.txt honest across releases.

Credential and Remote Management

# Store vault keys under friendly aliases
sgit vault add my-project --vault-key <key>
sgit vault list

# Configure multiple remotes
sgit remote add origin <url> <vault-id>
sgit remote list

Architecture

sgit_ai/
├── cli/           # CLI commands (sgit-ai / sgit)
├── crypto/        # AES-256-GCM, PBKDF2, HKDF, RSA-OAEP, ECDSA
├── sync/          # Clone, commit, push, pull, merge, branching
├── api/           # SGit-AI Transfer API client
├── pki/           # Key store and contact keyring
├── objects/       # Content-addressable encrypted object store
├── schemas/       # Type_Safe data models
├── safe_types/    # Domain-specific validated types (zero raw primitives)
└── secrets/       # Local encrypted secrets store

Built on osbot-utils Type_Safe framework — all data fields use validated domain types, never raw primitives.

Development

# Install in dev mode
pip install -e ".[dev]"

# Run tests
pytest tests/unit/

# Run with coverage
pytest --cov=sgit_ai --cov-report=term-missing

License

Apache-2.0

Documentation

Full documentation lives at sgit.ai — which is itself served from an encrypted vault, deployed by pushing that vault.