docs: replace the invented examples with measured ones - #86
Merged
Conversation
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
force-pushed
the
docs/readme-rewrite
branch
from
August 12, 2026 08:22
1d3ea87 to
eeb3713
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 --grepnext to the same question asked in English: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 benchtable 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
searchbootstraps itself (feat(cli): search bootstraps itself on first use #84).initandindexmove down to "if you want to do it ahead of time".git semantic search …works, and has since the day the binary was namedgit-semantic. The README never said so.completions(feat(cli): shell completions #83),--before, and--forcewere undocumented.updateis deprecated and no longer listed.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 withcargo +1.88 check --all-targets, and now declared asrust-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 retrievalwas 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.