lets find

Searches files or directories and prints hits as path:line, grouped by file. locate is an alias for the same command.

lets find [OPTIONS] <PATTERN> [PATHS]...

What it does

Regex search by default (Rust regex syntax), walked with the same rules as ripgrep: .gitignore, .ignore, the global gitignore and .git/info/exclude are honored, and hidden files are skipped unless asked for. Capped at 50 hits by default — over the cap, no hit lines are printed; instead a bounded map of the files holding the most hits, so the next call can narrow to one of them. Replaces grep -rn and rg run directly in the shell.

Flags

Grep-compatible no-ops, accepted so a command copied from grep runs unchanged: -n, --line-number, -r, -R, -E, -H (find already behaves as if each were set). -v, --invert-match has no equivalent — find only ever prints matching lines — so it is refused at parse time, exit 64 ERROR_CODE=usage.

Output shape

Under the cap:

── <path>
<n>:	<line with the match wrapped in «»>
<n>-	<context line>
── <H> hits in <F> files · searched <S> files[ · ignored …][ · skipped …][ · glob …]

Over the cap, no hit lines print. Instead:

<count>	<path>
...
── <H> hits in <F> files · over the 50-hit cap · narrow the pattern or the paths, or --files · top 10 files shown

• Matches are wrapped in «» so they survive a pipe.
• --files prints one bare path per line, no header, no line numbers, then the ordinary footer.
• --count prints the footer first, then <count> <path> rows, count right-aligned to the widest.
• A path that does not exist is named in the footer alongside what the other paths produced: · nope failed (not_found).
• A file with a NUL byte, or a UTF-16 file, is not text and is not searched; it is counted in skipped N (binary a · too large b · unreadable c).
• A regex holding one of grep’s BRE escapes (\|, \(, \), \{, \}, \+, \?) that matches nothing is retried read grep-style, and the footer names the reading used: · «A\|B» had no hits, read grep-style as «A|B».

Exit codes

Examples

A basic search, hits wrapped so they survive a pipe:

$ lets find usageCap
── src/config.ts
1:  export const «usageCap» = 10
── src/usage.ts
1:  import { «usageCap» } from './config'
── 2 hits in 2 files · searched 3 files · ~17 tokens

Two patterns at once, with context:

$ lets find 'Bottom line|Next' small.md
── small.md
 5:	## «Bottom line»
13:	## «Next»
── 2 hits in 1 file · searched 1 file

Over the cap: no hits printed, a map of where they are instead, exit 1:

$ lets find needle many-hits.txt
? 1
64	many-hits.txt
── 64 hits in 1 file · searched 1 file · over the 50-hit cap · narrow the pattern or the paths, or --files · top 1 file shown
ERROR_CODE=over_cap

Narrowing the walk with a glob, and the control with no glob:

$ lets find -g '*.ts' needle
── a.ts
1:	const «needle» = 1;
── 1 hit in 1 file · searched 1 file · glob *.ts

$ lets find needle
── a.ts
1:	const «needle» = 1;
── b.py
1:	«needle» = 1
── 2 hits in 2 files · searched 2 files

--files and --count shapes:

$ lets find filler . --files
big.ts
store.go
── 2 files · searched 5 files · ignored 3 (gitignore 1 · hidden 2) · skipped 1 (binary 1)

$ lets find filler . --count
── 393 hits in 2 files · ignored 3 (gitignore 1 · hidden 2) · skipped 1 (binary 1)
185  big.ts
208  store.go

No hits still prints a footer and exits 1, rather than staying silent:

$ lets find zzz_never_appears_zzz small.md
? 1
── 0 hits in 0 files · searched 1 file
no hits for «zzz_never_appears_zzz»
ERROR_CODE=not_found