Skip to content

Trim the README and move detail into docs - #12

Open
hmirin wants to merge 7 commits into
mainfrom
readme-trim
Open

hmirin wants to merge 7 commits into
mainfrom
readme-trim

Conversation

@hmirin

@hmirin hmirin commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

README goes from 392 to 235 lines without dropping any claim.

  • New figure docs/art/pillars.svg: Fast (data sent per one-line push, log scale), Safe (compare-and-swap rejects the losing push), No master key (fresh key per push and device; a revoked device gets none afterwards). Each pillar now sits next to its evidence.
  • The standalone Performance section is gone; docs/benchmarks.md already holds the full table and the reproduce script. The "At a glance" table is gone too.
  • Quick start gains a one-line clone example.
  • How it compares: one short table plus "pick something else when". The full tables with all 16 notes move verbatim to docs/comparison.md.
  • Security model: a two-paragraph summary. The full text moves verbatim to docs/security-model.md; SECURITY.md links there.

Docs-only change; relative links and anchors checked with a script.

State the benchmark numbers once, reach Quick start sooner, and add a
clone example. Keep a short comparison table and security summary in the
README; the full comparison with footnotes and the full security model
move to docs/comparison.md and docs/security-model.md.
The fast/safe/no-master-key claims now sit next to their evidence in a
single SVG. The standalone Performance table is dropped from the README;
docs/benchmarks.md already holds the full results and the reproduce script.
The 5,272 MiB figure came from a benchmark receiver with
receive.unpackLimit=0. With default settings a small gcrypt push is
unpacked and deduplicated on the host, so storage need not grow, even
though the whole history is still transferred. Show fetch time instead,
and say why gcrypt re-uploads: each state is a new parentless commit.
Fast now shows data sent, small-change and whole-history times, and peak
memory as bar charts, including where git-remote-e2ee is slower or uses
more memory. Safe and No master key sit below it.
It measured a receiver configured with receive.unpackLimit=0, which keeps
every received pack. With Git's defaults a host can discard duplicate
objects, so the row overstated gcrypt's lasting storage cost. The upload
size row still shows what each push transfers.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant