Provided by: ugrep_7.2.1+dfsg-1_amd64 bug

NAME

       ugrep-indexer -- file indexer to accelerate recursive searching

SYNOPSIS

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

DESCRIPTION

       The ugrep-indexer utility recursively indexes files to accelerate recursive searching with the ug --index
       PATTERN commands:

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

                ...

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

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

       where  option  -I or --ignore-binary ignores binary files, which is recommended to limit indexing storage
       overhead and to reduce search time.   Option  -z  or  --decompress  indexes  and  searches  archives  and
       compressed files.

       Indexing  speeds  up searching file systems that are large and cold (not recently cached in RAM) and file
       systems that are generally slow to search.  Note that indexing may not speed up searching  few  files  or
       recursively searching fast file systems.

       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.
       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.  Note that searching with ug --index may significantly increase the  start-up  time  when
       complex  regex  patterns  are specified that contain large Unicode character classes combined with `*' or
       `+' repeats, which should be avoided.

       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 produces  larger  index
       files  to  improve search performance by reducing false positives (a false positive is a match prediction
       for a file when the file does not match the regex pattern.)

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

       ugrep-indexer incrementally updates indexes.  To force reindexing, specify option -f or --force.  Indexes
       are deleted with option -d or --delete.

       ugrep-indexer  may  be stopped and restarted to continue indexing at any time.  Incomplete index files do
       not cause errors.

       ASCII, UTF-8, UTF-16 and UTF-32 files are indexed and searched as text files unless their UTF encoding is
       invalid.  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.
       Avoid searching these non-indexed binary files with ug --index -I using option -I.

       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.   Note  that  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, which is determined by comparing time stamps.

       Symlinked files are indexed with ugrep-indexer option -S or --dereference-files.  Symlinks to directories
       are never followed.

       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.

       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:

       -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 (more noise).  A high accuracy reduces the rate of
              false positive regex pattern matches (less noise) at the cost of  an  increased  indexing  storage
              overhead.  An accuracy between 2 and 7 is recommended.  The default accuracy is 4.

       -., --hidden
              Index hidden files and directories.

       -?, --help
              Display a help message and exit.

       -c, --check
              Recursively check and report indexes without reindexing files.

       -d, --delete
              Recursively remove index files.

       -f, --force
              Force reindexing of files, even those that are already indexed.

       -I, --ignore-binary
              Do not index binary files.

       -q, --quiet, --silent
              Quiet mode: do not display indexing statistics.

       -S, --dereference-files
              Follow symbolic links to files.  Symbolic links to directories are never followed.

       -s, --no-messages
              Silent mode: nonexistent and unreadable files are ignored, i.e.  their error messages and warnings
              are suppressed.

       -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.

       -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.

       -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).

       --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.

EXIT STATUS

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

       0      Indexes are up to date.

       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

       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.

SEE ALSO

       ug(1), ugrep(1).

BUGS

       Report bugs at:

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

ugrep-indexer 7.2.1                             January 27, 2025                                UGREP-INDEXER(1)