.TH UGREP "1" "September 15, 2026" "ugrep 7.8.5" "User Commands"
.SH NAME
\fBugrep\fR, \fBug\fR -- file pattern searcher
.SH SYNOPSIS
.B ugrep
[\fIOPTIONS\fR] [\fB-i\fR|\fB-j\fR] [\fB-Q\fR|\fIPATTERN\fR] [\fB-e\fR \fIPATTERN\fR] [\fB-N\fR \fIPATTERN\fR] [\fB-f\fR \fIFILE\fR]
      [\fB-E\fR|\fB-F\fR|\fB-G\fR|\fB-P\fR|\fB-Z\fR] [\fB-U\fR] [\fB-m\fR [\fIMIN,\fR][\fIMAX\fR]] [\fB--bool\fR [\fB--files\fR|\fB--lines\fR]]
      [\fB-r\fR|\fB-R\fR|\fB-1\fR|...|\fB-9\fR|\fB-10\fR|\fB-11\fR|...] [\fB-t\fR \fITYPES\fR] [\fB-g\fR \fIGLOBS\fR] [\fB--sort\fR[=\fIKEY\fR]]
      [\fB-q\fR|\fB-l\fR|\fB-c\fR|\fB-o\fR] [\fB-v\fR] [\fB-n\fR] [\fB-k\fR] [\fB-b\fR] [\fB-A\fR \fINUM\fR] [\fB-B\fR \fINUM\fR] [\fB-C \fR\fINUM\fR] [\fB-y\fR]
      [\fB--color\fR[=\fIWHEN\fR]|\fB--colour\fR[=\fIWHEN\fR]] [\fB--pretty\fR] [\fB--pager\fR[=\fICOMMAND\fR]]
      [\fB--hexdump\fR|\fB--csv\fR|\fB--json\fR|\fB--xml\fR] [\fB-I\fR] [\fB-z\fR] [\fB--zmax\fR=\fINUM\fR] [\fIFILE\fR \fI...\fR]
