UGREP-INDEXER(1)

📦
version 7.8.5 · 6 versions
, in arch rolling, nixpkgs unstable

💅 UGREP-INDEXER — like, the manual page for ugrep-indexer(1) (User Commands, bestie)

okay so real talk: this is the manual for ugrep-indexer, the file indexer that makes recursive searching go zoom. it lives in section 1 of the manual, and by the end of this you're gonna know it intimately. 🫶

✨ NAME ✨

ugrep-indexer — the file indexer that accelerates recursive searching. literally its whole personality. 🦋

✨ SYNOPSIS ✨

ugrep-indexer [-0...9] [-c|-d|-f] [-I] [-q] [-S] [-s] [-X] [-z] [PATH]

🌸 DESCRIPTION 🌸

so. the ugrep-indexer utility recursively indexes your files so that recursive searching with the ug --index PATTERN commands gets a serious glow-up:

$ ugrep-indexer [-I] [-z]

  ...

$ ug --index [-I] [-z] [-r|-R] OPTIONS PATTERN

$ ugrep --index [-I] [-z] [-r|-R] OPTIONS PATTERN

quick vocab check: option -I or --ignore-binary ignores binary files, and honestly it's recommended — it limits your indexing storage overhead AND reduces search time. icon behavior. and option -z or --decompress indexes and searches archives and compressed files. 🎀

indexing speeds up searching on file systems that are large and cold (like, not recently cached in RAM, sad for them) and file systems that are just generally slow to search. but ngl, indexing may not speed up searching when it's only a few files, or when you're recursively searching fast file systems. know your audience. 💅

searching with ug --index is safe and never skips modified files that may match after indexing — the ug --index PATTERN command always searches files and directories that were added or modified after indexing. periodt. and when option --stats is used with ug --index, you get a search report showing the number of files skipped that didn't match any indexes, plus the number of files and directories that were added or modified after indexing. so informative. when option --stats is used with ug --index, a search report is produced showing the number of files skipped not matching any indexes and the number of files and directories that were added or modified after indexing.

⚠️ heads up bestie — searching with ug --index may significantly increase the start-up time when you specify complex regex patterns that contain large Unicode character classes combined with * or + repeats. those should be avoided. fr fr, don't do it.

ugrep-indexer stores a hidden index file in each directory indexed. the size of an index file depends on the number of files indexed and the specified indexing accuracy. higher accuracy = larger index files, but better search performance because it reduces false positives. and what even is a false positive? it's a match prediction for a file when the file doesn't actually match the regex pattern. rude, honestly. 😭

ugrep-indexer accepts an optional PATH to the root of the directory tree to index. the default is to index the working directory tree. cozy.

ugrep-indexer incrementally updates indexes. to force reindexing, specify option -f or --force. indexes are deleted with option -d or --delete. clean slate energy. 🧚

ugrep-indexer may be stopped and restarted to continue indexing at any time. incomplete index files do not cause errors. we love a resilient queen. 👑

ASCII, UTF-8, UTF-16 and UTF-32 files are indexed and searched as text files — unless their UTF encoding is invalid, in which case, yikes, they're not. files with other encodings are indexed as binary files and can be searched with non-Unicode regex patterns using ug --index -U.

when ugrep-indexer option -I or --ignore-binary is specified, binary files are ignored and not indexed. so avoid searching those non-indexed binary files with ug --index -I using option -I. consistency is key bestie.

ugrep-indexer option -X or --ignore-files respects gitignore rules. likewise, avoid searching non-indexed ignored files with ug --index --ignore-files using option --ignore-files. 😌

archives and compressed files are indexed with ugrep-indexer option -z or --decompress. otherwise, archives and compressed files are indexed as binary files, or are ignored with option -I or --ignore-binary.

🚨 okay important: once an archive or compressed file is indexed as a binary file, it will not be reindexed with option -z to index the contents of the archive or compressed file. only files that are modified after indexing are reindexed, and that's determined by comparing time stamps. so if you mess up the order, that's just your life now. 💀

symlinked files are indexed with ugrep-indexer option -S or --dereference-files. symlinks to directories are never followed. boundaries, bestie. ✋

to save a log file of the indexing process, specify option -v or --verbose and redirect standard output to a log file. all messages and warnings are sent to standard output and captured by the log file. cute AND useful. 🌈

a .ugrep-indexer configuration file with configuration options is loaded when present in the working directory or in the home directory. a configuration option consists of the name of a long option and its argument when applicable. 🍓

the following options are available:

