gitsheets

A git-backed document store for low-volume, high-touch, human-scale data.

Records are TOML files in a git repo, organized by a per-sheet path template. Every mutation is a commit — the commit log is the audit log. Schemas live alongside the data; validation runs on every write. Branches give you propose-review workflows for free.

npm install gitsheets

Targets Node.js ≥ 20 and Bun ≥ 1. ESM-only. CLI installs as gitsheets and git-sheet.

Get started

• Quick start — npm install gitsheets, declare a sheet, write a record, read it back. ≤ 5 minutes.
• Concepts — Repository, Sheet, Path Template, Transaction, Store, Index, Push Daemon. The vocabulary every consumer needs.

Reference

• CLI reference — git sheet <command>, global flags, exit codes.
• API reference — public exports + pointers into the per-symbol spec.
• gitsheets-axi — the agent-facing companion CLI (TOON output, idempotent mutations, session hooks).
• Path templates — syntax, recursive fields, query pruning, invalid-char handling.
• Validation — JSON Schema in .gitsheets/<sheet>.toml, optional Standard Schema layering.
• Sync and merge — repo.sync() takes in other writers’ commits under the write lock; repo.merge() / git sheet merge merges two branches record-by-record with canonical output, and git sheet merge --install-driver makes plain git merge do the same.

Recipes

• Typed sheet with Zod — Standard Schema validator threading, type-safe upsert/query.
• Request-bound transactions in Fastify — one commit per HTTP request, with structured trailers.
• Secondary indices — in-memory findByEmail / findByForeignKey patterns.
• Production push daemon — backoff config, auth strategies, monitoring.
• Markdown CMS pattern — content-typed sheets: records as .md with TOML frontmatter; lazy body loading.
• Migrating a [gitsheet.fields] config — pre-v1.0 → v1.0 schema migration.

Migrating

The migration guide covers every version step with a behavior change: pre-v1.0 → v1.0, v1.x → v2.0 (the Rust core), and v2.7 → v2.9 (template fields must be schema-required; injectedFields removed).

Where the contracts live

specs/ is the source of truth. The docs you’re reading are the consumer-facing tour; the specs are the authoritative API + behavior contract. When in doubt, the spec wins. The decisive rules behind the unspecified cases — the project’s principles — are in specs/principles.md.

License

Apache-2.0. See LICENSE.