FreeBSD Manual Pages
UGREP(1) User Commands UGREP(1) NAME ugrep, ug -- file pattern searcher SYNOPSIS ugrep [OPTIONS] [-i|-j] [-Q|PATTERN] [-e PATTERN] [-N PATTERN] [-f FILE] [-E|-F|-G|-P|-Z] [-U] [-m [MIN,][MAX]] [--bool [--files|--lines]] [-r|-R|-1|...|-9|-10|-11|...] [-t TYPES] [-g GLOBS] [--sort[=KEY]] [-q|-l|-c|-o] [-v] [-n] [-k] [-b] [-A NUM] [-B NUM] [-C NUM] [-y] [--color[=WHEN]|--colour[=WHEN]] [--pretty] [--pager[=COMMAND]] [--hexdump|--csv|--json|--xml] [-I] [-z] [--zmax=NUM] [FILE ...] DESCRIPTION The ugrep 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. The ug 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. ug is equivalent to ugrep --config --pretty --sort to load a configuration file, enhance the ter- minal output, and to sort files by name. The ugrep+ and ug+ commands are the same as the ugrep and ug commands, but also use filters to search pdfs, documents, e-books, and image metadata, when the corresponding filter tools are installed. A list of matching files is produced with option -l (--files-with- matches). Option -c (--count) counts the number of matching lines. When combined with option -o, counts the total number of matches. When combined with option -m1, (--min-count=1), skips files with zero matches. The default pattern syntax is an extended form of the POSIX ERE syntax, same as option -E (--extended-regexp). Try ug --help regex for help with pattern syntax and how to use logical connectives to specify Boolean search queries with option -% (--bool) to match lines and -%% (--bool --files) to match files. Options -F (--fixed-strings), -G (--basic-regexp) and -P (--perl-regexp) specify other pattern syntaxes. Option -i (--ignore-case) ignores letter case in patterns. Option -j (--smart-case) enables -i only if the search patterns are specified in lower case. Fuzzy (approximate) search is specified with option -Z (--fuzzy) with an optional argument to control character insertions, deletions, and/or substitutions. Try ug --help fuzzy for help with fuzzy search. Note that pattern `.' matches any non-newline character. Pattern `\n' matches a newline character. Multiple lines may be matched with pat- terns that match one or more newline characters. The empty pattern "" matches all lines. Other empty-matching patterns do not. For example, the pattern `a*' will match one or more a's. Op- tion -Y forces empty matches for compatibility with other grep tools. Option -f FILE matches patterns specified in FILE. By default Unicode patterns are matched. Option -U (--ascii or --bi- nary) disables Unicode matching for ASCII and binary pattern matching. Non-Unicode matching is more efficient. ugrep accepts input of various encoding formats and normalizes the out- put 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 --encoding. If no FILE arguments are specified and standard input is read from a terminal, recursive searches are performed as if -r is specified. To force reading from standard input, specify `-' as a FILE argument. Directories specified as FILE arguments are searched without recursing deeper into subdirectories, unless -R, -r, or -2...-9 is specified to search subdirectories recursively (up to the specified depth.) Option -I (--ignore-binary) ignores binary files. A binary file is a file with non-text content. A file with zero bytes or invalid UTF for- matting is considered binary. Hidden files and directories are ignored in recursive searches. Option -. (--hidden) includes hidden files and directories in recursive searches. 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 -O specifies one or more filename extensions to match. Option -t spec- ifies one or more file types to search (-t list outputs a list of types.) Option -g specifies a gitignore-style glob pattern to match filenames. Option --ignore-files specifies a file with gitignore-style globs to ignore directories and files. Try ug --help globs for help with filename and directory name matching. See also section GLOBBING. Compressed files and archives are searched with option -z (--decom- press). When used with option --zmax=NUM, searches the contents of compressed files and archives stored within archives up to NUM levels. Output to a terminal for viewing is enhanced with --pretty, which is enabled by default with the ug command. A query terminal user interface (TUI) is opened with -Q (--query) to interactively specify search patterns and view search results. A PAT- TERN argument requires -e PATTERN to start the query TUI with the spec- ified pattern. A terminal output pager is enabled with --pager that accepts an op- tional COMMAND to view the output. Customized output is produced with option --format or --replace. Try ug --help format for help with custom formatting of the output. See also section FORMAT. Predefined formats include CSV with option --csv, JSON with option --json, and XML with option --xml. Hexdumps are out- put with option -X (--hex) or with option --hexdump to customize hex- dumps. A `--' signals the end of options; the rest of the parameters are FILE arguments, allowing filenames to begin with a `-' character. Long options may start with `--no-' to disable, when applicable. ug --help WHAT displays help on options related to WHAT. The following options are available: -A NUM, --after-context=NUM Output NUM lines of trailing context after matching lines. Places a --group-separator between contiguous groups of matches. If -o is specified, output the match with context to fit NUM columns after the match or shortens the match. See also options -B, -C and -y. -a, --text Process a binary file as if it were text. This is equivalent to the --binary-files=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 com- mands. --all, -@ Search all files except hidden: cancel previous file and direc- tory search restrictions and cancel --ignore-binary and --ig- nore-files 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 includ- ing hidden files. Note that hidden files and directories are never searched, unless option -. or --hidden is specified. --and [-e] PATTERN Specify additional PATTERN that must match. Additional -e PAT- TERN following this option is considered an alternative pattern to match, i.e. each -e is interpreted as an OR pattern enclosed within the AND. For example, -e A -e B --and -e C -e D matches lines with (`A' or `B') and (`C' or `D'). Note that multiple -e PATTERN are alternations that bind more tightly together than --and. Option --stats displays the search patterns applied. See also options --not, --andnot, --bool, --files and --lines. --andnot [-e] PATTERN Combines --and --not. See also options --and, --not and --bool. -B NUM, --before-context=NUM Output NUM lines of leading context before matching lines. Places a --group-separator between contiguous groups of matches. If -o is specified, output the match with context to fit NUM columns before the match or shortens the match. See also op- tions -A, -C and -y. -b, --byte-offset The offset in bytes of a pattern match is displayed in front of the respective matched line. When -u or --ungroup 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 dis- played. --binary-files=TYPE 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 hexadeci- mal. `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 op- tion -U or --ascii or --binary is specified. Short options are -a, -I, -W, -X. --bool, -%, -%% 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' oper- ator binds more tightly than `AND'. For example, --bool 'A|B C|D' matches lines with (`A' or `B') and (`C' or `D'), --bool 'A -B' matches lines with `A' and not `B'. Operators `AND', `OR', `NOT' require proper spacing. For example, --bool 'A OR B AND C OR D' matches lines with (`A' or `B') and (`C' or `D'), --bool 'A AND NOT B' matches lines with `A' without `B'. Quoted sub- patterns are matched literally as strings. For example, --bool 'A "AND"|"OR"' matches lines with `A' and also either `AND' or `OR'. Parentheses are used for grouping. For example, --bool '(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 -F is specified. Options -E, -F, -G, -P and -Z can be combined with --bool to match subpatterns as strings or regular expressions (-E is the default.) This option does not apply to -f FILE patterns. The double short option -%% en- ables options --bool --files. Option --stats displays the Boolean search patterns applied. See also options --and, --and- not, --not, --files and --lines. --break Adds a line break between results from different files. This option is enabled by --heading. -C NUM, --context=NUM Output NUM lines of leading and trailing context surrounding each matching line. Places a --group-separator between contigu- ous groups of matches. If -o is specified, output the match with context to fit NUM columns before and after the match or shortens the match. See also options -A, -B and -y. -c, --count Only a count of selected lines is written to standard output. When -o or -u is specified, counts the number of patterns matched. When -v is specified, counts the number of non-match- ing lines. When -m1, (with a comma or --min-count=1) is speci- fied, counts only matching files without outputting zero matches. --color[=WHEN], --colour[=WHEN] Mark up the matching text with the colors specified with option --colors 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'. --colors=COLORS, --colours=COLORS 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). Para- meter `hl' enables file name hyperlinks. Parameter `rv' re- verses the `sl=' and `cx=' parameters when option -v is speci- fied. Selectively overrides GREP_COLORS. Legacy grep single parameter codes may be specified, for example --colors='7;32' or --colors=ig to set ms (match selected). --config[=FILE], ---[FILE] Use configuration FILE. The default FILE is `.ugrep'. The working directory is checked first for FILE, then the home di- rectory. 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 --config=FILE or --no-config is specified. --no-config Do not automatically load the default .ugrep configuration file. --no-confirm Do not confirm actions in -Q query TUI. The default is confirm. --cpp Output file matches in C++. See also options --format and -u. --csv Output file matches in CSV. When -H, -n, -k, or -b is speci- fied, additional values are output. See also options --format and -u. -D ACTION, --devices=ACTION If an input file is a device, FIFO or socket, use ACTION to process it. By default, ACTION is `skip', which means that de- vices are silently skipped. When ACTION is `read', devices read just as if they were ordinary files. -d ACTION, --directories=ACTION If an input file is a directory, use ACTION to process it. By default, ACTION is `skip', i.e., silently skip directories un- less specified on the command line. When ACTION is `read', warn when directories are read as input. When ACTION is `recurse', read all files under each directory, recursively, following sym- bolic links only if they are on the command line. This is equivalent to the -r option. When ACTION is `dereference-re- curse', read all files under each directory, recursively, fol- lowing symbolic links. This is equivalent to the -R option. --delay=DELAY Set the default -Q key response delay. Default is 3 for 300ms. --depth=[MIN,][MAX], -1, -2, -3, ... -9, -10, -11, ... Restrict recursive searches from MIN to MAX directory levels deep, where -1 (--depth=1) searches the specified path without recursing into subdirectories. The short forms -3 -5, -3-5 and -3,5 search 3 to 5 levels deep. Enables -r if -R or -r is not specified. --dotall Dot `.' in regular expressions matches anything, including new- line. Note that `.*' matches all input and should not be used. -E, --extended-regexp Interpret patterns as extended regular expressions (EREs). This is the default. -e PATTERN, --regexp=PATTERN Specify a PATTERN to search the input. An input line is se- lected if it matches any of the specified patterns. This option is useful when multiple -e options are used to specify multiple patterns, or when a pattern starts with a dash (`-'), or to specify a pattern after option -f or after the FILE arguments. --encoding=ENCODING The encoding format of the input. The default ENCODING is bi- nary or UTF-8 which are treated the same. Therefore, --encod- ing=binary has no effect. Contrast this with option -U or --ascii or --binary 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'. --exclude=GLOB Exclude files whose name matches GLOB, same as -g ^GLOB. GLOB can use **, *, ?, and [...] as wildcards and \ to quote a wild- card 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 --exclude-dir is specified. Otherwise files are excluded. Note that --exclude patterns take priority over --include pat- terns. GLOB should be quoted to prevent shell globbing. This option may be repeated. --exclude-dir=GLOB Exclude directories whose name matches GLOB from recursive searches, same as -g ^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 --ex- clude-dir patterns take priority over --include-dir patterns. GLOB should be quoted to prevent shell globbing. This option may be repeated. --exclude-from=FILE 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 char- acter 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 --exclude-dir 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. --exclude-fs=MOUNTS 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 --exclude-fs=MOUNTS take priority over --in- clude-fs=MOUNTS. This option may be repeated. -F, --fixed-strings Interpret pattern as a set of fixed strings, separated by new- lines, any of which is to be matched. This makes ugrep behave as fgrep. If a PATTERN is specified, or -e PATTERN or -N PAT- TERN, then this option has no effect on -f FILE patterns to al- low -f FILE patterns to narrow or widen the scope of the PATTERN search. -f FILE, --file=FILE Read newline-separated patterns from FILE. White space in pat- terns 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/lo- cal/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. --filter=COMMANDS Filter files through the specified COMMANDS first before search- ing. COMMANDS is a comma-separated list of `exts:command argu- ments', where `exts' is a comma-separated list of filename ex- tensions 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 argu- ment may be quoted to include spacing, commas or a `%'. A `%' argument expands into the pathname to search. For example, --filter='pdf:pdftotext % -' searches PDF files. The `%' ex- pands into a `-' when searching standard input. When a `%' is not specified, the filter command should read from standard in- put and write to standard output. Option --label=.ext may be used to specify extension `ext' when searching standard input. This option may be repeated. --filter-magic-label=[+]LABEL:MAGIC Associate LABEL with files whose signature "magic bytes" match the MAGIC regex pattern. Only files that have no filename ex- tension are labeled, unless +LABEL is specified. When LABEL matches an extension specified in --filter=COMMANDS, the corre- sponding command is invoked. This option may be repeated. --format=FORMAT Output FORMAT-formatted matches. For example --for- mat='%f:%n:%O%~' outputs matching lines `%O' with filename `%f` and line number `%n' followed by a newline `%~'. If -P is spec- ified, FORMAT may include `%1' to `%9', `%[NUM]#' and `%[NAME]#' to output group captures. A `%%' outputs `%'. See `ugrep --help format' and `man ugrep' section FORMAT for details. When option -o is specified, option -u is also enabled. Context op- tions -A, -B, -C and -y are ignored. --free-space Spacing (blanks and tabs) in regular expressions are ignored. --from=FILE Read additional pathnames of files to search from FILE. When FILE is a `-', standard input is read. This option is useful with `find -G, --basic-regexp Interpret patterns as basic regular expressions (BREs). -g GLOBS, --glob=GLOBS, --iglob=GLOBS Only search files whose name matches the specified comma-sepa- rated list of GLOBS, same as --include='glob' for each `glob' in GLOBS. When a `glob' is preceded by a `!' or a `^', skip files whose name matches `glob', same as --exclude='glob'. When `glob' contains a `/', full pathnames are matched and option -r is enabled to recurse into directories if -d, -r or -R is not already specified. Otherwise basenames are matched. When `glob' ends with a `/', directories are matched, same as --in- clude-dir='glob' and --exclude-dir='glob'. A leading `./' or just `/' matches the working directory. Option --iglob=GLOBS performs case-insensitive name matching. This option may be re- peated and may be combined with options -M, -O and -t. For more details, see `ugrep --help globs' and `man ugrep' section GLOB- BING for details. --glob-ignore-case Perform case-insensitive glob matching in general. --group-separator[=SEP] Use SEP as a group separator for context options -A, -B and -C. The default is a double hyphen (`--'). --no-group-separator Removes the group separator line from the output for context op- tions -A, -B and -C. -H, --with-filename Always print the filename with output lines. This is the de- fault when there is more than one file to search. -h, --no-filename Never print filenames with output lines. This is the default when there is only one file (or only standard input) to search. --heading, -+ Group matches per file. Adds a heading and a line break between results from different files. This option is enabled by --pretty when the output is sent to a terminal. --help [WHAT], -? [WHAT] Display a help message on options related to WHAT when speci- fied. In addition, `--help regex' displays an overview of regu- lar expressions, `--help globs' displays an overview of glob syntax and conventions, `--help fuzzy' displays details of fuzzy search, and `--help format' displays a list of option --for- mat=FORMAT fields. --hexdump[=[1-8][a][bch][A[NUM]][B[NUM]][C[NUM]]] Output matches in 1 to 8 columns of 8 hexadecimal octets. The default is 2 columns or 16 octets per line. Argument `a' out- puts a `*' for all hex lines that are identical to the previous hex line, `b' removes all space breaks, `c' removes the charac- ter 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 -A, -B and -C when used with --hexdump. See also options -U, -W and -X. --hidden, -. Search hidden files and directories (enabled by default in grep compatibility mode). --hyperlink[=[PREFIX][+]] Hyperlinks are enabled for file names when colors are enabled. Same as --colors=hl. When PREFIX is specified, replaces file:// with PREFIX:// in the hyperlink. A `+' includes the line number in the hyperlink and when option -k is specified, the column number. -I, --ignore-binary Ignore matches in binary files. This option is equivalent to the --binary-files=without-match option. Files having NUL (zero) bytes are binary. Also files with invalid UTF encoding are binary unless option -U or --ascii or --binary is specified. -i, --ignore-case Perform case insensitive matching. By default, ugrep is case sensitive. --ignore-files[=FILE] 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 di- rectory of the FILE and in subdirectories below are ignored. Globbing syntax is the same as the --exclude-from=FILE gitignore syntax, but files and directories are excluded instead of only files. Directories are specifically excluded when the glob ends in a `/'. Files and directories explicitly specified as command line arguments are never ignored. This option may be repeated to specify additional files. --no-ignore-files Do not ignore files, i.e. cancel --ignore-files when specified. --include=GLOB Only search files whose name matches GLOB, same as -g GLOB. 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 -r is enabled to re- curse into directories if -d, -r or -R is not already specified. Otherwise basenames are matched. When GLOB ends with a `/', di- rectories are included as if --include-dir is specified. Other- wise files are included. Note that --exclude patterns take pri- ority over --include patterns. GLOB should be quoted to prevent shell globbing. This option may be repeated. --include-dir=GLOB Only directories whose name matches GLOB are included in recur- sive searches, same as -g GLOB/. GLOB may use **, *, ?, and [...] as wildcards and \ to quote a wildcard or backslash char- acter literally. When GLOB contains a `/', full pathnames are matched and option -r is enabled to recurse into directories if -d, -r or -R is not already specified. Otherwise basenames are matched. Note that --exclude-dir patterns take priority over --include-dir patterns. GLOB should be quoted to prevent shell globbing. This option may be repeated. --include-from=FILE 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 --include-dir 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. --include-fs=MOUNTS 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, re- stricts recursive searches to the file system of the working di- rectory, same as --include-fs=. (dot). Note that --ex- clude-fs=MOUNTS take priority over --include-fs=MOUNTS. This option may be repeated. --index 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 -r or --recursive. Skips in- dexed non-matching files, archives and compressed files. Sig- nificant 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 -U or --ascii or --binary im- proves performance. Option --stats displays an index search re- port. -J NUM, --jobs=NUM Specifies the number of threads spawned to search files. By de- fault an optimum number of threads is spawned to search files simultaneously. -J1 disables threading: files are searched in the same order as specified. -j, --smart-case Perform case insensitive matching, unless a pattern is specified with a literal upper case letter. --json Output file matches in JSON. When -H, -n, -k, or -b is speci- fied, additional values are output. See also options --format and -u. -K [MIN,][MAX], --range=[MIN,][MAX], --min-line=MIN, --max-line=MAX Start searching at line MIN, stop at line MAX when specified. -k, --column-number The column number of a pattern match is displayed in front of the respective matched line, starting at column 1. Tabs are ex- panded in counting columns, see also option --tabs. -L, --files-without-match Only the names of files not containing selected lines are writ- ten to standard output. Pathnames are listed once per file searched. If the standard input is searched, the string ``(standard input)'' is written. -l, --files-with-matches 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. --label=LABEL Displays the LABEL value when input is read from standard input where a file name would normally be printed in the output. As- sociates a filename extension with standard input when LABEL has a suffix. The default value is `(standard input)'. --line-buffered Force output to be line buffered instead of block buffered. --lines Boolean line matching mode for option --bool, the default mode. -M MAGIC, --file-magic=MAGIC 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 -O and -t. Every file on the search path is read, making recursive searches potentially more expensive. -m [MIN,][MAX], --min-count=MIN, --max-count=MAX Require MIN matches, stop after MAX matches when specified. Output MIN to MAX matches. For example, -m1 outputs the first match and -cm1, (with a comma) counts nonzero matches. When -u or --ungroup is specified, each individual match counts. See also option -K. --match Match all input. Same as specifying an empty pattern to search. --max-files=NUM Restrict the number of files matched to NUM. Note that --sort or -J1 may be specified to produce replicable results. If --sort is specified, then the number of threads spawned is lim- ited to NUM. --mmap[=MAX] 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. -N PATTERN, --neg-regexp=PATTERN Specify a negative PATTERN to reject specific -e PATTERN matches with a counter pattern. Note that longer patterns take prece- dence over shorter patterns, i.e. a negative pattern must be of the same length or longer to reject matching patterns. Option -N cannot be specified with -P. This option may be repeated. -n, --line-number 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. --not [-e] PATTERN Specifies that PATTERN should not match. Note that -e A --not -e B matches lines with `A' or lines without a `B'. To match lines with `A' that have no `B', specify -e A --andnot -e B. Option --stats displays the search patterns applied. See also options --and, --andnot, --bool, --files and --lines. --null, -0 Output a zero byte after the file name. This option can be used with commands such as `find -print0' and `xargs -0' to process arbitrary file names, even those that contain newlines. See also options -H or --with-filename and --null-data. --null-data, -00 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 --encoding=ENCODING, output each line terminated by a zero byte without affecting the input specified as per ENCOD- ING. Instead of option --null-data, option --encoding=null-data treats the input as a sequence of lines terminated by a zero byte without affecting the output. Option --null-data is not compatible with UTF-16/32 input. See also options --encoding and --null. -O EXTENSIONS, --file-extension=EXTENSIONS Only search files whose filename extensions match the specified comma-separated list of EXTENSIONS, same as -g '*.ext' for each `ext' in EXTENSIONS. When an `ext' is preceded by a `!' or a `^', skip files whose filename extensions matches `ext', same as -g '^*.ext'. This option may be repeated and may be combined with options -g, -M and -t. -o, --only-matching Only the matching part of a pattern match is output. When -A, -B or -C is specified, fits the match and its context on a line within the specified number of columns. --only-line-number Only the line number of a matching line is output. The line number counter is reset for each file processed. --files, -%% Boolean file matching mode, the opposite of --lines. When com- bined with option --bool, matches a file if all Boolean condi- tions are satisfied. For example, --bool --files 'A B|C -D' matches a file if some lines match `A', and some lines match ei- ther `B' or `C', and no line matches `D'. See also options --and, --andnot, --not, --bool and --lines. The double short option -%% enables options --bool --files. -P, --perl-regexp Interpret PATTERN as a Perl regular expression using PCRE2. Note that Perl pattern matching differs from the default grep POSIX pattern matching. -p, --no-dereference If -R or -r is specified, do not follow symbolic links, even when symbolic links are specified on the command line. --pager[=COMMAND] 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 --heading and --line-buffered. --pretty[=WHEN] When output is sent to a terminal, enables --color, --heading, -n, --sort, --tree and -T when not explicitly disabled. WHEN can be `never', `always', or `auto'. The default is `auto'. -Q[=DELAY], --query[=DELAY] Query mode: start a TUI to perform interactive searches. This mode requires an ANSI capable terminal. An optional DELAY argu- ment 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 -Q and its argument DELAY. Initial patterns may be specified with -e PATTERN, i.e. a PATTERN argument re- quires option -e. 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 --view 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 EN- TER to select lines to output. Press ALT-l for option -l to list files, ALT-n for -n, 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 --no-confirm, --delay, --split and --view. -q, --quiet, --silent Quiet mode: suppress all output. Only search a file until a match has been found. -R, --dereference-recursive Recursively read all files under each directory, following sym- bolic links to files and directories, unlike -r. -r, --recursive Recursively read all files under each directory, following sym- bolic 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 -r is speci- fied. --replace=FORMAT Replace matching patterns in the output by FORMAT with `%' fields. If -P is specified, FORMAT may include `%1' to `%9', `%[NUM]#' and `%[NAME]#' to output group captures. A `%%' out- puts `%' and `%~' outputs a newline. See also option --format, `ugrep --help format' and `man ugrep' section FORMAT for de- tails. -S, --dereference-files When -r is specified, follow symbolic links to files, but not to directories. The default is not to follow symbolic links. -s, --no-messages Silent mode: nonexistent and unreadable files are ignored and their error messages and warnings are suppressed. --save-config[=FILE] [OPTIONS] Save configuration FILE to include OPTIONS. Update FILE when first loaded with --config=FILE. 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 speci- fied by editing the saved configuration file. A configuration file may be modified by adding one or more config=FILE to in- clude configuration files, but recursive configuration file in- clusion is not permitted. --separator[=SEP], --context-separator=SEP Use SEP as field separator between file name, line number, col- umn number, byte offset and the matched line. The default sepa- rator is a colon (`:') and a bar (`|') for multi-line pattern matches, and a dash (`-') for context lines. See also option --group-separator. --split Split the -Q query TUI screen on startup. --sort[=KEY] Displays matching files in the order specified by KEY in recur- sive 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 -Z (sort by best match requires two passes over files, which is ex- pensive), `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. --stats Output statistics on the number of files and directories searched and the inclusion and exclusion constraints applied. -T, --initial-tab Add a tab space to separate the file name, line number, column number and byte offset with the matched line. -t TYPES, --file-type=TYPES 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 -O and filenames passed to option -g. For capitalized file types, the search is expanded to in- clude files with matching file signature magic bytes, as if passed to option -M. 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 (-tlist 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', `ver- ilog', `vhdl', `vim', `xml', `Xml', `yacc', `yaml', `zig'. --tabs[=NUM] Set the tab size to NUM to expand tabs for option -k. The value of NUM may be 1 (no expansion), 2, 4, or 8. The default size is 8. --tag[=TAG[,END]] Disables colors to mark up matches with TAG. END marks the end of a match if specified, otherwise TAG. The default is `___'. --tree, -^ Output directories with matching files in a tree-like format for option -c or --count, -l or --files-with-matches, -L or --files-without-match. This option is enabled by --pretty when the output is sent to a terminal. -U, --ascii, --binary Disables Unicode matching for ASCII and binary matching. PAT- TERN matches bytes. For example, -U '\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. -u, --ungroup Do not group multiple pattern matches on the same matched line. Output the matched line again for each additional pattern match. -V, --version Display version with linked libraries and exit. -v, --invert-match Selected lines are those not matching any of the specified pat- terns. --view[=COMMAND] Use COMMAND to view/edit a file in -Q query TUI by pressing CTRL-Y. -W, --with-hex Output binary matches in hexadecimal, leaving text matches alone. This option is equivalent to the --binary-files=with-hex option. To omit the matching line from the hex output, use both options -W and --hexdump. See also options -U. -w, --word-regexp 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. --width[=NUM] 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. -X, --hex Output matches and matching lines in hexadecimal. This option is equivalent to the --binary-files=hex option. To omit the matching line from the hex output use option --hexdump. See also option -U. -x, --line-regexp Select only those matches that exactly match the whole line, as if the patterns are surrounded by ^ and $. --xml Output file matches in XML. When -H, -n, -k, or -b is speci- fied, additional values are output. See also options --format and -u. -Y, --empty 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 ex- pected pattern. This option is enabled by default in grep com- patibility mode; specify option --no-empty to prevent matching all lines. -y, --any-line, --passthru Any line is output (passthru). Non-matching lines are output as context with a `-' separator. See also options -A, -B and -C. -Z[best][+-~][MAX], --fuzzy[=[best][+-~][MAX]] Fuzzy mode: report approximate pattern matches within MAX er- rors. The default is -Z1: one deletion, insertion or substitu- tion is allowed. If `+`, `-' and/or `~' is specified, then `+' allows insertions, `-' allows deletions and `~' allows substitu- tions. For example, -Z+~3 allows up to three insertions or sub- stitutions, but no deletions. If `best' is specified, then only the best matching lines are output with the lowest cost per file. Option -Zbest requires two passes over a file and cannot be used with standard input or Boolean queries. Option --sort=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 charac- ter, replace it with a `.' or `.?'. Option -U applies fuzzy matching to ASCII and bytes instead of Unicode text. No white- space may be given between -Z and its argument. -z, --decompress 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 --zmax=NUM, searches the contents of com- pressed files and archives stored within archives up to NUM lev- els. When -g, -O, -M, or -t is specified, searches archives for files that match the specified globs, filename extensions, file signature magic bytes, or file types, respectively; a side-ef- fect 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 for- mats: gzip (.gz), compress (.Z), zip, 7z, bzip2 (.bz, .bz2, .bzip2, .tbz, .tbz2, .tb2, .tz2), xz (.xz, .txz) and lzma (re- quires suffix .lzma, .tlz), zstd (.zst, .zstd, .tzst), lz4 (re- quires suffix .lz4), brotli (requires suffix .br). --zmax=NUM When used with option -z or --decompress, searches the contents of compressed files and archives stored within archives by up to NUM expansion stages. The default --zmax=1 only permits search- ing uncompressed files stored in cpio, pax, tar, zip and 7z archives; compressed files and archives are detected as binary files and are effectively ignored. Specify --zmax=2 to 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 decompres- sion and de-archiving steps. Increasing NUM values gradually degrades performance. EXIT STATUS The ugrep utility exits with one of the following values: 0 One or more lines were selected. 1 No lines were selected. >1 An error occurred. If -q or --quiet or --silent is used and a line is selected, the exit status is 0 even if an error occurred. CONFIGURATION The ug command is intended for interactive searching and is equivalent to the ugrep --config --pretty --sort command to load the `.ugrep` con- figuration file located in the working directory or, when not found, in the home directory. A configuration file contains `NAME=VALUE' pairs per line, where `NAME` is the name of a long option (without `--') and `=VALUE' is an argu- ment, which is optional and may be omitted depending on the option. Empty lines and lines starting with a `#' are ignored. The --config=FILE option and its abbreviated form ---FILE load the specified configuration file located in the working directory or, when not found, in the home directory. An error is produced when FILE is not found or cannot be read. Command line options are parsed in the following order: the configura- tion file is loaded first, followed by the remaining options and argu- ments on the command line. The --save-config 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 --save-con- fig=FILE option saves the configuration to FILE. The configuration is written to standard output when FILE is a `-'. GLOBBING Globbing is used by options -g (--glob and --iglob), --include, --in- clude-dir, --include-from, --exclude, --exclude-dir, --exclude-from and --ignore-files to match pathnames or basenames in recursive searches. Glob arguments for these options should be quoted to prevent shell globbing. 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 --include-dir or --exclude-dir is specified. When a glob contains a path separator `/', the full pathname is matched. Oth- erwise the basename of a file or directory is matched. For example, *.h matches foo.h and bar/foo.h. bar/*.h matches bar/foo.h but not foo.h and not bar/bar/foo.h. Use a leading `./' or just `/' to force /*.h to match foo.h in the working directory but not bar/foo.h. When a glob starts with a `^' or a `!' as in -g^GLOB, the match is negated. Likewise, a `!' (but not a `^') may be used with globs in the files specified --include-from, --exclude-from, and --ignore-files to negate the glob match. Empty lines or lines starting with a `#' are ignored. Glob Syntax and Conventions * Matches anything except /. ? Matches any one character except /. [abc-e] Matches one character a,b,c,d,e. [^abc-e] Matches one character not a,b,c,d,e,/. [!abc-e] Matches one character not a,b,c,d,e,/. / When used at the start of a glob, matches the working directory. When used at the end of a glob, matches directories only. **/ Matches zero or more directories. /** When used at the end of a glob, matches everything after the /. \? Matches a ? or any other character specified after the back- slash. Glob Matching Examples * Matches a, b, x/a, x/y/b a Matches a, x/a, x/y/a, but not b, x/b, a/a/b /* Matches a, b, but not x/a, x/b, x/y/a /a Matches a, but not x/a, x/y/a a?b Matches axb, ayb, but not a, b, ab, a/b a[xy]b Matches axb, ayb but not a, b, azb a[a-z]b Matches aab, abb, acb, azb, but not a, b, a3b, aAb, aZb a[^xy]b Matches aab, abb, acb, azb, but not a, b, axb, ayb a[^a-z]b Matches a3b, aAb, aZb but not a, b, aab, abb, acb, azb a/*/b Matches a/x/b, a/y/b, but not a/b, a/x/y/b **/a Matches a, x/a, x/y/a, but not b, x/b. a/**/b Matches a/b, a/x/b, a/x/y/b, but not x/a/b, a/b/x a/** Matches a/x, a/y, a/x/y, but not a, b/x a\?b Matches a?b, but not a, b, ab, axb, a/b Note that exclude glob patterns take priority over include glob pat- terns when specified with options -g, --exclude, --exclude-dir, --in- clude and include-dir. 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 --ex- clude-from or --ignore-file will become included again. Likewise, any matching file or directory included by a previous glob pattern speci- fied in the files associated with --include-from will become excluded again. ENVIRONMENT GREP_PATH May be used to specify a file path to pattern files. The file path is used by option -f to open a pattern file, when the pat- tern file does not exist. Defaults to /usr/lo- cal/share/ugrep/patterns when GREP_PATH is undefined. GREP_COLOR May be used to specify ANSI SGR parameters to highlight matches when option --color is used, e.g. 1;35;40 shows pattern matches in bold magenta text on a black background. Deprecated in favor of GREP_COLORS, but still supported. GREP_COLORS May be used to specify ANSI SGR parameters to highlight matches and other attributes when option --color is used. Its value is a colon-separated list of ANSI SGR parameters that defaults to cx=33:mt=1;31:fn=1;35:ln=1;32:cn=1;32:bn=1;32:se=36 with addi- tional parameters for TUI colors :qp=1;32:qe=1;37;41:qm=1;32:ql=36:qb=1;35. The mt=, ms=, and mc= capabilities of GREP_COLORS take priority over GREP_COLOR. Option --colors takes priority over GREP_COLORS. GREP_COLORS Colors are specified as string of colon-separated ANSI SGR parameters of the form `what=substring', where `substring' is a semicolon-sepa- rated list of ANSI SGR codes or `k' (black), `r' (red), `g' (green), `y' (yellow), `b' (blue), `m' (magenta), `c' (cyan), `w' (white). Up- per 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: sl= selected lines. cx= context lines. rv swaps the sl= and cx= capabilities when -v is specified. mt= matching text in any matching line. ms= matching text in a selected line. The substring mt= by default. mc= matching text in a context line. The substring mt= by default. fn= filenames. ln= line numbers. cn= column numbers. bn= byte offsets. se= separators. rv a Boolean parameter, switches sl= and cx= with option -v. hl a Boolean parameter, enables filename hyperlinks (\33]8;;link). ne a Boolean parameter, disables ``erase in line'' \33[K. qp= TUI prompt. qe= TUI errors. qr= TUI regex. qm= TUI regex meta characters. ql= TUI regex lists and literals. qb= TUI regex braces. FORMAT Option --format=FORMAT specifies an output format for matches. Option --replace=FORMAT only replaces the matching patterns. Fields may be used in FORMAT, which expand into the following values: %[TEXT]F if option -H is used: TEXT, the file pathname and separator. %f the file pathname. %a the file basename without directory path. %p the directory path to the file. %z the file pathname in a (compressed) archive. %[TEXT]H if option -H is used: TEXT, the quoted pathname and separator, \" and \\ replace " and \. %h the quoted file pathname, \" and \\ replace " and \. %[TEXT]I if option -H is used: TEXT, the pathname as XML character data and separator. %i the file pathname as XML character data. %[TEXT]N if option -n is used: TEXT, the line number and separator. %n the line number of the match. %[TEXT]K if option -k is used: TEXT, the column number and separator. %k the column number of the match. %[TEXT]B if option -b is used: TEXT, the byte offset and separator. %b the byte offset of the match. %[TEXT]T if option -T is used: TEXT and a tab character. %t a tab character. %[SEP]$ set field separator to SEP for the rest of the format fields. %[TEXT]< if the first match: TEXT. %[TEXT]> if not the first match: TEXT. %, if not the first match: a comma, same as %[,]>. %: if not the first match: a colon, same as %[:]>. %; if not the first match: a semicolon, same as %[;]>. %| if not the first match: a vertical bar, same as %[|]>. %[TEXT]S if not the first match: TEXT and separator, see also %[SEP]$. %s the separator, see also %[TEXT]S and %[SEP]$. %~ a newline character. %M the number of matching lines %m the number of matches %O the matching line is output as a raw string of bytes. %o the match is output as a raw string of bytes. %Q the matching line as a quoted string, \" and \\ replace " and \. %q the match as a quoted string, \" and \\ replace " and \. %C the matching line formatted as a quoted C/C++ string. %c the match formatted as a quoted C/C++ string. %J the matching line formatted as a quoted JSON string. %j the match formatted as a quoted JSON string. %V the matching line formatted as a quoted CSV string. %v the match formatted as a quoted CSV string. %X the matching line formatted as XML character data. %x the match formatted as XML character data. %w the width of the match, counting wide characters. %d the size of the match, counting bytes. %e the ending byte offset of the match. %Z the edit distance cost of an approximate match with option -Z %u select unique lines only, unless option -u is used. %1 the first regex group capture of the match, and so on up to group %9, same as %[1]#; requires option -P. %[NUM]# the regex group capture NUM; requires option -P. %[NUM]b the byte offset of the group capture NUM; requires option -P. Use e for the ending byte offset and d for the byte length. %[NUM1|NUM2|...]# the first group capture NUM that matched; requires option -P. %[NUM1|NUM2|...]b the byte offset of the first group capture NUM that matched; re- quires option -P. Use e for the ending byte offset and d for the byte length. %[NAME]# the NAMEd group capture; requires option -P and capturing pat- tern `(?<NAME>PATTERN)', see also %G. %[NAME]b the byte offset of the NAMEd group capture; requires option -P and capturing pattern `(?<NAME>PATTERN)'. Use e for the ending byte offset and d for the byte length. %[NAME1|NAME2|...]# the first NAMEd group capture that matched; requires option -P and capturing pattern `(?<NAME>PATTERN)', see also %G. %[NAME1|NAME2|...]b the byte offset of the first NAMEd group capture that matched; requires option -P and capturing pattern `(?<NAME>PATTERN)'. Use e for the ending byte offset and d for the byte length. %G list of group capture indices/names that matched; requires op- tion -P. %[TEXT1|TEXT2|...]G list of TEXT indexed by group capture indices that matched; re- quires option -P. %g the group capture index/name matched or 1; requires option -P. %[TEXT1|TEXT2|...]g the first TEXT indexed by the first group capture index that matched; requires option -P. %% the percentage sign. Formatted output is written without a terminating newline, unless %~ or `\n' is explicitly specified in the format string. The [TEXT] part of a field is optional and may be omitted. When present, the argument must be placed in [] brackets, for example %[,]F to output a comma, the pathname, and a separator. %[SEP]$ and %u are switches and do not send anything to the output. The separator used by the %F, %H, %I, %N, %K, %B, %S and %G fields may be changed by preceding the field by %[SEP]$. When [SEP] is not pro- vided, this reverts the separator to the default separator or the sepa- rator specified with --separator. 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 %u is specified anywhere in a format string, matching lines are output only once, unless option -u, --un- group is specified or when more than one line of input matched the search pattern. Additional formatting options: --format-begin=FORMAT the FORMAT when beginning the search. --format-open=FORMAT the FORMAT when opening a file and a match was found. --format-close=FORMAT the FORMAT when closing a file and a match was found. --format-end=FORMAT the FORMAT when ending the search. The context options -A, -B, -C, -y, and display options --break, --heading, --color, -T, and --null have no effect on formatted output. EXAMPLES Display lines containing the word `patricia' in `myfile.txt': $ ugrep -w patricia myfile.txt Display lines containing the word `patricia', ignoring case: $ ugrep -wi patricia myfile.txt Display lines approximately matching the word `patricia', ignoring case and allowing up to 2 spelling errors using fuzzy search: $ ugrep -Z2 -wi patricia myfile.txt Count the number of lines containing `patricia', ignoring case: $ ugrep -cwi patricia myfile.txt Count the number of words `patricia', ignoring case: $ ugrep -cowi patricia myfile.txt List lines with `amount' and a decimal, ignoring case (space is AND): $ ugrep -i -% 'amount \d+(\.\d+)?' myfile.txt The same Boolean search query, but with options -e and --and: $ ugrep -wi -e amount --and '\d+(\.\d+)?' myfile.txt List all Unicode words in a file: $ ugrep -o '\w+' myfile.txt List the laughing face emojis (Unicode code points U+1F600 to U+1F60F): $ ugrep -o '[\x{1F600}-\x{1F60F}]' myfile.txt Check if a file contains any non-ASCII (i.e. Unicode) characters: $ ugrep -q '[^[:ascii:]]' myfile.txt && echo "contains Unicode" Display the line and column number of `FIXME' in C++ files using recur- sive search, with one line of context before and after a matched line: $ ugrep -C1 -R -n -k -tc++ FIXME 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: $ ugrep -o -C20 -R -n -k -tjs FIXME 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: $ ugrep -n 'BEGIN.*\n(.*\n)*?.*END' myfile.txt Likewise, list the C/C++ comments in a file and line numbers: $ ugrep -n -e '//.*' -e '/\*(.*\n)*?.*\*+\/' myfile.cpp The same, but using predefined pattern c++/comments: $ ugrep -n -f c++/comments myfile.cpp 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: $ ugrep -e FIXME -N '"(\\.|\\\r?\n|[^\\\n"])*"' myfile.cpp The same, but using predefined pattern cpp/zap_strings: $ ugrep -e FIXME -f cpp/zap_strings myfile.cpp Find lines with `FIXME' or `TODO', showing line numbers: $ ugrep -n -e FIXME -e TODO myfile.cpp Find lines with `FIXME' that also contain `urgent': $ ugrep -n -e FIXME --and urgent myfile.cpp The same, but with a Boolean query pattern (a space is AND): $ ugrep -n -% 'FIXME urgent' myfile.cpp Find lines with `FIXME' that do not also contain `later': $ ugrep -n -e FIXME --andnot later myfile.cpp The same, but with a Boolean query pattern (a space is AND, - is NOT): $ ugrep -n -% 'FIXME -later' myfile.cpp Output a list of line numbers of lines with `FIXME' but not `later': $ ugrep -e FIXME --andnot later --format='%,%n' myfile.cpp Recursively list all files with both `FIXME' and `LICENSE' anywhere in the file, not necessarily on the same line: $ ugrep -l -%% 'FIXME LICENSE' Find lines with `FIXME' in the C/C++ files stored in a tarball: $ ugrep -z -tc++ -n FIXME project.tgz Recursively find lines with `FIXME' in C/C++ files, but do not search any `bak' and `old' directories: $ ugrep -n FIXME -tc++ -g^bak/,^old/ 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: $ ugrep -z -w --filter='pdf:pdftotext % -' copyright Match the binary pattern `A3hhhhA3' (hex) in a binary file without Uni- code pattern matching -U (which would otherwise match `\xaf' as a Uni- code character U+00A3 with UTF-8 byte sequence C2 A3) and display the results in hex with --hexdump with C1 to output one hex line before and after each match: $ ugrep -U --hexdump=C1 '\xa3[\x00-\xff]{2}\xa3' a.out Hexdump an entire file using a pager for viewing: $ ugrep -X --pager '' a.out List all files that are not ignored by one or more `.gitignore': $ ugrep -l '' --ignore-files List all files containing a RPM signature, located in the `rpm' direc- tory and recursively below up to two levels deeper (3 levels total): $ ugrep -3 -l -tRpm '' rpm/ Monitor the system log for bug reports and ungroup multiple matches from matching lines into separate lines: $ tail -f /var/log/system.log | ugrep -u -i -w bug Interactive fuzzy search with Boolean search queries: $ ugrep -Q -l -% -Z2 --sort=best Display all words in a MacRoman-encoded file that has CR newlines: $ ugrep --encoding=MACROMAN '\w+' mac.txt Display options related to "fuzzy" searching: $ ugrep --help fuzzy COPYRIGHT Copyright (c) 2021-2025 Robert A. van Engelen <engelen@acm.org> ugrep is released under the BSD-3 license. All parts of the software have reasonable copyright terms permitting free redistribution. This includes the ability to reuse all or parts of the ugrep source tree. SEE ALSO ugrep-indexer(1), grep(1), zgrep(1). BUGS Report bugs at: <https://github.com/Genivia/ugrep/issues> ugrep 7.5.0 June 18, 2025 UGREP(1)
NAME | SYNOPSIS | DESCRIPTION | EXIT STATUS | CONFIGURATION | GLOBBING | ENVIRONMENT | GREP_COLORS | FORMAT | EXAMPLES | COPYRIGHT | SEE ALSO | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ugrep&sektion=1&manpath=FreeBSD+15.0-RELEASE+and+Ports>