Skip to content

docs: replace the invented examples with measured ones - #86

Merged
yanxue06 merged 1 commit into
mainfrom
docs/readme-rewrite
Aug 12, 2026
Merged

docs: replace the invented examples with measured ones#86
yanxue06 merged 1 commit into
mainfrom
docs/readme-rewrite

Conversation

@yanxue06

@yanxue06 yanxue06 commented Aug 12, 2026

Copy link
Copy Markdown
Owner

Three of the README's four code samples are fabricated. The demo at the top shows "Alice Chen" and "Bob Martinez" committing to a repository that does not exist; the JSON sample reports 48,213 candidates; the tuning section prints a search over the same imaginary history.

A reader evaluating the tool cannot tell any of it from real output — and the real output is more convincing than the invented output was.

Measured, not invented

Everything now comes from runs against a fresh clone of ripgrep, 2,287 commits.

The demo is git log --grep next to the same question asked in English:

$ git log --grep="large files"
139f186 crates/ignore: switch to depth first traversal
714ae82 Add `--max-filesize` option to cli
d06f84c Get rid of special mmap decision on Windows.

$ git-semantic search "searching very large files without loading them into memory"
1. ca058d7 - Add support for memory maps. (0.75 similarity)

Grep returns three commits, none of them the one that answers the question.

Index and query cost are measured too — 16 s to build quick, 83 s full, 4.1 MB and 7.8 MB on disk, 100 ms per query end to end on an M5 Pro. The cargo bench table stays: it measures retrieval in isolation, which is why its numbers are three orders of magnitude smaller, and the two figures now explain the difference instead of quietly disagreeing.

Documents this release

Two corrections

Rust 1.70+ is wrong. The crate is edition 2024 and uses let-chains throughout the index and search paths, so 1.88 is the floor — verified with cargo +1.88 check --all-targets, and now declared as rust-version = "1.88" so cargo reports it instead of failing on a parse error. crates.io shows the MSRV on the crate page as a side effect.

Sub-millisecond retrieval was measuring the graph traversal while the CLI prints a figure that also includes embedding the query. Both were true; together they read as a contradiction.

The LICENSE badge also now links absolutely — crates.io renders this same file and cannot follow a relative path to LICENSE.


Structure and prose are otherwise untouched: the RRF-versus-weighted-blend rationale, the MMR explanation, the tokenizer notes, and the benchmark table are all kept as they were. Diff is +105/−44.

Last of five PRs, on top of #85.

@yanxue06 yanxue06 added documentation Improvements or additions to documentation release labels Aug 12, 2026
Three of the README's four code samples were fabricated. The demo at the
top shows "Alice Chen" and "Bob Martinez" committing to a repository that
does not exist; the JSON sample reports 48,213 candidates; the tuning
section prints a search over the same imaginary history. A reader
evaluating the tool cannot tell any of it from real output, which is
exactly the problem — the real output is more convincing than the
invented output was.

Replaced with runs against a fresh clone of ripgrep, 2,287 commits:

- The demo is now `git log --grep="large files"` next to the same
  question asked in English. Grep returns three commits, none of them
  the mmap commit that answers it.
- The JSON sample is a real document, hash and float precision included.
- Index and query cost are measured, not asserted: 16 s to build quick,
  83 s full, 4.1 MB and 7.8 MB on disk, 100 ms per query end to end.
  The `cargo bench` table stays — it measures retrieval in isolation,
  which is why its numbers are three orders of magnitude smaller, and
  the two now say so instead of quietly disagreeing.

Documents what this release adds and what it stopped requiring:

- Quick Start is one command. `init` and `index` move to "if you want to
  do it ahead of time".
- `git semantic search …` works, and has since the binary was named.
- `completions`, `--before`, and `--force` were undocumented.
- `update` is deprecated and no longer listed.
- Subdirectories, worktrees, and submodules are called out, since until
  this release only the repository root worked.

Corrects two claims. Rust 1.70+ is wrong — the crate is edition 2024 and
uses let-chains, so 1.88 is the floor; verified with `cargo +1.88 check
--all-targets` and declared as `rust-version` so cargo enforces it. And
"sub-millisecond retrieval" was quietly measuring something different
from the millisecond figure the CLI prints.

The LICENSE badge now links absolutely. crates.io renders this file and
cannot follow a relative path.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@yanxue06
yanxue06 force-pushed the docs/readme-rewrite branch from 1d3ea87 to eeb3713 Compare August 12, 2026 08:22
@yanxue06 yanxue06 changed the title docs: rewrite the README around what the tool actually does docs: replace the invented examples with measured ones Aug 12, 2026
@yanxue06
yanxue06 merged commit 8570f1f into main Aug 12, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant