Store arbitrary structured data and files alongside your git commits.

sidegit is a small HTTP server + CLI that lets you attach JSON payloads and file blobs to git commits, query them back, and read your repo's refs and log over HTTP. It was built with performance benchmark results and artifacts (like profiler outputs) in mind, and this concept will be used extensively in the docs and examples, but the API and data model are unopinionated about what you store and may prove useful for a wider variety of use cases.

        git history                  sidegit
   ─────────────────────────    ─────────────────────────
   commit deadbeef  ──────►     records keyed by deadbeef
     ├─ tree                      ├─ {"latency_ms": 12.3}
     ├─ parent                    ├─ tags {"env": "ci"}
     └─ message                   └─ blobs: profile.pprof, log.txt

v0.1 has no authentication. Run it on a trusted network, behind your VPN, or under an authenticating reverse proxy. Auth lands in a later release.

pip install sidegit

Or run the Docker image:

docker run -p 5000:8080 -v "$PWD:/repo" -e SIDEGIT_REPO_DIR=/repo ghcr.io/itsomri/sidegit:latest

# 1. Start the server (uses ./data for storage, current dir as the git repo)
sidegit serve

# 2. In another shell — attach data to the current commit
COMMIT=$(git rev-parse HEAD)
sidegit create-record "$COMMIT" \
    --data '{"latency_ms": 12.3, "throughput_rps": 4200}' \
    --tag env=ci --tag suite=nightly
# → prints {"id": "...", "commit_hash": "...", ...}

# 3. Attach a file (profiler output, log, anything)
RECORD=$(sidegit list-records --commit-hash "$COMMIT" | jq -r '.[0].id')
sidegit upload-blob "$RECORD" ./profile.pprof

# 4. Read it back
sidegit get-record "$RECORD"
curl http://127.0.0.1:5000/api/records?commit_hash=$COMMIT

records — a thing attached to a commit. There is no limit to the amount of records per commit. In the context of performance testing, a "record" can be thought of as a single execution of a benchmark. Several records of a benchmark can be created in various environments (a local dev machine, a remote server, a CI action, etc), and can be queried independently. Records can be tagged and filtered - for example, a user might want to get all records of a specific benchmark on a specific setup and compare them.

blobs — files attached to a record. In the context of performance benchmarks, this could be the profiler output.

The /api/git/* endpoints return 404 when sidegit isn't pointed at a git repo.

Records are intentionally strictly coupled to a commit. Using a commit_hash (and not general git refs) removes ambiguity - for example, a client might have an outdated local branch. Anything other than a full git SHA is potentially ambiguous.

The CLI smooths this over: when you run sidegit create-record HEAD (or any ref, tag, or short SHA), the CLI shells out to git rev-parse in your local repo, resolves it to the canonical 40-char SHA, and posts that. Resolution happens once, at write time, against the repo you have — so the stored value is permanent.

If you want to stash a release tag or an image digest on the record, put it in tags.

sidegit is configured by a YAML file. Env vars and CLI flags override individual values from the file — useful for injecting secrets at runtime or for one-off overrides without editing the config.

Precedence, later wins: built-in defaults → config file → env vars → CLI flags.

Where the file is read from (first match wins):

1. --config <path> flag
2. SIDEGIT_CONFIG env var
3. ./sidegit.yaml (project-local)
4. /etc/sidegit/config.yaml (system-wide)
5. Built-in defaults if nothing else is found

A full annotated example lives in sidegit.example.yaml. The defaults shown below are what you get with no config file at all:

data_dir: ./data
repo_dir: .

server:
  host: 127.0.0.1
  port: 5000

database:
  url: null            # null → SQLite under {data_dir}/sidegit.db

storage:
  s3_bucket: null      # null → local FS under {data_dir}/blobs
  s3_endpoint_url: null

Use env vars for secrets and per-deployment values you don't want pinned in a file.

See examples/ for a GitHub Actions workflow that records a benchmark on every commit and a pytest-benchmark adapter.

git notes is great for plain text attached to commits, but it doesn't scale to file uploads, has no query API, and isn't accessible from CI environments that don't have your repo cloned. sidegit gives you an HTTP boundary over the same idea.

git clone https://github.com/itsomri/sidegit
cd sidegit
python3 -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
pytest

Apache-2.0 — see LICENSE.