Skip to content

git-prolly CLI

git-prolly is the shell interface to a ProllyTree versioned key-value store. It wraps the Rust VersionedKvStore + SQL layers and is designed to feel like Git — init, set/get, commit, log, branch, checkout, merge, diff, history, sql.

If you'd rather call the library directly, see the Rust API or Python API.

Setup

Install the binary:

cargo install prollytree --features git
git-prolly --help

git-prolly operates inside a git repository. The typical layout is a repo with a dedicated data subdirectory:

mkdir my-project && cd my-project
git init
mkdir data && git-prolly init data
cd data

From here on, commands run from ./data operate on the prolly store. Remote sync (git push, git pull) uses plain Git.

Repository management

init

Initialise a ProllyTree KV store in the current directory (or the given path).

git-prolly init [path]

Key-value operations

set <key> <value>

Stage a key/value pair. The change is persisted but uncommitted.

git-prolly set user:123 "John Doe"
git-prolly set "complex key" "value with spaces"

get <key>

Retrieve a value.

git-prolly get user:123
# → John Doe

delete <key>

Stage a deletion.

git-prolly delete user:123

list [--values] [--graph]

List keys. --values prints each value; --graph prints the tree structure.

git-prolly list
git-prolly list --values
git-prolly list --graph

Version control

status

Show staged changes not yet committed.

git-prolly status
# Staged changes:
#   added: config:theme
#   modified: user:123
#   deleted: user:456

commit -m "<message>"

Commit staged changes. Creates a real Git commit on the current branch.

git-prolly commit -m "Initial user data"

log [--limit N] [--kv-summary]

Show commit history.

git-prolly log
git-prolly log --limit 5
git-prolly log --kv-summary
# f1e2d3c4 - 2024-01-15 10:30:00 - Initial data (+2 ~1 -0)

show <commit> [--keys-only]

Detail view of a commit.

git-prolly show HEAD
git-prolly show HEAD --keys-only

revert <commit>

Create a new commit that undoes the changes from <commit>.

git-prolly revert f1e2d3c4

Branching and merging

Branching uses native Git branches; the prolly store tracks them.

git checkout -b feature/darkmode
git-prolly set config:theme dark
git-prolly commit -m "Enable dark mode"

git checkout main
git-prolly merge feature/darkmode

merge <branch>

Three-way merge at the key-value level. See Theory → Versioning & Merge for the algorithm. Conflicting keys are resolved using the default strategy; use the Rust/Python API for custom resolvers.

Diff and history

diff <from> <to> [--format <fmt>] [--keys <pattern>]

git-prolly diff main feature/darkmode
git-prolly diff main feature/darkmode --format=detailed
git-prolly diff main feature/darkmode --format=json
git-prolly diff main feature/darkmode --keys "config:*"

Formats: compact (default), detailed, json.

history <key> [--format <fmt>] [--limit N]

Show every commit that touched <key>.

git-prolly history user:123
git-prolly history user:123 --format=detailed
git-prolly history user:123 --limit=5 --format=json

keys-at <ref> [--values] [--format <fmt>]

List keys (optionally with values) that exist at a given commit or branch.

git-prolly keys-at HEAD
git-prolly keys-at v1.0 --values
git-prolly keys-at a1b2c3d4 --format=json

stats [<commit>]

Summary statistics — total keys, commits, current branch.

git-prolly stats
git-prolly stats c3d4e5f6

SQL

git-prolly sql runs GlueSQL queries against the store. See the SQL Interface for the full surface.

git-prolly sql "CREATE TABLE users (id INTEGER, name TEXT)"
git-prolly sql "INSERT INTO users VALUES (1, 'Alice')"
git-prolly sql "SELECT * FROM users"
git-prolly sql -f schema.sql
git-prolly sql -i                                 # interactive shell
git-prolly sql -b v1.0 "SELECT COUNT(*) FROM users"   # read-only, historical
git-prolly sql -o json "SELECT * FROM users"

Output formats

Where a subcommand accepts --format:

  • compact / default — one-line per row.
  • detailed — multi-line block per row.
  • json — machine-readable; best shape for jq, CI, or programmatic callers.
  • csv — SQL only.

Setting MEMOIR_*-style env vars isn't a thing here; pass --format json explicitly when scripting.

Integration with plain Git

Because the store is a Git repository underneath, everything Git knows how to do still works:

# Push to a remote
git remote add origin git@github.com:you/mystore.git
git push -u origin main

# Clone elsewhere
git clone git@github.com:you/mystore.git
cd mystore && git-prolly list --values

You can also combine the two: use git log/git blame for the commit graph, and git-prolly history <key> for per-key history.

Troubleshooting

  • "Repository not found." Run git-prolly init in the directory, or check that you're inside the data/ subdirectory of your git repo.
  • "Cannot use -b/--branch parameter with uncommitted staging changes." Commit or discard staged changes before running a branch-scoped SQL query.
  • "Only SELECT statements are allowed when using -b/--branch." Historical commits are read-only. Switch to the target branch first if you need to write.
  • Pre-commit / hook failures. The store is a plain Git repo — the usual git config, hook setup, and git reset apply.

For a richer walkthrough see Basic Usage and the Versioned Store example.