✨ OPTIONS ✨

  • -0, -1, -2, -3, ..., -9, --accuracy=DIGIT — specifies indexing accuracy. a low accuracy reduces the indexing storage overhead at the cost of a higher rate of false positive pattern matches (aka more noise 🙈). a high accuracy reduces the rate of false positive regex pattern matches (less noise, slay) at the cost of increased indexing storage overhead. an accuracy between 2 and 7 is recommended. the default accuracy is 4.
  • -., --hidden — index hidden files and directories. yes, even the shy ones. 👀
  • -?, --help — display a help message and exit.
  • -c, --check — recursively check and report indexes without reindexing files. just looking respectfully.
  • -d, --delete — recursively remove index files. bye bye 💅
  • -f, --force — force reindexing of files, even those that are already indexed. no file left behind.
  • -I, --ignore-binary — do not index binary files. the recommended vibe.
  • -q, --quiet, --silent — quiet mode: do not display indexing statistics. shhh 🤫
  • -S, --dereference-files — follow symbolic links to files. symbolic links to directories are never followed. again: boundaries.
  • -s, --no-messages — silent mode: nonexistent and unreadable files are ignored, i.e. their error messages and warnings are suppressed. ignorance is bliss 🧚
  • -V, --version — display version and exit.
  • -v, --verbose — produce verbose output. files are marked A for archive, C for compressed, and B for binary or I for ignored binary. deletions are marked D. iykyk 🦋
  • -X, --ignore-files, --ignore-files=FILE — do not index files and directories matching the globs in FILE encountered during indexing. the default FILE is .gitignore. this option may be repeated to specify additional files. stack 'em up. 🎀
  • -z, --decompress — index the contents of compressed files and archives. hidden files in archives are ignored unless option -. or --hidden is specified. option -I or --ignore-binary ignores compressed binary files. when used with option --zmax=NUM, indexes the contents of compressed files and archives stored within archives up to NUM levels deep. supported compression formats: gzip (.gz), compress (.Z), zip, 7z, bzip2 (requires suffix .bz, .bz2, .bzip2, .tbz, .tbz2, .tb2, .tz2), lzma and xz (requires suffix .lzma, .tlz, .xz, .txz), lz4 (requires suffix .lz4), zstd (requires suffix .zst, .zstd, .tzst), brotli (requires suffix .br), bzip3 (requires suffix .bz3). a whole alphabet of formats, we love to see it. 🔥
  • --zmax=NUM — when used with option -z (--decompress), indexes the contents of compressed files and archives stored within archives by up to NUM expansion levels deep. the default --zmax=1 only permits indexing uncompressed files stored in cpio, pax, tar, zip and 7z archives; compressed files and archives are detected as binary files and are effectively ignored. specify --zmax=2 to index compressed files and archives stored in cpio, pax, tar, zip and 7z archives. NUM may range from 1 to 99 for up to 99 decompression and de-archiving steps. increasing NUM values gradually degrades performance. you've been warned, bestie. 😭

💜 EXIT STATUS 💜

the ugrep-indexer utility exits with one of the following values:

  1. 0 — indexes are up to date. ✨
  2. 1 — indexing check -c detected missing and outdated index files. 😬

🌟 EXAMPLES 🌟

recursively and incrementally index all non-binary files showing progress:

$ ugrep-indexer -I -v

recursively and incrementally index all non-binary files, including non-binary files stored in archives and in compressed files, showing progress:

$ ugrep-indexer -z -I -v

incrementally index all non-binary files, including archives and compressed files, show progress, follow symbolic links to files (but not to directories), but do not index files and directories matching the globs in .gitignore:

$ ugrep-indexer -z -I -v -S -X

force re-indexing of all non-binary files, including archives and compressed files, follow symbolic links to files (but not to directories), but do not index files and directories matching the globs in .gitignore:

$ ugrep-indexer -f -z -I -v -S -X

same, but decrease index file storage to a minimum by decreasing indexing accuracy from 4 (the default) to 0:

$ ugrep-indexer -f -0 -z -I -v -S -X

increase search performance by increasing the indexing accuracy from 4 (the default) to 7 at a cost of larger index files:

$ ugrep-indexer -f7zIvSX

recursively delete all hidden ._UG#_Store index files to restore the directory tree to non-indexed:

$ ugrep-indexer -d

copyright (c) 2021-2025 Robert A. van Engelen <engelen@acm.org>

ugrep-indexer is released under the BSD-3 license. all parts of the software have reasonable copyright terms permitting free redistribution. this includes the ability to reuse all or parts of the ugrep source tree. generous king. 🫶

🦋 SEE ALSO 🦋

ug(1), ugrep(1).

🌸 BUGS 🌸

report bugs at:

https://github.com/Genivia/ugrep-indexer/issues

and that's the whole page, bestie — you ate that 💅

this was ugrep-indexer version 7.8.5, dated September 15, 2026, from the UGREP-INDEXER(1) manual, section 1 (User Commands). go index something and make me proud. 🎀✨

📦 where this page comes from