.TH UGREP "1" "August 06, 2021" "ugrep 3.3.7" "User Commands"
.SH NAME
\fBugrep\fR, \fBug\fR -- file pattern searcher
.SH SYNOPSIS
.B ugrep
[\fIOPTIONS\fR] [\fB-A\fR \fINUM\fR] [\fB-B\fR \fINUM\fR] [\fB-C \fR\fINUM\fR] [\fB-y\fR] [\fB-Q\fR|\fIPATTERN\fR] [\fB-f\fR \fIFILE\fR]
      [\fB-e\fR \fIPATTERN\fR] [\fB-N\fR \fIPATTERN\fR] [\fB-t\fR \fITYPES\fR] [\fB-g\fR \fIGLOBS\fR] [\fB--sort\fR[=\fIKEY\fR]]
      [\fB--color\fR[=\fIWHEN\fR]|\fB--colour\fR[=\fIWHEN\fR]] [\fB--pager\fR[=\fICOMMAND\fR]] [\fIFILE\fR \fI...\fR]
.SH DESCRIPTION
The \fBugrep\fR utility searches any given input files, selecting lines that
match one or more patterns.  By default, a pattern matches an input line if the
regular expression (RE) matches the input line.  A pattern matches multiple
input lines if the RE in the pattern matches one or more newlines in the input.
An empty pattern matches every line.  Each input line that matches at least one
of the patterns is written to the standard output.
.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; otherwise, \fBugrep\fR assumes the input is ASCII,
UTF-8, or raw binary.  An input encoding format may be specified with option
\fB--encoding\fR.
.PP
The \fBug\fR command is equivalent to \fBugrep --config\fR to load the default
configuration file, which allows for customization, see CONFIGURATION.
.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
into subdirectories, unless \fB-R\fR, \fB-r\fR, or \fB-2\fR...\fB-9\fR is
specified.
.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
A query interface is opened with \fB-Q\fR (\fB--query\fR) to interactively
specify search patterns and view search results.  Note that a \fIPATTERN\fR
argument cannot be specified in this case.  To specify one or more patterns
with \fB-Q\fR, use \fB-e PATTERN\fR.
.PP
For help, \fB--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
Print NUM lines of trailing context after matching lines.  Places
a \fB\-\-group\-separator\fR between contiguous groups of matches.  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 commands.
.TP
\fB\-\-and\fR [[\fB\-e\fR] PATTERN] ... \fB\-e\fR \fIPATTERN\fR
Specify additional patterns to match.  Patterns must be specified
with \fB\-e\fR.  Each \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.  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, and \fB\-\-bool\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
Print NUM lines of leading context before matching lines.  Places
a \fB\-\-group\-separator\fR between contiguous groups of matches.  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 matched line is displayed in front of the
respective matched line.  If \fB\-u\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 byte 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.  A match is considered binary when matching a zero
byte or invalid UTF.  Short options are \fB\-a\fR, \fB\-I\fR, \fB\-U\fR, \fB\-W\fR, and \fB\-X\fR.
.TP
\fB\-\-bool\fR, \fB\-%\fR
Specifies Boolean search patterns.  A Boolean search 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'.  Parenthesis 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
search pattern are regular expressions, unless option \fB\-F\fR is used.
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.  Option \fB\-\-stats\fR
displays the search patterns applied.  See also options \fB\-\-and\fR,
\fB\-\-andnot\fR, and \fB\-\-not\fR.
.TP
\fB\-\-break\fR
Adds a line break between results from different files.
.TP
\fB\-C\fR \fINUM\fR, \fB\-\-context\fR=\fINUM\fR
Print NUM lines of leading and trailing context surrounding each
match.  Places a \fB\-\-group\-separator\fR between contiguous groups of
matches.  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.
If \fB\-o\fR or \fB\-u\fR is specified, counts the number of patterns matched.
If \fB\-v\fR is specified, counts the number of non\-matching lines.
.TP
\fB\-\-color\fR[=\fIWHEN\fR], \fB\-\-colour\fR[=\fIWHEN\fR]
Mark up the matching text with the expression stored in 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).  Parameter values
are ANSI SGR color 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
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
with option \fB\-v\fR.  Selectively overrides GREP_COLORS.
.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.
.TP
\fB\-\-confirm\fR
Confirm actions in \fB\-Q\fR query mode.  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.  If \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.  By default, ACTION is `skip', which means that devices are
silently skipped.  If ACTION is `read', devices read just as if
they were ordinary files.
.TP
\fB\-d\fR \fIACTION\fR, \fB\-\-directories\fR=\fIACTION\fR
If an input file is a directory, use ACTION to process it.  By
default, ACTION is `skip', i.e., silently skip directories unless
specified on the command line.  If ACTION is `read', warn when
directories are read as input.  If 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.  If ACTION is `dereference\-recurse', read all files under
each directory, recursively, following symbolic links.  This is
equivalent to the \fB\-R\fR option.
.TP
\fB\-\-depth\fR=[\fIMIN\fR,][\fIMAX\fR], \fB\-1\fR, \fB\-2\fR ... \fB\-9\fR, \fB\-\-10\fR, \fB\-\-11\fR ...
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.  Note that \fB\-3\fR \fB\-5\fR, \fB\-3\fR\-5, or \fB\-3\fR5 searches 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 used during the search of the input: an input
line is selected if it matches any of the specified patterns.
Note that longer patterns take precedence over shorter patterns.
This option is most useful when multiple \fB\-e\fR options are used to
specify multiple patterns, when a pattern begins with a dash (`\-'),
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, where 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'.
.TP
\fB\-\-exclude\fR=\fIGLOB\fR
Skip files whose name matches GLOB using wildcard matching, 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 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.  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 can 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 `#' and empty lines in FILE are ignored.  When FILE
is a `\-', standard input is read.  This option may be repeated.
.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 of
directories on file systems.  Note that \fB\-\-exclude\-fs\fR mounts take
priority over \fB\-\-include\-fs\fR mounts.  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\-\-filter\fR=\fICOMMANDS\fR
Filter files through the specified COMMANDS first before searching.
COMMANDS is a comma\-separated list of `exts:command [option ...]',
where `exts' is a comma\-separated list of filename extensions and
`command' is a filter utility.  The filter utility should read from
standard input and write to standard output.  Files matching one of
`exts' are filtered.  When `exts' is `*', files with non\-matching
extensions are filtered.  One or more `option' separated by spacing
may be specified, which are passed verbatim to the command.  A `%'
as `option' expands into the pathname to search.  For example,
\fB\-\-filter\fR='pdf:pdftotext % \-' searches PDF files.  The `%' expands
into a `\-' when searching standard input.  Option \fB\-\-label\fR=.ext may
be used to specify extension `ext' when searching standard input.
.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 `%~'.  Context options \fB\-A\fR, \fB\-B\fR, \fB\-C\fR, and \fB\-y\fR are
ignored.  See `man ugrep' section FORMAT.
.TP
\fB\-\-free\-space\fR
Spacing (blanks and tabs) in regular expressions are ignored.
.TP
\fB\-G\fR, \fB\-\-basic\-regexp\fR
Interpret pattern as a basic regular expression, i.e. make ugrep
behave as traditional grep.
.TP
\fB\-g\fR \fIGLOBS\fR, \fB\-\-glob\fR=\fIGLOBS\fR
Search only 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.  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 `/'
matches the working directory.  This option may be repeated and may
be combined with options \fB\-M\fR, \fB\-O\fR and \fB\-t\fR to expand the recursive
search.
.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\-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.
.TP
\fB\-\-help\fR [\fIWHAT\fR], \fB\-?\fR [\fIWHAT\fR]
Display a help message, specifically on WHAT when specified.
.TP
\fB\-\-hexdump\fR=[1\-8][a][b][c][h]
Output matches in 1 to 8 columns of 8 hexadecimal octets.  The
default is 2 columns or 16 octets per line.  Option `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 and
`h' removes hex spacing.  Enables \fB\-X\fR if \fB\-W\fR or \fB\-X\fR is not specified.
.TP
\fB\-\-hidden\fR, \fB\-.\fR
Search hidden files and directories.
.TP
\fB\-\-hyperlink\fR
Hyperlinks are enabled for file names when colors are enabled.
Same as \fB\-\-colors\fR=hl.
.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.
.TP
\fB\-i\fR, \fB\-\-ignore\-case\fR
Perform case insensitive matching.  By default, ugrep is case
sensitive.  By default, this option applies to ASCII letters only.
Use options \fB\-P\fR and \fB\-i\fR for Unicode case insensitive matching.
.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 a FILE's location and in directories below are ignored
by temporarily overriding the \fB\-\-exclude\fR and \fB\-\-exclude\-dir\fR globs,
as if \fB\-\-exclude\-from\fR=\fIFILE\fR is locally enforced.  Globbing is the
same as \fB\-\-exclude\-from\fR=\fIFILE\fR and supports gitignore syntax, but
directories are not automatically excluded from searches (use a
glob ending with a `/' to identify directories to ignore, same as
git).  Files and directories explicitly specified as command line
arguments are never ignored.  This option may be repeated.
.TP
\fB\-\-include\fR=\fIGLOB\fR
Search only files whose name matches GLOB using wildcard matching,
same as \fB\-g\fR \fIGLOB\fR.  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
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 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.  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 can 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 of directories on file systems.  \fB\-\-include\-fs\fR=. restricts
recursive searches to the file system of the working directory
only.  Note that \fB\-\-exclude\-fs\fR mounts take priority over
\fB\-\-include\-fs\fR mounts.  This option may be repeated.
.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 like option \fB\-i\fR, unless a pattern
is specified with a literal ASCII upper case letter.
.TP
\fB\-\-json\fR
Output file matches in JSON.  If \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 \fIFIRST\fR[,\fILAST\fR], \fB\-\-range\fR=\fIFIRST\fR[,\fILAST\fR]
Start searching at line FIRST, stop at line LAST when specified.
.TP
\fB\-k\fR, \fB\-\-column\-number\fR
The column number of a matched pattern is displayed in front of the
respective matched line, starting at column 1.  Tabs are expanded
when columns are counted, 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.  ugrep will only search a file until a match has
been found, making searches potentially less expensive.  Pathnames
are listed once per file searched.  If the standard input is
searched, the string ``(standard input)'' is written.
.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\-M\fR \fIMAGIC\fR, \fB\-\-file\-magic\fR=\fIMAGIC\fR
Only files matching the signature pattern MAGIC are searched.  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 to expand the search.  Every file on the
search path is read, making searches potentially more expensive.
.TP
\fB\-m\fR \fINUM\fR, \fB\-\-max\-count\fR=\fINUM\fR
Stop reading the input after NUM matches in each input file.
.TP
\fB\-\-match\fR
Match all input.  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, the number of threads spawned is limited to NUM.
.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 used during the search of the input:
an input line is selected only if it matches any of the specified
patterns unless a subpattern of PATTERN.  Same as \fB\-e\fR (?^PATTERN).
Negative PATTERN matches are essentially removed before any other
patterns are matched.  Note that longer patterns take precedence
over shorter patterns.  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\-\-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\-\-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, and \fB\-\-bool\fR.
.TP
\fB\-O\fR \fIEXTENSIONS\fR, \fB\-\-file\-extension\fR=\fIEXTENSIONS\fR
Search only files whose filename extensions match the specified
comma\-separated list of EXTENSIONS, same as \fB\-\-include\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\-\-exclude\fR='*.ext'.  This option may be repeated and may be combined
with options \fB\-g\fR, \fB\-M\fR and \fB\-t\fR to expand the recursive search.
.TP
\fB\-o\fR, \fB\-\-only\-matching\fR
Print only the matching part of lines.  When multiple lines match,
the line numbers with option \fB\-n\fR are displayed using `|' as the
field separator for each additional line matched by the pattern.
If \fB\-u\fR is specified, ungroups multiple matches on the same line.
This option cannot be combined with options \fB\-A\fR, \fB\-B\fR, \fB\-C\fR, \fB\-v\fR, and \fB\-y\fR.
.TP
\fB\-\-only\-line\-number\fR
The line number of the matching line in the file is output without
displaying the match.  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.
.TP
\fB\-p\fR, \fB\-\-no\-dereference\fR
If \fB\-R\fR or \fB\-r\fR is specified, no symbolic links are followed, even when
they 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.  The default COMMAND is `less \fB\-R\fR'.  Enables \fB\-\-heading\fR
and \fB\-\-line\-buffered\fR.
.TP
\fB\-\-pretty\fR
When output is sent to a terminal, enables \fB\-\-color\fR, \fB\-\-heading\fR, \fB\-n\fR,
\fB\-\-sort\fR and \fB\-T\fR when not explicitly disabled or set.
.TP
\fB\-Q\fR[\fIDELAY\fR], \fB\-\-query\fR[=\fIDELAY\fR]
Query mode: user interface 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 5 (0.5s 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.
The command can be specified with option \fB\-\-view\fR, or defaults to
environment variable PAGER if defined, or EDITOR.  Press Tab and
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 fuzziness and ALT\-} to increase context.  Enables
\fB\-\-heading\fR.  See also options \fB\-\-confirm\fR and \fB\-\-view\fR.
.TP
\fB\-q\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR
Quiet mode: suppress all output.  ugrep will only search until a
match has been found.
.TP
\fB\-R\fR, \fB\-\-dereference\-recursive\fR
Recursively read all files under each directory.  Follow all
symbolic links, unlike \fB\-r\fR.  When \fB\-J\fR1 is specified, files are
searched in the same order as specified.  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\-r\fR, \fB\-\-recursive\fR
Recursively read all files under each directory, following symbolic
links only if they are on the command line.  When \fB\-J\fR1 is specified,
files are searched in the same order as specified.
.TP
\fB\-S\fR, \fB\-\-dereference\fR
If \fB\-r\fR is specified, all symbolic links are followed, like \fB\-R\fR.  The
default is not to follow symbolic links.
.TP
\fB\-s\fR, \fB\-\-no\-messages\fR
Silent mode: nonexistent and unreadable files are ignored, i.e.
their error messages are suppressed.
.TP
\fB\-\-save\-config\fR[=\fIFILE\fR]
Save configuration FILE.  By default `.ugrep' is saved.  If FILE is
a `\-', write the configuration to standard output.
.TP
\fB\-\-separator\fR[=\fISEP\fR]
Use SEP as field separator between file name, line number, column
number, byte offset, and the matched line.  The default is a colon
(`:').
.TP
\fB\-\-sort\fR[=\fIKEY\fR]
Displays matching files in the order specified by KEY in recursive
searches.  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 the input files), `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.  Normally ugrep displays
matches in no particular order to improve performance.
.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.  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.  This
option may be repeated.  The possible file types can be (where
\fB\-t\fRlist displays a detailed list):
`actionscript', `ada', `asm', `asp', `aspx', `autoconf', `automake',
`awk', `Awk', `basic', `batch', `bison', `c', `c++',
`clojure', `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', `shell', `Shell', `smalltalk', `sql', `svg', `swift',
`tcl', `tex', `text', `tiff', `Tiff', `tt', `typescript',
`verilog', `vhdl', `vim', `xml', `Xml', `yacc', `yaml'.
.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, 2, 4, or 8.  The default tab 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\-U\fR, \fB\-\-binary\fR
Disables Unicode matching for binary file matching, forcing PATTERN
to match bytes, not Unicode characters.  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.  See also option \fB\-\-dotall\fR.
.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,
using `+' as the field separator.
.TP
\fB\-V\fR, \fB\-\-version\fR
Display version information 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[=\fICOMMAND\fR]
Use COMMAND to view/edit a file in query mode when pressing CTRL\-Y.
.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.
.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 characters are letters, digits, and the
underscore.  With option \fB\-P\fR, word characters are Unicode letters,
digits, and underscore.  This option has no effect if \fB\-x\fR is also
specified.  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\-X\fR, \fB\-\-hex\fR
Output matches in hexadecimal.  This option is equivalent to the
\fB\-\-binary\-files\fR=hex option.  See also option \fB\-\-hexdump\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 $.  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\-\-xml\fR
Output file matches in XML.  If \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
Permits empty matches.  By default, empty matches are disabled,
unless a pattern begins with `^' or ends with `$'.  With this
option, empty\-matching patterns such as x? and x*, match all input,
not only lines containing the character `x'.
.TP
\fB\-y\fR, \fB\-\-any\-line\fR
Any matching or non\-matching line is output.  Non\-matching lines
are output with the `\-' separator as context of the matching lines.
See also options \fB\-A\fR, \fB\-B\fR, and \fB\-C\fR.
.TP
\fB\-Z\fR[[+\-~]MAX], \fB\-\-fuzzy\fR[=[+\-~]MAX]
Fuzzy mode: report approximate pattern matches within MAX errors.
By default, MAX is 1: one deletion, insertion or substitution is
allowed.  When `+' and/or `\-' precede MAX, only insertions and/or
deletions are allowed, respectively.  When `~' precedes MAX,
substitution counts as one error.  For example, \fB\-Z\fR+~3 allows up to
three insertions or substitutions, but no deletions.  The first
character of an approximate match always matches the begin of a
pattern.  Option \fB\-\-sort\fR=best orders matching files by best match.
No whitespace may be given between \fB\-Z\fR and its argument.
.TP
\fB\-z\fR, \fB\-\-decompress\fR
Decompress files to search, when compressed.  Archives (.cpio,
\&.pax, .tar and .zip) and compressed archives (e.g. .taz, .tgz,
\&.tpz, .tbz, .tbz2, .tb2, .tz2, .tlz, .txz, .tzst) are searched and
matching pathnames of files in archives are output in braces.  If
\fB\-g\fR, \fB\-O\fR, \fB\-M\fR, or \fB\-t\fR is specified, searches files within archives
whose name matches globs, matches file name extensions, matches
file signature magic bytes, or matches file types, respectively.
Supported compression formats: gzip (.gz), compress (.Z), zip,
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).
.TP
\fB\-0\fR, \fB\-\-null\fR
Prints a zero\-byte (NUL) 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.
.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
The regular expression pattern syntax is an extended form of the POSIX ERE
syntax.  For an overview of the syntax see README.md or visit:
.IP
https://github.com/Genivia/ugrep
.PP
Note that `.' 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.
.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 context-dependent interactive searching
and is equivalent to the \fBugrep --config\fR command to load the default
configuration file `.ugrep' when present in the working directory or 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, located 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 current 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--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 and basenames
in recursive searches.  Glob arguments for these options should be quoted to
prevent shell globbing.
.PP
Globbing supports gitignore syntax and the corresponding matching rules, except
that a glob normally matches files but not directories.  If a glob ends in a
path separator `/', then it matches directories but not files, as if
\fB--include-dir\fR or \fB--exclude-dir\fR is specified.  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 `/' to force \fB/*.h\fR to match foo.h 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 a /.
.IP \fB?\fR
Matches any one character except a /.
.IP \fB[a-z]\fR
Matches one character in the selected range of characters.
.IP \fB[^a-z]\fR
Matches one character not in the selected range of characters.
.IP \fB[!a-z]\fR
Matches one character not in the selected range of characters.
.IP \fB/\fR
When used at the begin of a glob, matches if pathname has no /.
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\\\\?\fR
Matches a ? (or any 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\\\\?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
Glob patterns specified with prefix `!' in any of the files associated with
--include-from, --exclude-from and --ignore-files will negate a previous glob
match.  That is, any matching file or directory excluded by a previous glob
pattern specified in the files associated with --exclude-from or --ignore-file
will become included again.  Likewise, any matching file or directory included
by a previous glob pattern specified in the files associated with
--include-from will become excluded again.
.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.
.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.  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
SGR substring for selected lines.
.IP \fBcx=\fR
SGR substring for context lines.
.IP \fBrv\fR
Swaps the \fBsl=\fR and \fBcx=\fR capabilities when \fB-v\fR is specified.
.IP \fBmt=\fR
SGR substring for matching text in any matching line.
.IP \fBms=\fR
SGR substring for matching text in a selected line.  The substring \fBmt=\fR by
default.
.IP \fBmc=\fR
SGR substring for matching text in a context line.  The substring \fBmt=\fR by
default.
.IP \fBfn=\fR
SGR substring for filenames.
.IP \fBln=\fR
SGR substring for line numbers.
.IP \fBcn=\fR
SGR substring for column numbers.
.IP \fBbn=\fR
SGR substring for byte offsets.
.IP \fBse=\fR
SGR substring for 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.
.SH FORMAT
Option \fB--format\fR=\fIFORMAT\fR specifies an output format for file matches.
Fields may be used in \fIFORMAT\fR, which expand into the following values:
.IP \fB%[\fR\fIARG\fR\fB]F\fR
if option \fB-H\fR is used: \fIARG\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\fIARG\fR\fB]H\fR
if option \fB-H\fR is used: \fIARG\fR, the quoted pathname and separator, \\"
and \\\\ replace " and \\.
.IP \fB%h\fR
the quoted file pathname, \\" and \\\\ replace " and \\.
.IP \fB%[\fR\fIARG\fR\fB]N\fR
if option \fB-n\fR is used: \fIARG\fR, the line number and separator.
.IP \fB%n\fR
the line number of the match.
.IP \fB%[\fR\fIARG\fR\fB]K\fR
if option \fB-k\fR is used: \fIARG\fR, the column number and separator.
.IP \fB%k\fR
the column number of the match.
.IP \fB%[\fR\fIARG\fR\fB]B\fR
if option \fB-b\fR is used: \fIARG\fR, the byte offset and separator.
.IP \fB%b\fR
the byte offset of the match.
.IP \fB%[\fR\fIARG\fR\fB]T\fR
if option \fB-T\fR is used: \fIARG\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\fIARG\fR\fB]<\fR
if the first match: \fIARG\fR.
.IP \fB%[\fR\fIARG\fR\fB]>\fR
if not the first match: \fIARG\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\fIARG\fR\fB]S\fR
if not the first match: \fIARG\fR and separator, see also \fB%$\fR.
.IP \fB%s\fR
the separator, see also \fB%S\fR and \fB%$\fR.
.IP \fB%~\fR
a newline character.
.IP \fB%m\fR
the number of matches or matched files.
.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\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\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\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%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\fIARG\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%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 both `amount' and a decimal number, ignoring case:
.IP
$ ugrep -wi --bool 'amount \d+(\.\d+)?' myfile.txt
.PP
Alternative query:
.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 all ASCII words in a file:
.IP
$ ugrep -o '[[:word:]]+' 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
List the C/C++ comments in a file with line numbers:
.IP
$ ugrep -n -e '//.*' -e '/\\*([^*]|(\\*+[^*/]))*\\*+\\/' 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':
.IP
$ ugrep -n -e FIXME -e TODO myfile.cpp
.PP
Find lines with `FIXME' that also contain the word `urgent':
.IP
$ ugrep -n FIXME myfile.cpp | ugrep -w urgent
.PP
Find lines with `FIXME' but not the word `later':
.IP
$ ugrep -n FIXME myfile.cpp | ugrep -v -w later
.PP
Output a list of line numbers of lines with `FIXME' but not `later':
.IP
$ ugrep -n FIXME myfile.cpp | ugrep -vw later | 
  ugrep -P '^(\\d+)' --format='%,%n'
.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 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 `A3hhhhA3hh' (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-X\fR using `less -R' as a pager:
.IP
$ ugrep --pager -UXo '\\xa3[\\x00-\\xff]{2}\\xa3[\\x00-\\xff]' a.out
.PP
Hexdump an entire file:
.IP
$ ugrep -X '' 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 on a line:
.IP
$ tail -f /var/log/system.log | ugrep -u -i -w bug
.PP
Interactive fuzzy search with Boolean search queries:
.IP
$ ugrep -Q --bool -Z3 --sort=best
.PP
Display all words in a MacRoman-encoded file that has CR newlines:
.IP
$ ugrep --encoding=MACROMAN '\\w+' mac.txt
.PP
Display all options related to "fuzzy" searching:
.IP
$ ugrep --help fuzzy
.SH BUGS
Report bugs at:
.IP
https://github.com/Genivia/ugrep/issues
.PP
.SH LICENSE
\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"
grep(1).