Cleaning Up ripgrep's README: Removing Shell Prompt Prefixes from Code Blocks

Contents

The ripgrep README had a subtle usability issue: 41 code blocks prefixed their commands with $ , the shell prompt indicator. While common in tutorials, these prefixes create friction — users who copy-paste commands get $ : command not found errors.

Repo: BurntSushi/ripgrep Issue: #3323 PR: #3437 Status: PR-submitted Fix scope: 41 lines changed in README.md

The Problem

Code blocks in the ripgrep README looked like this:

$ rg --type-list | head -5
    asm: *.asm, *.s, *.S
    asp: *.asp
    aspx: *.aspx, *.cshtml, *.vbhtml
    awk: *.awk

The $ prefix signals “this is a terminal command” in Markdown. But it’s not executable — it’s a visual convention. When users copy the block and paste into a terminal, the shell tries to execute $ as a command:

$ $ rg --type-list
$ : command not found

This is a well-documented anti-pattern in technical writing. The Arch Wiki and Google Developer Documentation Style Guide both recommend omitting shell prompts from copy-pasteable code blocks.

The Fix

Remove the $ prefix from all 41 code blocks in README.md. The change is purely cosmetic — no code logic, no build system, no tests affected.

- $ rg --type-list | head -5
+ rg --type-list | head -5

All 41 lines had the $ prefix removed, including the installation line containing $(arch). The shell variable expansion works correctly without the prompt prefix:

# Before
$ curl -LO $(arch)/ripgrep.deb

# After
curl -LO $(arch)/ripgrep.deb

Why This Matters

ripgrep is one of the most-used CLI tools in software development — 100k+ GitHub stars, installed on millions of developer machines. Its README is the first touchpoint for new users.

Small documentation friction compounds at scale. A user encountering a copy-paste error on their first interaction with ripgrep forms a negative first impression. Removing shell prompts eliminates this entirely.

The maintainer (BurntSushi) had previously kept the prefixes intentionally but commented they were “open to reconsidering this” — making this a well-scoped, maintainer-aligned contribution.

Pattern: Detecting Shell Prompt Prefixes in Documentation

Automated check

# Find code blocks with shell prompt prefixes
grep -n '^$ ' README.md | wc -l

When to remove vs. keep

Pattern	Action	Reason
`$ command`	Remove prefix	Copy-pasteable command
`$ command` with output below	Keep or use two blocks	Prompt distinguishes input from output
`$(variable)`	Keep as-is	Shell variable, not a prompt
`# comment`	Keep	Root prompt, indicates privilege level

The key distinction: if the $ is followed by a space and then a command, it’s a prompt prefix. If it’s part of $(...) or $VAR, it’s shell syntax.

Contribution Notes

This fix follows the “small PR” strategy that maximizes merge probability:

41 lines changed — well under the 20-line-per-hunk threshold
Documentation only — zero risk of introducing bugs
Maintainer-aligned — issue explicitly marked as open for reconsideration
No test changes needed — README changes don’t affect test suites

The PR was opened against the default branch with a clear description linking to the original issue.

References

NoCode Insider — AI workflow automation with no-code tools, agents, and APIs

Cross-links automatically generated from CodeIntel Log.