.SH DESCRIPTION
The \fBugrep\fR utility searches any given input files, selecting files and
lines that match one or more patterns specified as regular expressions or as
fixed strings.  A pattern matches multiple input lines when the pattern's
regular expression matches one or more newlines.  An empty pattern matches
every line.  Each input line that matches at least one of the patterns is
written to the standard output.
.PP
The \fBug\fR command is intended for interactive searching, using a `.ugrep'
configuration file located in the working directory or, if not found, in the
home directory, see CONFIGURATION.  \fBug\fR is equivalent to \fBugrep --config
--pretty --sort\fR to load a configuration file, enhance the terminal output,
and to sort files by name.
.PP
The \fBugrep+\fR and \fBug+\fR commands are the same as the \fBugrep\fR and
\fBug\fR commands, but also use filters to search pdfs, documents, e-books,
and image metadata, when the corresponding filter tools are installed.
.PP
A list of matching files is produced with option \fB-l\fR
(\fB--files-with-matches\fR).  Option \fB-c\fR (\fB--count\fR) counts the
number of matching lines.  When combined with option \fB-o\fR, counts the total
number of matches.  When combined with option \fB-m1,\fR (\fB--min-count=1\fR),
skips files with zero matches.
.PP
The default pattern syntax is an extended form of the POSIX ERE syntax, same as
option \fB-E\fR (\fB--extended-regexp\fR).  Try \fBug --help regex\fR for help
with pattern syntax and how to use logical connectives to specify Boolean
search queries with option \fB-%\fR (\fB--bool\fR) to match lines and \fB-%%\fR
(\fB--bool --files\fR) to match files.  Options \fB-F\fR
(\fB--fixed-strings\fR), \fB-G\fR (\fB--basic-regexp\fR) and \fB-P\fR
(\fB--perl-regexp\fR) specify other pattern syntaxes.
.PP
Option \fB-i\fR (\fB--ignore-case\fR) ignores letter case in patterns.  Option
\fB-j\fR (\fB--smart-case\fR) enables \fB-i\fR only if the search patterns are
specified in lower case.
.PP
Fuzzy (approximate) search is specified with option \fB-Z\fR (\fB--fuzzy\fR)
with an optional argument to control character insertions, deletions, and/or
substitutions.  Try \fBug --help fuzzy\fR for help with fuzzy search.
.PP
Note that pattern `.' matches any non-newline character.  Pattern `\\n' matches
a newline character.  Multiple lines may be matched with patterns that match
one or more newline characters.
.PP
The empty pattern "" matches all lines.  Other empty-matching patterns do not.
For example, the pattern `a*' will match one or more a's.  Option \fB-Y\fR
forces empty matches for compatibility with other grep tools.  
.PP
Option \fB-f\fR \fIFILE\fR matches patterns specified in \fIFILE\fR.
.PP
By default Unicode patterns are matched.  Option \fB-U\fR (\fB--ascii\fR or
\fB--binary\fR) disables Unicode matching for ASCII and binary pattern
matching.  Non-Unicode matching is more efficient.
.PP
\fBugrep\fR accepts input of various encoding formats and normalizes the output
to UTF-8.  When a UTF byte order mark is present in the input, the input is
automatically normalized.  An input encoding format may be specified with
option \fB--encoding\fR.
.PP
If no \fIFILE\fR arguments are specified and standard input is read from a
terminal, recursive searches are performed as if \fB-r\fR is specified.  To
force reading from standard input, specify `-' as a \fIFILE\fR argument.
.PP
Directories specified as \fIFILE\fR arguments are searched without recursing
deeper into subdirectories, unless \fB-R\fR, \fB-r\fR, or \fB-2\fR...\fB-9\fR
is specified to search subdirectories recursively (up to the specified depth.)
.PP
Option \fB-I\fR (\fB--ignore-binary\fR) ignores binary files.  A binary file is
a file with non-text content.  A file with zero bytes or invalid UTF formatting
is considered binary.
.PP
Hidden files and directories are ignored in recursive searches.  Option
\fB-.\fR (\fB--hidden\fR) includes hidden files and directories in recursive
searches.
.PP
To match the names of files to search and the names of directories to recurse,
one or more of the following options may be specified.  Option \fB-O\fR
specifies one or more filename extensions to match.  Option \fB-t\fR specifies
one or more file types to search (\fB-t list\fR outputs a list of types.)
Option \fB-g\fR specifies a gitignore-style glob pattern to match filenames.
Option \fB--ignore-files\fR specifies a file with gitignore-style globs to
ignore directories and files.  Try \fBug --help globs\fR for help with filename
and directory name matching.  See also section GLOBBING.
.PP
Compressed files and archives are searched with option \fB-z\fR
(\fB--decompress\fR).  When used with option \fB--zmax\fR=\fINUM\fR, searches
the contents of compressed files and archives stored within archives up to
\fINUM\fR levels.
.PP
Output to a terminal for viewing is enhanced with \fB--pretty\fR, which is
enabled by default with the \fBug\fR command.
.PP
A query terminal user interface (TUI) is opened with \fB-Q\fR (\fB--query\fR)
to interactively specify search patterns and view search results.  A
\fIPATTERN\fR argument requires \fB-e PATTERN\fR to start the query TUI with
the specified pattern.
.PP
A terminal output pager is enabled with \fB--pager\fR that accepts an
optional \fICOMMAND\fR to view the output.
.PP
Customized output is produced with option \fB--format\fR or \fB--replace\fR.
Try \fBug --help format\fR for help with custom formatting of the output.
See also section FORMAT.  Predefined formats include CSV with option
\fB--csv\fR, JSON with option \fB--json\fR, and XML with option \fB--xml\fR.
Hexdumps are output with option \fB-X\fR (\fB--hex\fR) or with option
\fB--hexdump\fR to customize hexdumps.
.PP
A `--' signals the end of options; the rest of the parameters are \fIFILE\fR
arguments, allowing filenames to begin with a `-' character.
.PP
Long options may start with `\FB--no-\fR' to disable, when applicable.
.PP
\fBug --help \fIWHAT\fR displays help on options related to \fIWHAT\fR.
.PP
The following options are available:
.TP
\fB\-A\fR \fINUM\fR, \fB\-\-after\-context\fR=\fINUM\fR
Output NUM lines of trailing context after matching lines.  Places
a \fB\-\-group\-separator\fR between contiguous groups of matches.  If \fB\-o\fR is
specified, output the match with context to fit NUM columns after
the match or shortens the match.  See also options \fB\-B\fR, \fB\-C\fR and \fB\-y\fR.
.TP
\fB\-a\fR, \fB\-\-text\fR
Process a binary file as if it were text.  This is equivalent to
the \fB\-\-binary\-files\fR=text option.  This option might output binary
garbage to the terminal, which can have problematic consequences if
the terminal driver interprets some of it as terminal commands.
.TP
\fB\-\-all\fR, \-@
Search all files except hidden: cancel previous file and directory
search restrictions and cancel \fB\-\-ignore\-binary\fR and \fB\-\-ignore\-files\fR
when specified.  Restrictions specified after this option, i.e. to
the right, are still applied.  For example, \-@I searches all
non\-binary files and \-@. searches all files including hidden files.
Note that hidden files and directories are never searched, unless
option \fB\-.\fR or \fB\-\-hidden\fR is specified.
.TP
\fB\-\-and\fR [\fB\-e\fR] PATTERN
Specify additional PATTERN that must match.  Additional \fB\-e\fR \fIPATTERN\fR
following this option is considered an alternative pattern to
match, i.e. each \fB\-e\fR is interpreted as an OR pattern enclosed within
the AND.  For example, \fB\-e\fR \fIA\fR \fB\-e\fR \fIB\fR \fB\-\-and\fR \fB\-e\fR \fIC\fR \fB\-e\fR \fID\fR matches lines with
(`A' or `B') and (`C' or `D').  Note that multiple \fB\-e\fR \fIPATTERN\fR are
alternations that bind more tightly together than \fB\-\-and\fR.  Option
\fB\-\-stats\fR displays the search patterns applied.  See also options
\fB\-\-not\fR, \fB\-\-andnot\fR, \fB\-\-bool\fR, \fB\-\-files\fR and \fB\-\-lines\fR.
.TP
\fB\-\-andnot\fR [\fB\-e\fR] PATTERN
Combines \fB\-\-and\fR \fB\-\-not\fR.  See also options \fB\-\-and\fR, \fB\-\-not\fR and \fB\-\-bool\fR.
.TP
\fB\-B\fR \fINUM\fR, \fB\-\-before\-context\fR=\fINUM\fR
Output NUM lines of leading context before matching lines.  Places
a \fB\-\-group\-separator\fR between contiguous groups of matches.  If \fB\-o\fR is
specified, output the match with context to fit NUM columns before
the match or shortens the match.  See also options \fB\-A\fR, \fB\-C\fR and \fB\-y\fR.
.TP
\fB\-b\fR, \fB\-\-byte\-offset\fR
The offset in bytes of a pattern match is displayed in front of the
respective matched line.  When \fB\-u\fR or \fB\-\-ungroup\fR is specified,
displays the offset for each pattern matched on the same line.
Byte offsets are exact for ASCII, UTF\-8 and raw binary input.
Otherwise, the offset in the UTF\-8\-normalized input is displayed.
.TP
\fB\-\-binary\-files\fR=\fITYPE\fR
Controls searching and reporting pattern matches in binary files.
TYPE can be `binary', `without\-match`, `text`, `hex` and
`with\-hex'.  The default is `binary' to search binary files and to
report a match without displaying the match.  `without\-match'
ignores binary matches.  `text' treats all binary files as text,
which might output binary garbage to the terminal, which can have
problematic consequences if the terminal driver interprets some of
it as commands.  `hex' reports all matches in hexadecimal.
`with\-hex' only reports binary matches in hexadecimal, leaving text
matches alone.  Files having NUL (zero) bytes are binary and files
with invalid UTF encoding are binary unless option \fB\-U\fR or \fB\-\-ascii\fR
or \fB\-\-binary\fR is specified.  Short options are \fB\-a\fR, \fB\-I\fR, \fB\-W\fR, \fB\-X\fR.
.TP
\fB\-\-bool\fR, \fB\-%\fR, \fB\-%\fR%
Specifies Boolean query patterns.  A Boolean query pattern is
composed of `AND', `OR', `NOT' operators and grouping with `(' `)'.
Spacing between subpatterns is the same as `AND', `|' is the same
as `OR' and a `\-' is the same as `NOT'.  The `OR' operator binds
more tightly than `AND'.  For example, \fB\-\-bool\fR 'A|B C|D' matches
lines with (`A' or `B') and (`C' or `D'), \fB\-\-bool\fR 'A \fB\-B\fR' matches
lines with `A' and not `B'.  Operators `AND', `OR', `NOT' require
proper spacing.  For example, \fB\-\-bool\fR 'A OR B AND C OR D' matches
lines with (`A' or `B') and (`C' or `D'), \fB\-\-bool\fR 'A AND NOT B'
matches lines with `A' without `B'.  Quoted subpatterns are matched
literally as strings.  For example, \fB\-\-bool\fR 'A "AND"|"OR"' matches
lines with `A' and also either `AND' or `OR'.  Parentheses are used
for grouping.  For example, \fB\-\-bool\fR '(A B)|C' matches lines with `A'
and `B', or lines with `C'.  Note that all subpatterns in a Boolean
query pattern are regular expressions, unless \fB\-F\fR is specified.
Options \fB\-E\fR, \fB\-F\fR, \fB\-G\fR, \fB\-P\fR and \fB\-Z\fR can be combined with \fB\-\-bool\fR to match
subpatterns as strings or regular expressions (\fB\-E\fR is the default.)
This option does not apply to \fB\-f\fR \fIFILE\fR patterns.  The double short
option \fB\-%\fR% enables options \fB\-\-bool\fR \fB\-\-files\fR.  Option \fB\-\-stats\fR displays
the Boolean search patterns applied.  See also options \fB\-\-and\fR,
\fB\-\-andnot\fR, \fB\-\-not\fR, \fB\-\-files\fR and \fB\-\-lines\fR.
.TP
\fB\-\-break\fR
Adds a line break between results from different files.  This
option is enabled by \fB\-\-heading\fR.
.TP
\fB\-C\fR \fINUM\fR, \fB\-\-context\fR=\fINUM\fR
Output NUM lines of leading and trailing context surrounding each
matching line.  Places a \fB\-\-group\-separator\fR between contiguous
groups of matches.  If \fB\-o\fR is specified, output the match with
context to fit NUM columns before and after the match or shortens
the match.  See also options \fB\-A\fR, \fB\-B\fR and \fB\-y\fR.
.TP
\fB\-c\fR, \fB\-\-count\fR
Only a count of selected lines is written to standard output.
When \fB\-o\fR or \fB\-u\fR is specified, counts the number of patterns matched.
When \fB\-v\fR is specified, counts the number of non\-matching lines.
When \fB\-m\fR1, (with a comma or \fB\-\-min\-count\fR=1) is specified, counts only
matching files without outputting zero matches.
.TP
\fB\-\-color\fR[=\fIWHEN\fR], \fB\-\-colour\fR[=\fIWHEN\fR]
Mark up the matching text with the colors specified with option
\fB\-\-colors\fR or the GREP_COLOR or GREP_COLORS environment variable.
WHEN can be `never', `always', or `auto', where `auto' marks up
matches only when output on a terminal.  The default is `auto'.
.TP
\fB\-\-colors\fR=\fICOLORS\fR, \fB\-\-colours\fR=\fICOLORS\fR
Use COLORS to mark up text.  COLORS is a colon\-separated list of
one or more parameters `sl=' (selected line), `cx=' (context line),
`mt=' (matched text), `ms=' (match selected), `mc=' (match
context), `fn=' (file name), `ln=' (line number), `cn=' (column
number), `bn=' (byte offset), `se=' (separator), `qp=' (TUI
prompt), `qe=' (TUI errors), `qr=' (TUI regex), `qm=' (TUI regex
meta characters), `ql=' (TUI regex lists and literals), `qb=' (TUI
regex braces).  Parameter values are ANSI SGR color codes or `k'
(black), `r' (red), `g' (green), `y' (yellow), `b' (blue), `m'
(magenta), `c' (cyan), `w' (white), or leave empty for no color.
Upper case specifies background colors.  A `+' qualifies a color as
bright.  A foreground and a background color may be combined with
font properties `n' (normal), `f' (faint), `h' (highlight), `i'
(invert), `u' (underline).  Parameter `hl' enables file name
hyperlinks.  Parameter `rv' reverses the `sl=' and `cx=' parameters
when option \fB\-v\fR is specified.  Selectively overrides GREP_COLORS.
Legacy grep single parameter codes may be specified, for example
\fB\-\-colors\fR='7;32' or \fB\-\-colors\fR=ig to set ms (match selected).
.TP
\fB\-\-config\fR[=\fIFILE\fR], \fB\-\-\-\fR[\fIFILE\fR]
Use configuration FILE.  The default FILE is `.ugrep'.  The working
directory is checked first for FILE, then the home directory.  The
options specified in the configuration FILE are parsed first,
followed by the remaining options specified on the command line.
The ug command automatically loads a `.ugrep' configuration file
when present, unless \fB\-\-config\fR=\fIFILE\fR or \fB\-\-no\-config\fR is specified.
.TP
\fB\-\-no\-config\fR
Do not automatically load the default .ugrep configuration file.
.TP
\fB\-\-no\-confirm\fR
Do not confirm actions in \fB\-Q\fR query TUI.  The default is confirm.
.TP
\fB\-\-cpp\fR
Output file matches in C++.  See also options \fB\-\-format\fR and \fB\-u\fR.
.TP
\fB\-\-csv\fR
Output file matches in CSV.  When \fB\-H\fR, \fB\-n\fR, \fB\-k\fR, or \fB\-b\fR is specified,
additional values are output.  See also options \fB\-\-format\fR and \fB\-u\fR.
.TP
\fB\-D\fR \fIACTION\fR, \fB\-\-devices\fR=\fIACTION\fR
If an input file is a device, FIFO or socket, use ACTION to process
it.  When ACTION is `skip', devices are ignored.  When ACTION is
`read', devices are read just as if they were ordinary files.  The
default ACTION is `skip', except for devices specified as arguments
on the command line, which can be explicitly skipped with \fB\-D\fRskip.
.TP
\fB\-d\fR \fIACTION\fR, \fB\-\-directories\fR=\fIACTION\fR
If an input file is a directory, use ACTION to process it.  When
ACTION is `read', warn when directories are read as input.  When
ACTION is `recurse', read all files under each directory,
recursively, following symbolic links only if they are on the
command line.  This is equivalent to the \fB\-r\fR option.  When ACTION is
`dereference\-recurse', read all files under each directory,
recursively, following symbolic links.  This is equivalent to the
\fB\-R\fR option.  When no files or directories are specified on the
command line, ACTION defaults to `recurse` or option \fB\-r\fR.
.TP
\fB\-\-delay\fR=\fIDELAY\fR
Set the default \fB\-Q\fR key response delay.  Default is 3 for 300ms.
.TP
\fB\-\-depth\fR=[\fIMIN\fR,][\fIMAX\fR], \fB\-1\fR, \fB\-2\fR, \fB\-3\fR, \&... \fB\-9\fR, \fB\-1\fR0, \fB\-1\fR1, \&...
Restrict recursive searches from MIN to MAX directory levels deep,
where \fB\-1\fR (\fB\-\-depth\fR=1) searches the specified path without recursing
into subdirectories.  The short forms \fB\-3\fR \fB\-5\fR, \fB\-3\fR\-5 and \fB\-3\fR,5 search 3
to 5 levels deep.  Enables \fB\-r\fR if \fB\-R\fR or \fB\-r\fR is not specified.
.TP
\fB\-\-dotall\fR
Dot `.' in regular expressions matches anything, including newline.
Note that `.*' matches all input and should not be used.
.TP
\fB\-E\fR, \fB\-\-extended\-regexp\fR
Interpret patterns as extended regular expressions (EREs). This is
the default.
.TP
\fB\-e\fR \fIPATTERN\fR, \fB\-\-regexp\fR=\fIPATTERN\fR
Specify a PATTERN to search the input.  An input line is selected
if it matches any of the specified patterns.  This option is useful
when multiple \fB\-e\fR options are used to specify multiple patterns, or
when a pattern starts with a dash (`\-'), or to specify a pattern
after option \fB\-f\fR or after the FILE arguments.
.TP
\fB\-\-encoding\fR=\fIENCODING\fR
The encoding format of the input.  The default ENCODING is binary
or UTF\-8 which are treated the same.  Therefore, \fB\-\-encoding\fR=binary
has no effect.  Contrast this with option \fB\-U\fR or \fB\-\-ascii\fR or \fB\-\-binary\fR
that specifies raw binary PATTERN matching.  ENCODING can be:
`binary', `ASCII', `UTF\-8', `UTF\-16', `UTF\-16BE', `UTF\-16LE',
`UTF\-32', `UTF\-32BE', `UTF\-32LE', `LATIN1', `ISO\-8859\-1',
`ISO\-8859\-2', `ISO\-8859\-3', `ISO\-8859\-4', `ISO\-8859\-5',
`ISO\-8859\-6', `ISO\-8859\-7', `ISO\-8859\-8', `ISO\-8859\-9',
`ISO\-8859\-10', `ISO\-8859\-11', `ISO\-8859\-13', `ISO\-8859\-14',
`ISO\-8859\-15', `ISO\-8859\-16', `MAC', `MACROMAN', `EBCDIC', `CP437',
`CP850', `CP858', `CP1250', `CP1251', `CP1252', `CP1253', `CP1254',
`CP1255', `CP1256', `CP1257', `CP1258', `KOI8\-R', `KOI8\-U',
`KOI8\-RU', `null\-data'.
.TP
\fB\-\-exclude\fR=\fIGLOB\fR
Exclude files whose name matches GLOB, same as \fB\-g\fR ^GLOB.  GLOB can
use **, *, ?, and [\&...] as wildcards and \\ to quote a wildcard or
backslash character literally.  When GLOB contains a `/', full
pathnames are matched.  Otherwise basenames are matched.  When GLOB
ends with a `/', directories are excluded as if \fB\-\-exclude\-dir\fR is
specified.  Otherwise files are excluded.  Note that \fB\-\-exclude\fR
patterns take priority over \fB\-\-include\fR patterns.  GLOB should be
quoted to prevent shell globbing.  This option may be repeated.
.TP
\fB\-\-exclude\-dir\fR=\fIGLOB\fR
Exclude directories whose name matches GLOB from recursive
searches, same as \fB\-g\fR ^GLOB/.  GLOB may use **, *, ?, and [\&...] as
wildcards and \\ to quote a wildcard or backslash character
literally.  When GLOB contains a `/', full pathnames are matched.
Otherwise basenames are matched.  Note that \fB\-\-exclude\-dir\fR patterns
take priority over \fB\-\-include\-dir\fR patterns.  GLOB should be quoted
to prevent shell globbing.  This option may be repeated.
.TP
\fB\-\-exclude\-from\fR=\fIFILE\fR
Read the globs from FILE and skip files and directories whose name
matches one or more globs.  A glob may use **, *, ?, and [\&...] as
wildcards and \\ to quote a wildcard or backslash character
literally.  When a glob contains a `/', full pathnames are matched.
Otherwise basenames are matched.  When a glob ends with a `/',
directories are excluded as if \fB\-\-exclude\-dir\fR is specified.
Otherwise files are excluded.  A glob starting with a `!' overrides
previously\-specified exclusions by including matching files.  Lines
starting with a `#' in FILE are ignored.  When FILE is a `\-',
standard input is read.  This option may be repeated.  See also
related option \fB\-\-ignore\-files\fR for subdirectory\-specific exclusions.
.TP
\fB\-\-exclude\-fs\fR=\fIMOUNTS\fR
Exclude file systems specified by MOUNTS from recursive searches.
MOUNTS is a comma\-separated list of mount points or pathnames to
directories.  When MOUNTS is not specified, only descends into the
file systems associated with the specified file and directory
search targets, i.e. excludes all other file systems.  Note that
\fB\-\-exclude\-fs\fR=\fIMOUNTS\fR take priority over \fB\-\-include\-fs\fR=\fIMOUNTS\fR.  This
option may be repeated.
.TP
\fB\-F\fR, \fB\-\-fixed\-strings\fR
Interpret pattern as a set of fixed strings, separated by newlines,
any of which is to be matched.  This makes ugrep behave as fgrep.
If a PATTERN is specified, or \fB\-e\fR \fIPATTERN\fR or \fB\-N\fR \fIPATTERN\fR, then this
option has no effect on \fB\-f\fR \fIFILE\fR patterns to allow \fB\-f\fR \fIFILE\fR patterns
to narrow or widen the scope of the PATTERN search.
.TP
\fB\-f\fR \fIFILE\fR, \fB\-\-file\fR=\fIFILE\fR
Read newline\-separated patterns from FILE.  White space in patterns
is significant.  Empty lines in FILE are ignored.  If FILE does not
exist, the GREP_PATH environment variable is used as path to FILE.
If that fails, looks for FILE in /usr/local/share/ugrep/patterns.
When FILE is a `\-', standard input is read.  Empty files contain no
patterns; thus nothing is matched.  This option may be repeated.
.TP
\fB\-\-files\fR, \fB\-%\fR%
Boolean file matching mode, the opposite of \fB\-\-lines\fR.  When combined
with option \fB\-\-bool\fR, matches a file if all Boolean conditions are
satisfied.  For example, \fB\-\-bool\fR \fB\-\-files\fR 'A B|C \fB\-D\fR' matches a file
if some lines match `A', and some lines match either `B' or `C',
and no line matches `D'.  See also options \fB\-\-and\fR, \fB\-\-andnot\fR, \fB\-\-not\fR,
\fB\-\-bool\fR and \fB\-\-lines\fR.  The double short option \fB\-%\fR% enables options
\fB\-\-bool\fR \fB\-\-files\fR.
.TP
\fB\-\-filter\fR=\fICOMMANDS\fR
Filter files through the specified COMMANDS first before searching.
COMMANDS is a comma\-separated list of `exts:command arguments',
where `exts' is a comma\-separated list of filename extensions and
`command' is a filter utility.  Files matching one of `exts' are
filtered.  A `*' matches any file.  The specified `command' may
include arguments separated by spaces.  An argument may be quoted
to include spacing, commas or a `%'.  A `%' argument expands into
the pathname to search.  For example, \fB\-\-filter\fR='pdf:pdftotext % \-'
searches PDF files.  The `%' expands into a `\-' when searching
standard input.  When a `%' is not specified, the filter command
should read from standard input and write to standard output.
Option \fB\-\-label\fR=.ext may be used to specify extension `ext' when
searching standard input.  Note that `exts` filename extension
matching is case insensitive.  This option may be repeated.
.TP
\fB\-\-filter\-magic\-label\fR=[+]LABEL:MAGIC
Associate LABEL with files whose signature "magic bytes" match the
MAGIC regex pattern.  Only files that have no filename extension
are labeled, unless +LABEL is specified.  When LABEL matches an
extension specified in \fB\-\-filter\fR=\fICOMMANDS\fR, the corresponding command
is invoked.  This option may be repeated.
.TP
\fB\-\-format\fR=\fIFORMAT\fR
Output FORMAT\-formatted matches.  For example \fB\-\-format\fR='%f:%n:%O%~'
outputs matching lines `%O' with filename `%f` and line number `%n'
followed by a newline `%~'.  If \fB\-P\fR is specified, FORMAT may include
`%1' to `%9', `%[\fINUM\fR]#' and `%[\fINAME\fR]#' to output group captures.  A
`%%' outputs `%'.  See `ugrep \fB\-\-help\fR format' and `man ugrep'
section FORMAT for details.  When option \fB\-o\fR is specified, option \fB\-u\fR
is also enabled.  Context options \fB\-A\fR, \fB\-B\fR, \fB\-C\fR and \fB\-y\fR are ignored.
.TP
\fB\-\-free\-space\fR
Spacing (blanks and tabs) in regular expressions are ignored.
.TP
\fB\-\-from\fR=\fIFILE\fR
Read additional pathnames of files to search from FILE.  When FILE
is a `\-', standard input is read.  This option is useful with `find
\&... \fB\-p\fRrint | ugrep \fB\-\-from\fR=\fI\-\fR \&...' to search specific files.
.TP
\fB\-G\fR, \fB\-\-basic\-regexp\fR
Interpret patterns as basic regular expressions (BREs).
.TP
\fB\-g\fR \fIGLOBS\fR, \fB\-\-glob\fR=\fIGLOBS\fR, \fB\-\-iglob\fR=\fIGLOBS\fR
Only search files whose name matches the specified comma\-separated
list of GLOBS, same as \fB\-\-include\fR='glob' for each `glob' in GLOBS.
When a `glob' is preceded by a `!' or a `^', skip files whose name
matches `glob', same as \fB\-\-exclude\fR='glob'.  When `glob' contains a
`/', full pathnames are matched and option \fB\-r\fR is enabled to recurse
into directories if \fB\-d\fR, \fB\-r\fR or \fB\-R\fR is not already specified.
Otherwise basenames are matched.  When `glob' ends with a `/',
directories are matched, same as \fB\-\-include\-dir\fR='glob' and
\fB\-\-exclude\-dir\fR='glob'.  A leading `./' or just `/' matches the
working directory.  Option \fB\-\-iglob\fR=\fIGLOBS\fR performs case\-insensitive
name matching.  This option may be repeated and may be combined
with options \fB\-M\fR, \fB\-O\fR and \fB\-t\fR.  For more details, see `ugrep \fB\-\-help\fR
globs' and `man ugrep' section GLOBBING for details.
.TP
\fB\-\-glob\-ignore\-case\fR
Perform case\-insensitive glob matching in general.
.TP
\fB\-\-group\-separator\fR[=\fISEP\fR]
Use SEP as a group separator for context options \fB\-A\fR, \fB\-B\fR and \fB\-C\fR.
The default is a double hyphen (`\fB\-\-\fR').
.TP
\fB\-\-no\-group\-separator\fR
Removes the group separator line from the output for context
options \fB\-A\fR, \fB\-B\fR and \fB\-C\fR.
.TP
\fB\-H\fR, \fB\-\-with\-filename\fR
Always print the filename with output lines.  This is the default
when there is more than one file to search.
.TP
\fB\-h\fR, \fB\-\-no\-filename\fR
Never print filenames with output lines.  This is the default
when there is only one file (or only standard input) to search.
.TP
\fB\-\-heading\fR, \fB\-+\fR
Group matches per file.  Adds a heading and a line break between
results from different files.  This option is enabled by \fB\-\-pretty\fR
when the output is sent to the terminal.
.TP
\fB\-\-help\fR [\fIWHAT\fR], \fB\-?\fR [\fIWHAT\fR]
Display a help message on options related to WHAT when specified.
In addition, `\fB\-\-help\fR regex' displays an overview of regular
expressions, `\fB\-\-help\fR globs' displays an overview of glob syntax and
conventions, `\fB\-\-help\fR fuzzy' displays details of fuzzy search, and
`\fB\-\-help\fR format' displays a list of option \fB\-\-format\fR=\fIFORMAT\fR fields.
.TP
\fB\-\-hexdump\fR[=[1\-8][a][bch][A[\fINUM\fR]][B[\fINUM\fR]][C[\fINUM\fR]]]
Output matches in 1 to 8 columns of 8 hexadecimal octets.  The
default is 2 columns or 16 octets per line.  Argument `a' outputs a
`*' for all hex lines that are identical to the previous hex line,
`b' removes all space breaks, `c' removes the character column, `h'
removes hex spacing, `A' includes up to NUM hex lines after a
match, `B' includes up to NUM hex lines before a match and `C'
includes up to NUM hex lines before and after a match.  Arguments
`A', `B' and `C' are the same as options \fB\-A\fR, \fB\-B\fR and \fB\-C\fR when used
with \fB\-\-hexdump\fR.  See also options \fB\-U\fR, \fB\-W\fR and \fB\-X\fR.
.TP
\fB\-\-hidden\fR, \fB\-.\fR
Search hidden files and directories
(enabled by default in grep compatibility mode).
.TP
\fB\-\-hyperlink\fR[=[\fIPREFIX\fR][+]]
Hyperlinks are enabled for file names when colors are enabled.
Same as \fB\-\-colors\fR=hl.  When PREFIX is specified, replaces file://
with PREFIX:// in the hyperlink.  A `+' includes the line number in
the hyperlink and when option \fB\-k\fR is specified, the column number.
.TP
\fB\-I\fR, \fB\-\-ignore\-binary\fR
Ignore matches in binary files.  This option is equivalent to the
\fB\-\-binary\-files\fR=without\-match option.  Files having NUL (zero) bytes
are binary.  Also files with invalid UTF encoding are binary unless
option \fB\-U\fR or \fB\-\-ascii\fR or \fB\-\-binary\fR is specified.
.TP
\fB\-i\fR, \fB\-\-ignore\-case\fR
Perform case insensitive matching.  By default, ugrep is case
sensitive.
.TP
\fB\-\-ignore\-files\fR[=\fIFILE\fR]
Ignore files and directories matching the globs in each FILE that
is encountered in recursive searches.  The default FILE is
`.gitignore'.  Matching files and directories located in the
directory of the FILE and in subdirectories are ignored.  When FILE is
a full pathname, FILE is read ahead of the recursive search and
globs are globally applied to ignore files and directories.  When
FILE is a `\-', standard input is read.  Globbing is the same as for
\fB\-\-exclude\-from\fR=\fIFILE\fR, except that \fB\-\-ignore\-files\fR excludes files and
also directories when globs match.  This option may be repeated.
.TP
\fB\-\-no\-ignore\-files\fR
Do not ignore files, i.e. cancel \fB\-\-ignore\-files\fR when specified.
.TP
\fB\-\-include\fR=\fIGLOB\fR
Only search files whose name matches GLOB, same as \fB\-g\fR \fIGLOB\fR.  GLOB
may use **, *, ?, and [\&...] as wildcards and \\ to quote a wildcard
or backslash character literally.  When GLOB contains a `/', full
pathnames are matched and option \fB\-r\fR is enabled to recurse into
directories if \fB\-d\fR, \fB\-r\fR or \fB\-R\fR is not already specified.  Otherwise
basenames are matched.  When GLOB ends with a `/', directories are
included as if \fB\-\-include\-dir\fR is specified.  Otherwise files are
included.  Note that \fB\-\-exclude\fR patterns take priority over
\fB\-\-include\fR patterns.  GLOB should be quoted to prevent shell
globbing.  This option may be repeated.
.TP
\fB\-\-include\-dir\fR=\fIGLOB\fR
Only directories whose name matches GLOB are included in recursive
searches, same as \fB\-g\fR \fIGLOB\fR/.  GLOB may use **, *, ?, and [\&...] as
wildcards and \\ to quote a wildcard or backslash character
literally.  When GLOB contains a `/', full pathnames are matched
and option \fB\-r\fR is enabled to recurse into directories if \fB\-d\fR, \fB\-r\fR or
\fB\-R\fR is not already specified.  Otherwise basenames are matched.
Note that \fB\-\-exclude\-dir\fR patterns take priority over \fB\-\-include\-dir\fR
patterns.  GLOB should be quoted to prevent shell globbing.  This
option may be repeated.
.TP
\fB\-\-include\-from\fR=\fIFILE\fR
Read the globs from FILE and search only files and directories
whose name matches one or more globs.  A glob may use **, *, ?, and
[\&...] as wildcards and \\ to quote a wildcard or backslash
character literally.  When a glob contains a `/', full pathnames
are matched.  Otherwise basenames are matched.  When a glob ends
with a `/', directories are included as if \fB\-\-include\-dir\fR is
specified.  Otherwise files are included.  A glob starting with a
`!' overrides previously\-specified inclusions by excluding matching
files.  Lines starting with a `#' and empty lines in FILE are
ignored.  When FILE is a `\-', standard input is read.  This option
may be repeated.
.TP
\fB\-\-include\-fs\fR=\fIMOUNTS\fR
Only file systems specified by MOUNTS are included in recursive
searches.  MOUNTS is a comma\-separated list of mount points or
pathnames to directories.  When MOUNTS is not specified, restricts
recursive searches to the file system of the working directory,
same as \fB\-\-include\-fs\fR=. (dot). Note that \fB\-\-exclude\-fs\fR=\fIMOUNTS\fR take
priority over \fB\-\-include\-fs\fR=\fIMOUNTS\fR.  This option may be repeated.
.TP
\fB\-\-index\fR
Perform fast index\-based recursive search.  This option assumes,
but does not require, that files are indexed with ugrep\-indexer.
This option also enables option \fB\-r\fR or \fB\-\-recursive\fR.  Skips indexed
non\-matching files, archives and compressed files.  Significant
acceleration may be achieved on cold (not file\-cached) and large
file systems, or any file system that is slow to search.  Note that
the start\-up time to search may be increased when complex search
patterns are specified that contain large Unicode character classes
combined with `*' or `+' repeats, which should be avoided.  Option
\fB\-U\fR or \fB\-\-ascii\fR or \fB\-\-binary\fR improves performance.  Option \fB\-\-stats\fR
displays an index search report.
.TP
\fB\-J\fR \fINUM\fR, \fB\-\-jobs\fR=\fINUM\fR
Specifies the number of threads spawned to search files.  By
default an optimum number of threads is spawned to search files
simultaneously.  \fB\-J\fR1 disables threading: files are searched in the
same order as specified.
.TP
\fB\-j\fR, \fB\-\-smart\-case\fR
Perform case insensitive matching, unless a pattern is specified
with a literal upper case letter.
.TP
\fB\-\-json\fR
Output file matches in JSON.  When \fB\-H\fR, \fB\-n\fR, \fB\-k\fR, or \fB\-b\fR is specified,
additional values are output.  See also options \fB\-\-format\fR and \fB\-u\fR.
.TP
\fB\-K\fR [\fIMIN\fR,][\fIMAX\fR], \fB\-\-range\fR=[\fIMIN\fR,][\fIMAX\fR], \fB\-\-min\-line\fR=\fIMIN\fR, \fB\-\-max\-line\fR=\fIMAX\fR
Start searching at line MIN, stop reading input after line MAX.
.TP
\fB\-k\fR, \fB\-\-column\-number\fR
The column number of a pattern match is displayed in front of the
respective matched line, starting at column 1.  Tabs are expanded
in counting columns, see also option \fB\-\-tabs\fR.
.TP
\fB\-L\fR, \fB\-\-files\-without\-match\fR
Only the names of files not containing selected lines are written
to standard output.  Pathnames are listed once per file searched.
If the standard input is searched, the string ``(standard input)''
is written.
.TP
\fB\-l\fR, \fB\-\-files\-with\-matches\fR
Only the names of files containing selected lines are written to
standard output.  Pathnames are listed once per file searched.  If
the standard input is searched, the string ``(standard input)'' is
written.  Stop reading input upon the first match.
.TP
\fB\-\-label\fR=\fILABEL\fR
Displays the LABEL value when input is read from standard input
where a file name would normally be printed in the output.
Associates a filename extension with standard input when LABEL has
a suffix.  The default value is `(standard input)'.
.TP
\fB\-\-line\-buffered\fR
Force output to be line buffered instead of block buffered.
.TP
\fB\-\-lines\fR
Boolean line matching mode for option \fB\-\-bool\fR, the default mode.
.TP
\fB\-M\fR \fIMAGIC\fR, \fB\-\-file\-magic\fR=\fIMAGIC\fR
Only search files matching the magic signature pattern MAGIC.  The
signature "magic bytes" at the start of a file are compared to
the MAGIC regex pattern.  When matching, the file will be searched.
When MAGIC is preceded by a `!' or a `^', skip files with matching
MAGIC signatures.  This option may be repeated and may be combined
with options \fB\-O\fR and \fB\-t\fR.  Every file on the search path is read,
making recursive searches potentially more expensive.
.TP
\fB\-m\fR [\fIMIN\fR,][\fIMAX\fR], \fB\-\-min\-count\fR=\fIMIN\fR, \fB\-\-max\-count\fR=\fIMAX\fR
Require MIN matches, stop reading input upon MAX matches.  Output
MIN to MAX matches.  For example, \fB\-m\fR1 outputs the first match and
\fB\-c\fRm1, (with a comma) counts nonzero matches.  When \fB\-u\fR or \fB\-\-ungroup\fR
is specified, each individual match counts.  See also option \fB\-K\fR.
.TP
\fB\-\-match\fR
Match all lines.  Same as specifying an empty pattern to search.
.TP
\fB\-\-max\-files\fR=\fINUM\fR
Restrict the number of files matched to NUM.  Note that \fB\-\-sort\fR or
\fB\-J\fR1 may be specified to produce replicable results.  If \fB\-\-sort\fR is
specified, then the number of threads spawned is limited to NUM.
.TP
\fB\-\-max\-size\fR=\fIMAX\fR
Only search files whose physical size does not exceed MAX bytes.
Suffix MAX with kb, mb, gb, tb for kilo, mega, giga, or terabytes.
.TP
\fB\-\-min\-size\fR=\fIMIN\fR
Only search files whose physical size equals or exceeds MIN bytes.
Suffix MIN with kb, mb, gb, tb for kilo, mega, giga, or terabytes.
.TP
\fB\-\-mmap\fR[=\fIMAX\fR]
Use memory maps to search files.  By default, memory maps are used
under certain conditions to improve performance.  When MAX is
specified, use up to MAX mmap memory per thread.
.TP
\fB\-N\fR \fIPATTERN\fR, \fB\-\-neg\-regexp\fR=\fIPATTERN\fR
Specify a negative PATTERN to reject specific \fB\-e\fR \fIPATTERN\fR matches
with a counter pattern.  Note that longer patterns take precedence
over shorter patterns, i.e. a negative pattern must be of the same
length or longer to reject matching patterns.  Option \fB\-N\fR cannot be
specified with \fB\-P\fR.  This option may be repeated.
.TP
\fB\-n\fR, \fB\-\-line\-number\fR
Each output line is preceded by its relative line number in the
file, starting at line 1.  The line number counter is reset for
each file processed.
.TP
\fB\-\-not\fR [\fB\-e\fR] PATTERN
Specifies that PATTERN should not match.  Note that \fB\-e\fR \fIA\fR \fB\-\-not\fR \fB\-e\fR \fIB\fR
matches lines with `A' or lines without a `B'.  To match lines with
`A' that have no `B', specify \fB\-e\fR \fIA\fR \fB\-\-andnot\fR \fB\-e\fR \fIB\fR.  Option \fB\-\-stats\fR
displays the search patterns applied.  See also options \fB\-\-and\fR,
\fB\-\-andnot\fR, \fB\-\-bool\fR, \fB\-\-files\fR and \fB\-\-lines\fR.
.TP
\fB\-\-null\fR, \fB\-0\fR
Output a zero byte after the file name.  This option can be used
with commands such as `find \fB\-p\fRrint0' and `xargs \fB\-0\fR' to process
arbitrary file names, even those that contain newlines.  See also
options \fB\-H\fR or \fB\-\-with\-filename\fR and \fB\-\-null\-data\fR.
.TP
\fB\-\-null\-data\fR, \fB\-0\fR0
Input and output are treated as sequences of lines with each line
terminated by a zero byte instead of a newline; effectively swaps
NUL with LF in the input and the output.  When combined with option
\fB\-\-encoding\fR=\fIENCODING\fR, output each line terminated by a zero byte
without affecting the input specified as per ENCODING.  Instead of
option \fB\-\-null\-data\fR, option \fB\-\-encoding\fR=null\-data treats the input as
a sequence of lines terminated by a zero byte without affecting the
output.  Option \fB\-\-null\-data\fR is not compatible with UTF\-16/32 input.
Since ugrep matches multiple lines when patterns are specified
containing a newline `\\n' or `\\R', this option is not required for
multi\-line matching.  See also options \fB\-\-encoding\fR and \fB\-\-null\fR.
.TP
\fB\-O\fR \fIEXTENSIONS\fR, \fB\-\-file\-extension\fR=\fIEXTENSIONS\fR
Only search files whose filename extensions match the specified
comma\-separated list of EXTENSIONS, same as \fB\-g\fR '*.ext' for each
`ext' in EXTENSIONS.  When an `ext' is preceded by a `!' or a `^',
skip files whose filename extensions matches `ext', same as
\fB\-g\fR '^*.ext'.  This option may be repeated and may be combined with
options \fB\-g\fR, \fB\-M\fR and \fB\-t\fR.
.TP
\fB\-o\fR, \fB\-\-only\-matching\fR
Only the matching part of a pattern match is output.  When \fB\-A\fR, \fB\-B\fR
or \fB\-C\fR is specified, fits the match and its context on a line within
the specified number of columns.
.TP
\fB\-\-only\-line\-number\fR
Only the line number of a matching line is output.  The line number
counter is reset for each file processed.
.TP
\fB\-P\fR, \fB\-\-perl\-regexp\fR
Interpret PATTERN as a Perl regular expression using PCRE2.
Note that Perl pattern matching differs from the default grep POSIX
pattern matching.
.TP
\fB\-p\fR, \fB\-\-no\-dereference\fR
If \fB\-R\fR or \fB\-r\fR is specified, do not follow symbolic links, even when
symbolic links are specified on the command line.
.TP
\fB\-\-pager\fR[=\fICOMMAND\fR]
When output is sent to the terminal, uses COMMAND to page through
the output.  COMMAND defaults to environment variable PAGER when
defined or `less'.  Enables \fB\-\-heading\fR and \fB\-\-line\-buffered\fR.
.TP
\fB\-\-pretty\fR[=\fIWHEN\fR]
When output is sent to the terminal, enables options \fB\-\-color\fR,
\fB\-\-heading\fR, \fB\-n\fR, \fB\-\-sort\fR, \fB\-\-tree\fR and \fB\-T\fR when not explicitly disabled.
WHEN can be `never', `always', or `auto'.  The default is `auto'.
.TP
\fB\-Q\fR[=\fIDELAY\fR], \fB\-\-query\fR[=\fIDELAY\fR]
Query mode: start a TUI to perform interactive searches.  This mode
requires an ANSI capable terminal.  An optional DELAY argument may
be specified to reduce or increase the response time to execute
searches after the last key press, in increments of 100ms, where
the default is 3 (300ms delay).  No whitespace may be given between
\fB\-Q\fR and its argument DELAY.  Initial patterns may be specified with
\fB\-e\fR \fIPATTERN\fR, i.e. a PATTERN argument requires option \fB\-e\fR.  Press F1
or CTRL\-Z to view the help screen.  Press F2 or CTRL\-Y to invoke a
command to view or edit the file shown at the top of the screen.
This command can be specified with option \fB\-\-view\fR and defaults to
environment variable PAGER when defined, or VISUAL or EDITOR.
Press TAB or SHIFT\-TAB to navigate directories and to select a file
to search.  Press ENTER to select lines to output.  Press ALT\-l for
option \fB\-l\fR to list files, ALT\-n for \fB\-n\fR, etc.  Non\-option commands
include ALT\-] to increase context and ALT\-} to increase fuzzyness.
If ALT or OPTION keys are not available, then press CTRL\-O + KEY to
switch option `KEY', or press F1 or CTRL\-Z for help and press KEY.
See also options \fB\-\-no\-confirm\fR, \fB\-\-delay\fR, \fB\-\-split\fR and \fB\-\-view\fR.
.TP
\fB\-q\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR
Quiet mode: suppress all output.  Only search a file until a match
has been found.
.TP
\fB\-R\fR, \fB\-\-dereference\-recursive\fR
Recursively read all files under each directory, following symbolic
links to files and directories, unlike \fB\-r\fR.
.TP
\fB\-r\fR, \fB\-\-recursive\fR
Recursively read all files under each directory, following symbolic
links only if they are on the command line.  Note that when no FILE
arguments are specified and input is read from a terminal,
recursive searches are performed as if \fB\-r\fR is specified.
.TP
\fB\-\-replace\fR=\fIFORMAT\fR
Replace matching patterns in the output by FORMAT with `%' fields.
If \fB\-P\fR is specified, FORMAT may include `%1' to `%9', `%[\fINUM\fR]#' and
`%[\fINAME\fR]#' to output group captures.  A `%%' outputs `%' and `%~'
outputs a newline.  See also option \fB\-\-format\fR, `ugrep \fB\-\-help\fR format'
and `man ugrep' section FORMAT for details.
.TP
\fB\-S\fR, \fB\-\-dereference\-files\fR
When \fB\-r\fR is specified, follow symbolic links to files, but not to
directories.  The default is not to follow symbolic links.
.TP
\fB\-s\fR, \fB\-\-no\-messages\fR
Silent mode: nonexistent and unreadable files are ignored and
their error messages and warnings are suppressed.
.TP
\fB\-\-save\-config\fR[=\fIFILE\fR] [\fIOPTIONS\fR]
Save configuration FILE to include OPTIONS.  Update FILE when
first loaded with \fB\-\-config\fR=\fIFILE\fR.  The default FILE is `.ugrep',
which is automatically loaded by the ug command.  When FILE is a
`\-', writes the configuration to standard output.  Only part of the
OPTIONS are saved that do not cause searches to fail when combined
with other options.  Additional options may be specified by editing
the saved configuration file.  A configuration file may be modified
by adding one or more config=\fIFILE\fR to include configuration files,
but recursive configuration file inclusion is not permitted.
.TP
\fB\-\-separator\fR[=\fISEP\fR], \fB\-\-context\-separator\fR=\fISEP\fR
Use SEP as field separator between file name, line number, column
number, byte offset and the matched line.  The default separator is
a colon (`:') and a bar (`|') for multi\-line pattern matches, and a
dash (`\-') for context lines.  See also option \fB\-\-group\-separator\fR.
.TP
\fB\-\-split\fR
Split the \fB\-Q\fR query TUI screen on startup.
.TP
\fB\-\-sort\fR[=\fIKEY\fR]
Displays matching files in the order specified by KEY in recursive
searches.  Normally the ug command sorts by name whereas the ugrep
batch command displays matches in no particular order to improve
performance.  The sort KEY can be `name' to sort by pathname
(default), `best' to sort by best match with option \fB\-Z\fR (sort by
best match requires two passes over files, which is expensive),
`size' to sort by file size, `used' to sort by last access time,
`changed' to sort by last modification time and `created' to sort
by creation time.  Sorting is reversed with `rname', `rbest',
`rsize', `rused', `rchanged', or `rcreated'.  Archive contents are
not sorted.  Subdirectories are sorted and displayed after matching
files.  FILE arguments are searched in the same order as specified.
.TP
\fB\-\-stats\fR
Output statistics on the number of files and directories searched
and the inclusion and exclusion constraints applied.
.TP
\fB\-T\fR, \fB\-\-initial\-tab\fR
Add a tab space to separate the file name, line number, column
number and byte offset with the matched line.
.TP
\fB\-t\fR \fITYPES\fR, \fB\-\-file\-type\fR=\fITYPES\fR
Search only files associated with TYPES, a comma\-separated list of
file types.  Each file type corresponds to a set of filename
extensions passed to option \fB\-O\fR and filenames passed to option \fB\-g\fR.
For capitalized file types, the search is expanded to include files
with matching file signature magic bytes, as if passed to option
\fB\-M\fR.  When a type is preceded by a `!' or a `^', excludes files of
the specified type.  Specifying the initial part of a type name
suffices when the choice is unambiguous.  This option may be
repeated.  The possible file types can be (\fB\-t\fRlist displays a list):
`actionscript', `ada', `adoc', `asm', `asp', `aspx', `autoconf',
`automake', `awk', `Awk', `basic', `batch', `bison', `c',
`c++', `clojure', `cpp', `csharp', `css', `csv', `dart',
`Dart', `delphi', `elisp', `elixir', `erlang', `fortran', `gif',
`Gif', `go', `groovy', `gsp', `haskell', `html', `jade',
`java', `jpeg', `Jpeg', `js', `json', `jsp', `julia',
`kotlin', `less', `lex', `lisp', `lua', `m4', `make',
`markdown', `matlab', `node', `Node', `objc', `objc++', `ocaml',
`parrot', `pascal', `pdf', `Pdf', `perl', `Perl', `php',
`Php', `png', `Png', `prolog', `python', `Python', `r',
`rpm', `Rpm', `rst', `rtf', `Rtf', `ruby', `Ruby',
`rust', `scala', `scheme', `seed7', `shell', `Shell', `smalltalk',
`sql', `svg', `swift', `tcl', `tex', `text', `tiff',
`Tiff', `tt', `typescript', `verilog', `vhdl', `vim', `xml',
`Xml', `yacc', `yaml', `zig'.
.TP
\fB\-\-tabs\fR[=\fINUM\fR]
Set the tab size to NUM to expand tabs for option \fB\-k\fR.  The value of
NUM may be 1 (no expansion), 2, 4, or 8.  The default size is 8.
.TP
\fB\-\-tag\fR[=\fITAG\fR[,\fIEND\fR]]
Disables colors to mark up matches with TAG.  END marks the end of
a match if specified, otherwise TAG.  The default is `___'.
.TP
\fB\-\-tree\fR, \-^
Output directories with matching files in a tree\-like format for
option \fB\-c\fR or \fB\-\-count\fR, \fB\-l\fR or \fB\-\-files\-with\-matches\fR, \fB\-L\fR or
\fB\-\-files\-without\-match\fR.  This option is enabled by \fB\-\-pretty\fR when the
output is sent to the terminal.
.TP
\fB\-U\fR, \fB\-\-ascii\fR, \fB\-\-binary\fR
Disables Unicode matching for ASCII and binary matching.  PATTERN
matches bytes.  For example, \fB\-U\fR '\\xa3' matches byte A3 (hex)
instead of the Unicode code point U+00A3 represented by the UTF\-8
sequence C2 A3.  Input is not flagged as "binary" for having
invalid UTF, only for having NUL (zero) bytes.
.TP
\fB\-u\fR, \fB\-\-ungroup\fR
Do not group multiple pattern matches on the same matched line.
Output the matched line again for each additional pattern match.
.TP
\fB\-V\fR, \fB\-\-version\fR
Display version with linked libraries and exit.
.TP
\fB\-v\fR, \fB\-\-invert\-match\fR
Selected lines are those not matching any of the specified
patterns.
.TP
\fB\-\-view\fR[=[+]COMMAND]
Use COMMAND to view/edit a file in \fB\-Q\fR query TUI by pressing CTRL\-Y,
+COMMAND waits for a key press after COMMAND terminated.
.TP
\fB\-W\fR, \fB\-\-with\-hex\fR
Output binary matches in hexadecimal, leaving text matches alone.
This option is equivalent to the \fB\-\-binary\-files\fR=with\-hex option.
To omit the matching line from the hex output, use both options \fB\-W\fR
and \fB\-\-hexdump\fR.  See also options \fB\-U\fR.
.TP
\fB\-w\fR, \fB\-\-word\-regexp\fR
The PATTERN is searched for as a word, such that the matching text
is preceded by a non\-word character and is followed by a non\-word
character.  Word\-like characters are Unicode letters, digits and
connector punctuations such as underscore.
.TP
\fB\-\-width\fR[=\fINUM\fR]
Truncate the output to NUM visible characters per line.  The width
of the terminal window is used if NUM is not specified.  Note that
double\-width characters in the output may result in wider lines.
.TP
\fB\-X\fR, \fB\-\-hex\fR
Output matches and matching lines in hexadecimal.  This option is
equivalent to the \fB\-\-binary\-files\fR=hex option.  To omit the matching
line from the hex output use option \fB\-\-hexdump\fR.  See also option \fB\-U\fR.
.TP
\fB\-x\fR, \fB\-\-line\-regexp\fR
Select only those matches that exactly match the whole line, as if
the patterns are surrounded by ^ and $.
.TP
\fB\-\-xml\fR
Output file matches in XML.  When \fB\-H\fR, \fB\-n\fR, \fB\-k\fR, or \fB\-b\fR is specified,
additional values are output.  See also options \fB\-\-format\fR and \fB\-u\fR.
.TP
\fB\-Y\fR, \fB\-\-empty\fR
Empty\-matching patterns match all lines.  Normally, empty matches
are not output, unless a pattern starts with `^' or ends with `$'.
With this option, empty\-matching patterns, such as x*y?, x*y*z*,
and x*(y?|z) match all lines, not only the expected pattern.
This option is enabled by default in grep compatibility mode;
specify option \fB\-\-no\-empty\fR to prevent matching all lines.
.TP
\fB\-y\fR, \fB\-\-any\-line\fR, \fB\-\-passthru\fR
Any line is output (passthru).  Non\-matching lines are output as
context with a `\-' separator.  See also options \fB\-A\fR, \fB\-B\fR and \fB\-C\fR.
.TP
\fB\-Z\fR[best][+\-~][\fIMAX\fR], \fB\-\-fuzzy\fR[=[best][+\-~][\fIMAX\fR]]
Fuzzy mode: report approximate pattern matches within MAX errors.
The default is \fB\-Z\fR1: one deletion, insertion or substitution is
allowed.  If `+`, `\-' and/or `~' is specified, then `+' allows
insertions, `\-' allows deletions and `~' allows substitutions.  For
example, \fB\-Z\fR+~3 allows up to three insertions or substitutions, but
no deletions.  If `best' is specified, then only the best matching
lines are output with the lowest cost per file.  Option \fB\-Z\fRbest
requires two passes over a file and cannot be used with standard
input or Boolean queries.  Option \fB\-\-sort\fR=best orders matching files
by best match.  The first character of an approximate match always
matches a character at the beginning of the pattern.  To fuzzy
match the first character, replace it with a `.' or `.?'.  Option
\fB\-U\fR applies fuzzy matching to ASCII and bytes instead of Unicode
text.  No whitespace may be given between \fB\-Z\fR and its argument.
.TP
\fB\-z\fR, \fB\-\-decompress\fR
Search compressed files and archives.  Archives (.cpio, .pax, .tar)
and compressed archives (e.g. .zip, .7z, .taz, .tgz, .tpz, .tbz,
\&.tbz2, .tb2, .tz2, .tlz, .txz, .tzst) are searched and matching
pathnames of files in archives are output in braces.  When used
with option \fB\-\-zmax\fR=\fINUM\fR, searches the contents of compressed files
and archives stored within archives up to NUM levels.  When \fB\-g\fR, \fB\-O\fR,
\fB\-M\fR, or \fB\-t\fR is specified, searches archives for files that match the
specified globs, filename extensions, file signature magic bytes,
or file types, respectively; a side\-effect of these options is that
the compressed files and archives searched are only those with
filename extensions that match known compression and archive types.
Supported compression formats: gzip (.gz), compress (.Z), zip, 7z,
bzip2 (.bz, .bz2, .bzip2, .tbz, .tbz2, .tb2, .tz2),
xz (.xz, .txz) and lzma (requires suffix .lzma, .tlz),
zstd (.zst, .zstd, .tzst),
lz4 (requires suffix .lz4),
brotli (requires suffix .br),
bzip3 (requires suffix .bz3).
.TP
\fB\-\-zmax\fR=\fINUM\fR
When used with option \fB\-z\fR or \fB\-\-decompress\fR, searches the contents of
compressed files and archives stored within archives by up to NUM
expansion stages.  The default \fB\-\-zmax\fR=1 only permits searching
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 \fB\-\-zmax\fR=2 to search 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.
.TP
Specify `ugrep \fB\-\-help\fR WHAT' for help on WHAT.
.SH "EXIT STATUS"
The \fBugrep\fR utility exits with one of the following values:
.IP 0
One or more lines were selected.
.IP 1
No lines were selected.
.IP >1
An error occurred.
.PP
If \fB-q\fR or \fB--quiet\fR or \fB--silent\fR is used and a line is selected,
the exit status is 0 even if an error occurred.
.SH CONFIGURATION
The \fBug\fR command is intended for interactive searching and is equivalent to
the \fBugrep --config --pretty --sort\fR command to load the `.ugrep`
configuration file located in the working directory or, when not found, in the
home directory.
.PP
A configuration file contains `NAME=VALUE' pairs per line, where `NAME` is the
name of a long option (without `--') and `=VALUE' is an argument, which is
optional and may be omitted depending on the option.  Empty lines and lines
starting with a `#' are ignored.
.PP
The \fB--config\fR=\fIFILE\fR option and its abbreviated form
\fB---\fR\fIFILE\fR load the specified configuration file located in the
working directory or, when not found, in the home directory.  An error is
produced when \fIFILE\fR is not found or cannot be read.
.PP
Command line options are parsed in the following order: the configuration file
is loaded first, followed by the remaining options and arguments on the command
line.
.PP
The \fB--save-config\fR option saves a `.ugrep' configuration file to the
working directory with a subset of the options specified on the command line.
Only part of the specified options are saved that do not cause searches to fail
when combined with other options.  The \fB--save-config\fR=\fIFILE\fR option
saves the configuration to \fIFILE\fR.  The configuration is written to
standard output when \fIFILE\fR is a `-'.
.SH GLOBBING
Globbing is used by options \fB-g\fR (\fB--glob\fR and \fB--iglob\fR),
\fB--include\fR, \fB--include-dir\fR, \fB--include-from\fR, \fB--exclude\fR,
\fB--exclude-dir\fR, \fB--exclude-from\fR and \fB--ignore-files\fR to match
pathnames or basenames in recursive searches.  Glob arguments for these
options should be quoted to prevent shell globbing.
.PP
Globbing with \fB--ignore-files\fR supports gitignore syntax and rules.
This is also the case for all other globbing-related options, with the
exception that a glob matches filenames, not directory names.  If a glob ends
in a path separator `/', then it matches directory names, not filenames, as if
\fB--include-dir\fR or \fB--exclude-dir\fR is specified.
.PP
When a glob contains a path separator `/', the full pathname is matched.
Otherwise the basename of a file or directory is matched.  For example,
\fB*.h\fR matches foo.h and bar/foo.h.  \fBbar/*.h\fR matches bar/foo.h but not
foo.h and not bar/bar/foo.h.  Use a leading `./' or just `/' to force
\fB/*.h\fR to match foo.h in the working directory but not bar/foo.h.
.PP
When a glob starts with a `!' or a `^' as in \fB-g\fR^\fIGLOB\fR, the match is
negated.  Likewise, a `!' (but not a `^') may be used with globs in the files
specified \fB--include-from\fR, \fB--exclude-from\fR, and \fB--ignore-files\fR
to negate the glob match.  Empty lines or lines starting with a `#' are
ignored.
.PP
\fBGlob Syntax and Conventions\fR
.IP \fB*\fR
Matches anything except /.
.IP \fB?\fR
Matches any one character except /.
.IP \fB[abc-e]\fR
Matches one character a,b,c,d,e.
.IP \fB[^abc-e]\fR
Matches one character not a,b,c,d,e,/.
.IP \fB[!abc-e]\fR
Matches one character not a,b,c,d,e,/.
.IP \fB/\fR
When used at the start of a glob, matches the working directory.
When used at the end of a glob, matches directories only.
.IP \fB**/\fR
Matches zero or more directories.
.IP \fB/**\fR
When used at the end of a glob, matches everything after the /.
.IP \fB\e?\fR
Matches a ? or any other character specified after the backslash.
.PP
\fBGlob Matching Examples\fR
.IP \fB*\fR
Matches a, b, x/a, x/y/b
.IP \fBa\fR
Matches a, x/a, x/y/a,       but not b, x/b, a/a/b
.IP \fB/*\fR
Matches a, b,                but not x/a, x/b, x/y/a
.IP \fB/a\fR
Matches a,                   but not x/a, x/y/a
.IP \fBa?b\fR
Matches axb, ayb,            but not a, b, ab, a/b
.IP \fBa[xy]b\fR
Matches axb, ayb             but not a, b, azb
.IP \fBa[a-z]b\fR
Matches aab, abb, acb, azb,  but not a, b, a3b, aAb, aZb
.IP \fBa[^xy]b\fR
Matches aab, abb, acb, azb,  but not a, b, axb, ayb
.IP \fBa[^a-z]b\fR
Matches a3b, aAb, aZb        but not a, b, aab, abb, acb, azb
.IP \fBa/*/b\fR
Matches a/x/b, a/y/b,        but not a/b, a/x/y/b
.IP \fB**/a\fR
Matches a, x/a, x/y/a,       but not b, x/b.
.IP \fBa/**/b\fR
Matches a/b, a/x/b, a/x/y/b, but not x/a/b, a/b/x
.IP \fBa/**\fR
Matches a/x, a/y, a/x/y,     but not a, b/x
.IP \fBa\e?b\fR
Matches a?b,                 but not a, b, ab, axb, a/b
.PP
Note that exclude glob patterns take priority over include glob patterns when
specified with options -g, --exclude, --exclude-dir, --include and include-dir.
.PP
Option --ignore-files specifies a file with gitignore-style globs, where the
default file is .gitignore.  When ignore files are encountered in recursive
searches, the search is narrowed by excluding filenames and directory names
matching the globs; this gitignore glob-matching rule differs from option
--exclude-from which requires globs ending in / to match directory names.
.SH ENVIRONMENT
.IP \fBGREP_PATH\fR
May be used to specify a file path to pattern files.  The file path is used by
option \fB-f\fR to open a pattern file, when the pattern file does not exist.
Defaults to /usr/local/share/ugrep/patterns when \fBGREP_PATH\fR is undefined.
.IP \fBGREP_COLOR\fR
May be used to specify ANSI SGR parameters to highlight matches when option
\fB--color\fR is used, e.g. 1;35;40 shows pattern matches in bold magenta text
on a black background.  Deprecated in favor of \fBGREP_COLORS\fR, but still
supported.
.IP \fBGREP_COLORS\fR
May be used to specify ANSI SGR parameters to highlight matches and other
attributes when option \fB--color\fR is used.  Its value is a colon-separated
list of ANSI SGR parameters that defaults to
\fBcx=33:mt=1;31:fn=1;35:ln=1;32:cn=1;32:bn=1;32:se=36\fR with additional
parameters for TUI colors \fB:qp=1;32:qe=1;37;41:qm=1;32:ql=36:qb=1;35\fR.
The \fBmt=\fR, \fBms=\fR, and \fBmc=\fR capabilities of \fBGREP_COLORS\fR take
priority over \fBGREP_COLOR\fR.  Option \fB--colors\fR takes priority over
\fBGREP_COLORS\fR.
.SH GREP_COLORS
Colors are specified as string of colon-separated ANSI SGR parameters of the
form `what=substring', where `substring' is a semicolon-separated list of ANSI
SGR codes or `k' (black), `r' (red), `g' (green), `y' (yellow), `b' (blue), `m'
(magenta), `c' (cyan), `w' (white).  Upper case specifies background colors.  A
`+' qualifies a color as bright.  A foreground and a background color may be
combined with one or more font properties `n' (normal), `f' (faint), `h'
(highlight), `i' (invert), `u' (underline).  Substrings may be specified for:
.IP \fBsl=\fR
selected lines.
.IP \fBcx=\fR
context lines.
.IP \fBrv\fR
swaps the \fBsl=\fR and \fBcx=\fR capabilities when \fB-v\fR is specified.
.IP \fBmt=\fR
matching text in any matching line.
.IP \fBms=\fR
matching text in a selected line.  The substring \fBmt=\fR by
default.
.IP \fBmc=\fR
matching text in a context line.  The substring \fBmt=\fR by
default.
.IP \fBfn=\fR
filenames.
.IP \fBln=\fR
line numbers.
.IP \fBcn=\fR
column numbers.
.IP \fBbn=\fR
byte offsets.
.IP \fBse=\fR
separators.
.IP \fBrv\fR
a Boolean parameter, switches \fBsl=\fR and \fBcx=\fR with option \fB-v\fR.
.IP \fBhl\fR
a Boolean parameter, enables filename hyperlinks (\fB\\33]8;;link\fR).
.IP \fBne\fR
a Boolean parameter, disables ``erase in line'' \fB\\33[K\fR.
.IP \fBqp=\fR
TUI prompt.
.IP \fBqe=\fR
TUI errors.
.IP \fBqr=\fR
TUI regex.
.IP \fBqm=\fR
TUI regex meta characters.
.IP \fBql=\fR
TUI regex lists and literals.
.IP \fBqb=\fR
TUI regex braces.
.SH FORMAT
Option \fB--format\fR=\fIFORMAT\fR specifies an output format for matches.
Option \fB--replace\fR=\fIFORMAT\fR only replaces the matching patterns.
Fields may be used in \fIFORMAT\fR, which expand into the following values:
.IP \fB%[\fR\fITEXT\fR\fB]F\fR
if option \fB-H\fR is used: \fITEXT\fR, the file pathname and separator.
.IP \fB%f\fR
the file pathname.
.IP \fB%a\fR
the file basename without directory path.
.IP \fB%p\fR
the directory path to the file.
.IP \fB%z\fR
the file pathname in a (compressed) archive.
.IP \fB%[\fR\fITEXT\fR\fB]H\fR
if option \fB-H\fR is used: \fITEXT\fR, the quoted pathname and separator, \\"
and \\\\ replace " and \\.
.IP \fB%h\fR
the quoted file pathname, \\" and \\\\ replace " and \\.
.IP \fB%[\fR\fITEXT\fR\fB]I\fR
if option \fB-H\fR is used: \fITEXT\fR, the pathname as XML character data and separator.
.IP \fB%i\fR
the file pathname as XML character data.
.IP \fB%[\fR\fITEXT\fR\fB]N\fR
if option \fB-n\fR is used: \fITEXT\fR, the line number and separator.
.IP \fB%n\fR
the line number of the match.
.IP \fB%[\fR\fITEXT\fR\fB]K\fR
if option \fB-k\fR is used: \fITEXT\fR, the column number and separator.
.IP \fB%k\fR
the column number of the match.
.IP \fB%[\fR\fITEXT\fR\fB]B\fR
if option \fB-b\fR is used: \fITEXT\fR, the byte offset and separator.
.IP \fB%b\fR
the byte offset of the match.
.IP \fB%[\fR\fITEXT\fR\fB]T\fR
if option \fB-T\fR is used: \fITEXT\fR and a tab character.
.IP \fB%t\fR
a tab character.
.IP \fB%[\fR\fISEP\fR\fB]$\fR
set field separator to \fISEP\fR for the rest of the format fields.
.IP \fB%[\fR\fITEXT\fR\fB]<\fR
if the first match: \fITEXT\fR.
.IP \fB%[\fR\fITEXT\fR\fB]>\fR
if not the first match: \fITEXT\fR.
.IP \fB%,\fR
if not the first match: a comma, same as \fB%[,]>\fR.
.IP \fB%:\fR
if not the first match: a colon, same as \fB%[:]>\fR.
.IP \fB%;\fR
if not the first match: a semicolon, same as \fB%[;]>\fR.
.IP \fB%|\fR
if not the first match: a vertical bar, same as \fB%[|]>\fR.
.IP \fB%[\fR\fITEXT\fR\fB]S\fR
if not the first match: \fITEXT\fR and separator, see also \fB%[\fR\fISEP\fR\fB]$.
.IP \fB%s\fR
the separator, see also \fB%[\fR\fITEXT\fR\fB]S\fR and \fB%[\fR\fISEP\fR\fB]$.
.IP \fB%~\fR
a newline character.
.IP \fB%M\fR
the number of matching lines
.IP \fB%m\fR
the number of matches
.IP \fB%O\fR
the matching line is output as a raw string of bytes.
.IP \fB%o\fR
the match is output as a raw string of bytes.
.IP \fB%Q\fR
the matching line as a quoted string, \\" and \\\\ replace " and \\.
.IP \fB%q\fR
the match as a quoted string, \\" and \\\\ replace " and \\.
.IP \fB%C\fR
the matching line formatted as a quoted C/C++ string.
.IP \fB%c\fR
the match formatted as a quoted C/C++ string.
.IP \fB%J\fR
the matching line formatted as a quoted JSON string.
.IP \fB%j\fR
the match formatted as a quoted JSON string.
.IP \fB%V\fR
the matching line formatted as a quoted CSV string.
.IP \fB%v\fR
the match formatted as a quoted CSV string.
.IP \fB%X\fR
the matching line formatted as XML character data.
.IP \fB%x\fR
the match formatted as XML character data.
.IP \fB%w\fR
the width of the match, counting wide characters.
.IP \fB%d\fR
the size of the match, counting bytes.
.IP \fB%e\fR
the ending byte offset of the match.
.IP \fB%Z\fR
the edit distance cost of an approximate match with option \fB-Z\fR
.IP \fB%u\fR
select unique lines only, unless option \fB-u\fR is used.
.IP \fB%1\fR
the first regex group capture of the match, and so on up to group \fB%9\fR,
same as \fB%[1]#\fR; requires option \fB-P\fR.
.IP \fB%[\fR\fINUM\fR\fB]#\fR
the regex group capture \fINUM\fR; requires option \fB-P\fR.
.IP \fB%[\fR\fINUM\fR\fB]b\fR
the byte offset of the group capture \fINUM\fR; requires option \fB-P\fR.  Use
\fBe\fR for the ending byte offset and \fBd\fR for the byte length.
.IP \fB%[\fR\fINUM1\fR\fB|\fR\fINUM2\fR\fB|\fR...\fB]#\fR
the first group capture \fINUM\fR that matched; requires option \fB-P\fR.
.IP \fB%[\fR\fINUM1\fR\fB|\fR\fINUM2\fR\fB|\fR...\fB]b\fR
the byte offset of the first group capture \fINUM\fR that matched; requires
option \fB-P\fR.  Use \fBe\fR for the ending byte offset and \fBd\fR for the
byte length.
.IP \fB%[\fR\fINAME\fR\fB]#\fR
the \fINAME\fRd group capture; requires option \fB-P\fR and capturing pattern
`(?<NAME>PATTERN)', see also \fB%G\fR.
.IP \fB%[\fR\fINAME\fR\fB]b\fR
the byte offset of the \fINAME\fRd group capture; requires option \fB-P\fR and
capturing pattern `(?<NAME>PATTERN)'.  Use \fBe\fR for the ending byte offset
and \fBd\fR for the byte length.
.IP \fB%[\fR\fINAME1\fR\fB|\fR\fINAME2|...\fR\fB]#\fR
the first \fINAME\fRd group capture that matched; requires option \fB-P\fR
and capturing pattern `(?<NAME>PATTERN)', see also \fB%G\fR.
.IP \fB%[\fR\fINAME1\fR\fB|\fR\fINAME2|...\fR\fB]b\fR
the byte offset of the first \fINAME\fRd group capture that matched; requires
option \fB-P\fR and capturing pattern `(?<NAME>PATTERN)'.  Use \fBe\fR for the
ending byte offset and \fBd\fR for the byte length.
.IP \fB%G\fR
list of group capture indices/names that matched; requires option \fB-P\fR.
.IP \fB%[\fR\fITEXT1\fR\fB|\fR\fITEXT2\fR\fB|...]G\fR
list of \fITEXT\fR indexed by group capture indices that matched; requires option \fB-P\fR.
.IP \fB%g\fR
the group capture index/name matched or 1; requires option \fB-P\fR.
.IP \fB%[\fR\fITEXT1\fR\fB|\fR\fITEXT2\fR\fB|\fR...\fB]g\fR
the first \fITEXT\fR indexed by the first group capture index that matched; requires option \fB-P\fR.
.IP \fB%%\fR
the percentage sign.
.PP
Formatted output is written without a terminating newline, unless \fB%~\fR or
`\\n' is explicitly specified in the format string.
.PP
The \fB[\fR\fITEXT\fR\fB]\fR part of a field is optional and may be omitted.
When present, the argument must be placed in \fB[]\fR brackets, for example
\fB%[,]F\fR to output a comma, the pathname, and a separator.
.PP
\fB%[\fR\fISEP\fR\fB]$\fR and \fB%u\fR are switches and do not send anything to
the output.
.PP
The separator used by the \fB%F\fR, \fB%H\fR, \fB%I\fR, \fB%N\fR, \fB%K\fR,
\fB%B\fR, \fB%S\fR and \fB%G\fR fields may be changed by preceding the field by
\fB%[\fR\fISEP\fR\fB]$\fR.  When \fB[\fR\fISEP\fR\fB]\fR is not provided, this
reverts the separator to the default separator or the separator specified with
\fB--separator\fR.
.PP
Formatted output is written for each matching pattern, which means that a line
may be output multiple times when patterns match more than once on the same
line.  If field \fB%u\fR is specified anywhere in a format string, matching
lines are output only once, unless option \fB-u\fR, \fB--ungroup\fR is
specified or when more than one line of input matched the search pattern.
.PP
Additional formatting options:
.IP \fB--format-begin\fR=\fIFORMAT\fR
the \fIFORMAT\fR when beginning the search.
.IP \fB--format-open\fR=\fIFORMAT\fR
the \fIFORMAT\fR when opening a file and a match was found.
.IP \fB--format-close\fR=\fIFORMAT\fR
the \fIFORMAT\fR when closing a file and a match was found.
.IP \fB--format-end\fR=\fIFORMAT\fR
the \fIFORMAT\fR when ending the search.
.PP
The context options \fB-A\fR, \fB-B\fR, \fB-C\fR, \fB-y\fR, and display options
\fB--break\fR, \fB--heading\fR, \fB--color\fR, \fB-T\fR, and \fB--null\fR have
no effect on formatted output.
.SH EXAMPLES
Display lines containing the word `patricia' in `myfile.txt':
.IP
$ ugrep -w patricia myfile.txt
.PP
Display lines containing the word `patricia', ignoring case:
.IP
$ ugrep -wi patricia myfile.txt
.PP
Display lines approximately matching the word `patricia', ignoring case and
allowing up to 2 spelling errors using fuzzy search:
.IP
$ ugrep -Z2 -wi patricia myfile.txt
.PP
Count the number of lines containing `patricia', ignoring case:
.IP
$ ugrep -cwi patricia myfile.txt
.PP
Count the number of words `patricia', ignoring case:
.IP
$ ugrep -cowi patricia myfile.txt
.PP
List lines with `amount' and a decimal, ignoring case (space is AND):
.IP
$ ugrep -i -% 'amount \\d+(\\.\\d+)?' myfile.txt
.PP
The same Boolean search query, but with options \fB-e\fR and \fB--and\fR:
.IP
$ ugrep -wi -e amount --and '\\d+(\\.\\d+)?' myfile.txt
.PP
List all Unicode words in a file:
.IP
$ ugrep -o '\\w+' myfile.txt
.PP
List the laughing face emojis (Unicode code points U+1F600 to U+1F60F):
.IP
$ ugrep -o '[\\x{1F600}-\\x{1F60F}]' myfile.txt
.PP
Check if a file contains any non-ASCII (i.e. Unicode) characters:
.IP
$ ugrep -q '[^[:ascii:]]' myfile.txt && echo "contains Unicode"
.PP
Display the line and column number of `FIXME' in C++ files using recursive
search, with one line of context before and after a matched line:
.IP
$ ugrep -C1 -R -n -k -tc++ FIXME
.PP
Display the line and column number of `FIXME' in long Javascript files using
recursive search, showing only matches with up to 10 characters of context
before and after:
.IP
$ ugrep -o -C20 -R -n -k -tjs FIXME
.PP
Find blocks of text between lines matching BEGIN and END by using a lazy
quantifier `*?' to match only what is necessary and pattern `\\n' to match
newlines:
.IP
$ ugrep -n 'BEGIN.*\\n(.*\\n)*?.*END' myfile.txt
.PP
Likewise, list the C/C++ comments in a file and line numbers:
.IP
$ ugrep -n -e '//.*' -e '/\\*(.*\\n)*?.*\\*+\\/' myfile.cpp
.PP
The same, but using predefined pattern c++/comments:
.IP
$ ugrep -n -f c++/comments myfile.cpp
.PP
List the lines that need fixing in a C/C++ source file by looking for the word
`FIXME' while skipping any `FIXME' in quoted strings:
.IP
$ ugrep -e FIXME -N '"(\\\\.|\\\\\\r?\\n|[^\\\\\\n"])*"' myfile.cpp
.PP
The same, but using predefined pattern cpp/zap_strings:
.IP
$ ugrep -e FIXME -f cpp/zap_strings myfile.cpp
.PP
Find lines with `FIXME' or `TODO', showing line numbers:
.IP
$ ugrep -n -e FIXME -e TODO myfile.cpp
.PP
Find lines with `FIXME' that also contain `urgent':
.IP
$ ugrep -n -e FIXME --and urgent myfile.cpp
.PP
The same, but with a Boolean query pattern (a space is AND):
.IP
$ ugrep -n -% 'FIXME urgent' myfile.cpp
.PP
Find lines with `FIXME' that do not also contain `later':
.IP
$ ugrep -n -e FIXME --andnot later myfile.cpp
.PP
The same, but with a Boolean query pattern (a space is AND, - is NOT):
.IP
$ ugrep -n -% 'FIXME -later' myfile.cpp
.PP
Output a list of line numbers of lines with `FIXME' but not `later':
.IP
$ ugrep -e FIXME --andnot later --format='%,%n' myfile.cpp
.PP
Recursively list all files with both `FIXME' and `LICENSE' anywhere in the
file, not necessarily on the same line:
.IP
$ ugrep -l -%% 'FIXME LICENSE'
.PP
Find lines with `FIXME' in the C/C++ files stored in a tarball:
.IP
$ ugrep -z -tc++ -n FIXME project.tgz
.PP
Recursively find lines with `FIXME' in C/C++ files, but do not search any `bak'
and `old' directories:
.IP
$ ugrep -n FIXME -tc++ -g^bak/,^old/
.PP
Recursively search for the word `copyright' in cpio, jar, pax, tar, zip, 7z
archives, compressed and regular files, and in PDFs using a PDF filter:
.IP
$ ugrep -z -w --filter='pdf:pdftotext % -' copyright
.PP
Match the binary pattern `A3hhhhA3' (hex) in a binary file without Unicode
pattern matching \fB-U\fR (which would otherwise match `\\xaf' as a Unicode
character U+00A3 with UTF-8 byte sequence C2 A3) and display the results in hex
with \fB--hexdump\fR with \fBC1\fR to output one hex line before and after each
match:
.IP
$ ugrep -U --hexdump=C1 '\\xa3[\\x00-\\xff]{2}\\xa3' a.out
.PP
Hexdump an entire file using a pager for viewing:
.IP
$ ugrep -X --pager '' a.out
.PP
List all files that are not ignored by one or more `.gitignore':
.IP
$ ugrep -l '' --ignore-files
.PP
List all files containing a RPM signature, located in the `rpm' directory and
recursively below up to two levels deeper (3 levels total):
.IP
$ ugrep -3 -l -tRpm '' rpm/
.PP
Monitor the system log for bug reports and ungroup multiple matches from
matching lines into separate lines:
.IP
$ tail -f /var/log/system.log | ugrep -u -i -w bug
.PP
Interactive fuzzy search with Boolean search queries:
.IP
$ ugrep -Q -l -% -Z2 --sort=best
.PP
Display all words in a MacRoman-encoded file that has CR newlines:
.IP
$ ugrep --encoding=MACROMAN '\\w+' mac.txt
.PP
Display options related to "fuzzy" searching:
.IP
$ ugrep --help fuzzy
.PP
.SH COPYRIGHT
Copyright (c) 2021-2025 Robert A. van Engelen <engelen@acm.org>
.PP
\fBugrep\fR 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.
.SH "SEE ALSO"
ugrep-indexer(1), grep(1), zgrep(1).
.SH BUGS
Report bugs at: <https://github.com/Genivia/ugrep/issues>