Skip to content

CLI Tools en

Jump to bottom
Won-Kyu Park edited this page Aug 4, 2026 · 2 revisions

CLI Tools

The command-line scripts live under tools/. Run any of them from the repo root with uv run tools/<name>.py. Handy when you want to poke at the library from a terminal instead of writing Python.

srcs_commit.py — commit a file

uv run tools/srcs_commit.py my_doc.txt -m "initial commit"
  • content_file (required) — the source file to commit
  • rcs_file (optional) — path to the .srcs file. If omitted, it's placed at .srcs/<filename>.srcs automatically
  • -m/--message (required) — commit log message
  • -a/--author — defaults to $USER
  • --no-sign — skip GPG signing
  • --binary — force a binary commit even if the content is decodable as text
  • --srcs-dir — directory to use for auto-placement (default .srcs)

The file is read as bytes first, then committed as text if there's no NUL byte in the first 8KB and it decodes as UTF-8 (the same heuristic git uses to distinguish text from binary). That decision happens in this script, not the library — SimpleRCS.commit() itself takes any bytes straight down the binary path, no auto-detection.

srcs_log.py — view history

uv run tools/srcs_log.py my_doc.txt.srcs
uv run tools/srcs_log.py my_doc.txt.srcs -n 5 --reverse --show-signature
  • -n/--limit — show only the most recent N commits
  • -r/--reverse — oldest first
  • --show-signature — also verify GPG signatures

srcs_diff.py — diff between versions

uv run tools/srcs_diff.py my_doc.txt.srcs -r 1.1:1.3
uv run tools/srcs_diff.py my_doc.txt.srcs --engine ses
  • -r/--revision — '1.1' (compare against HEAD) or '1.1:1.2' (compare two specific versions)
  • --engine — difflib (default) / pydifflib / myers / ses / dmp. The ses/dmp engines only work if the Cython extensions have been built

This is the tool for actually eyeballing the difference between the diff algorithms discussed in Diff Engines.

srcs_blame.py — per-line authorship

uv run tools/srcs_blame.py my_doc.txt
uv run tools/srcs_blame.py my_doc.txt --depth 10
  • content_file — the source file (or you can point it directly at a .srcs file)
  • rcs_file (optional) — explicit .srcs path
  • --srcs-dir — auto-discovery directory (default .srcs)
  • --depth — only walk back this many versions; anything older gets attributed to the oldest version reached

Doesn't work if HEAD is binary — there's no such thing as a "line" there.

srcs_verify.py — integrity check

uv run tools/srcs_verify.py my_doc.txt.srcs

Verifies the entire hash chain and any GPG signatures. On failure, exits with code 1 and prints ❌ VERIFICATION FAILED.

srcs_sign_head.py — sign HEAD

uv run tools/srcs_sign_head.py my_doc.txt.srcs -s <GPG_KEY_ID>
  • -s/--signer — GPG key ID of the signer. Pass it multiple times for multiple signatures
  • Falls back to the SRCS_SIGNING_KEY environment variable if not specified
  • Doesn't work on v1 files — signing is v2-only

bench_diff.py — diff engine benchmark

uv run tools/bench_diff.py
uv run tools/bench_diff.py --size 500 --diff-ratio 0.1 --runs 5
  • --size (KB) — size of the synthetic test data
  • --diff-ratio — fraction of content that differs between the two inputs
  • --file-a/--file-b — use real files instead of synthetic data
  • --runs — number of repetitions (for averaging/min)
  • --skip — exclude specific engines

Reports both timing and peak memory (tracemalloc). Compares pure-Python Myers, Cython SES/DMP, StreamSequenceMatcher, StreamTextSequenceMatcher, and standard difflib all at once.

compare_memory_usage.py

A standalone memory-comparison utility. Since bench_diff.py already measures memory too, there's not much reason to reach for this one separately anymore.

Clone this wiki locally