1UGREP(1) User Commands UGREP(1)
2
6 ugrep, ug -- file pattern searcher
7
9 ugrep [OPTIONS] [-i] [-Q|PATTERN] [-e PATTERN] [-N PATTERN] [-f FILE]
10 [-F|-G|-P|-Z] [-U] [-m [MIN,][MAX]] [--bool [--files|--lines]]
11 [-r|-R|-1|...|-9|--10|...] [-t TYPES] [-g GLOBS] [--sort[=KEY]]
12 [-l|-c] [-o] [-n] [-k] [-b] [-A NUM] [-B NUM] [-C NUM] [-y]
13 [--color[=WHEN]|--colour[=WHEN]] [--pretty] [--pager[=COMMAND]]
14 [--hexdump|--csv|--json|--xml] [-I] [-z] [--zmax=NUM] [FILE ...]
15
17 The ugrep utility searches any given input files, selecting lines that
18 match one or more patterns. By default, a pattern matches an input
19 line if the regular expression (RE) matches the input line. A pattern
20 matches multiple input lines if the RE in the pattern matches one or
21 more newlines in the input. An empty pattern matches every line. Each
22 input line that matches at least one of the patterns is written to the
23 standard output.
24 The ug command is intended for interactive searching, using a .ugrep
26 configuration file located in the working directory or home directory,
27 see CONFIGURATION. ug is equivalent to ugrep --config --pretty --sort
28 to load a .ugrep file, enhance the terminal output, and sort files by
29 name.
30 The ugrep+ and ug+ commands are the same as the ugrep and ug commands,
32 but also use filters to search pdfs, documents, e-books, and image
33 metadata, when the corresponding filter tools are installed.
34 A list of matching files is produced with option -l (--files-with-
36 matches). Option -c (--count) counts the number of matching lines.
37 Combine with option -o to count the total number of matches. Combine
38 with option -m1, (--min-count=1) to omit zero matches.
39 The default pattern syntax is an extended form of the POSIX ERE syntax,
41 same as option -E (--extended-regexp). Try ug --help regex for help
42 with pattern syntax and how to use logical connectives to specify Bool‐
43 ean search queries with option -% (--bool). Options -F (--fixed-
44 strings), -G (--basic-regexp) and -P (--perl-regexp) specify other pat‐
45 tern syntaxes.
46 Option -i (--ignore-case) ignores case in ASCII patterns. Combine with
48 option -P for case-insensitive Unicode matching. Option -j (--smart-
49 case) enables -i only if the search patterns are specified in lower
50 case.
51 Fuzzy (approximate) search is specified with option -Z (--fuzzy) with
53 an optional argument to control character insertions, deletions, and/or
54 substitutions. Try ug --help fuzzy for help with fuzzy search.
55 Note that pattern `.' matches any non-newline character. Pattern `\n'
57 matches a newline character. Multiple lines may be matched with pat‐
58 terns that match one or more newline characters.
59 Empty-matching patterns do not match all lines. For example, the pat‐
61 tern `a*' will match one or more a's. The single exception to this
62 rule is the empty pattern "", which matches all lines. Option -Y
63 forces empty matches for compatibility with other grep tools.
64 Option -f FILE matches patterns specified in FILE.
66 By default Unicode patterns are matched. Option -U (--binary) disables
68 Unicode matching for ASCII and binary pattern matching. Non-Unicode
69 matching is generally more efficient.
70 ugrep accepts input of various encoding formats and normalizes the out‐
72 put to UTF-8. When a UTF byte order mark is present in the input, the
73 input is automatically normalized. An input encoding format may be
74 specified with option --encoding.
75 If no FILE arguments are specified and standard input is read from a
77 terminal, recursive searches are performed as if -r is specified. To
78 force reading from standard input, specify `-' as a FILE argument.
79 Directories specified as FILE arguments are searched without recursing
81 deeper into subdirectories, unless -R, -r, or -2...-9 is specified to
82 search subdirectories recursively (up to the specified depth.)
83 Option -I (--ignore-binary) ignores binary files. A binary file is a
85 file with non-text content. A file with zero bytes or invalid UTF for‐
86 matting is considered binary.
87 Hidden files and directories are ignored in recursive searches. Option
89 -. (--hidden) includes hidden files and directories in recursive
90 searches.
91 To match the names of files to search and the names of directories to
93 recurse, one or more of the following options may be specified. Option
94 -O specifies one or more filename extensions to match. Option -t spec‐
95 ifies one or more file types to search (-t list outputs a list of
96 types.) Option -g specifies a gitignore-style glob pattern to match
97 filenames. Option --ignore-files specifies a file with gitignore-style
98 globs to ignore directories and files. Try ug --help globs for help
99 with filename and directory name matching. See also section GLOBBING.
100 Compressed files and archives are searched with option -z (--decom‐
102 press). When used with option --zmax=NUM, searches the contents of
103 compressed files and archives stored within archives up to NUM levels.
104 A query terminal user interface (TUI) is opened with -Q (--query) to
106 interactively specify search patterns and view search results. Note
107 that a PATTERN argument cannot be specified in this case. To specify
108 one or more patterns with -Q to start searching, use -e PATTERN.
109 Output to a terminal for viewing is enhanced with --pretty, which is
111 enabled by default with the ug command.
112 A terminal output pager is enabled with --pager.
114 Customized output is produced with option --format or --replace. Try
116 ug --help format for help with custom formatting of the output. Prede‐
117 fined formats include CSV with option --csv, JSON with option --json,
118 and XML with option --xml. Hexdumps are output with option -X (--hex)
119 or with option --hexdump to customize hexdumps. See also section FOR‐
120 MAT.
121 A `--' signals the end of options; the rest of the parameters are FILE
123 arguments, allowing filenames to begin with a `-' character.
124 Long options may start with `--no-' to disable, when applicable.
126 ug --help WHAT displays help on options related to WHAT.
128 The following options are available:
130 -A NUM, --after-context=NUM
132 Output NUM lines of trailing context after matching lines.
133 Places a --group-separator between contiguous groups of matches.
134 If -o is specified, output the match with context to fit NUM
135 columns after the match or shortens the match. See also options
136 -B, -C and -y.
137 -a, --text
139 Process a binary file as if it were text. This is equivalent to
140 the --binary-files=text option. This option might output binary
141 garbage to the terminal, which can have problematic consequences
142 if the terminal driver interprets some of it as commands.
143 --and [-e] PATTERN ... -e PATTERN
145 Specify additional patterns to match. Patterns must be speci‐
146 fied with -e. Each -e PATTERN following this option is consid‐
147 ered an alternative pattern to match, i.e. each -e is inter‐
148 preted as an OR pattern. For example, -e A -e B --and -e C -e D
149 matches lines with (`A' or `B') and (`C' or `D'). Note that
150 multiple -e PATTERN are alternations that bind more tightly to‐
151 gether than --and. Option --stats displays the search patterns
152 applied. See also options --not, --andnot, --bool, --files and
153 --lines.
154 --andnot [-e] PATTERN
156 Combines --and --not. See also options --and, --not and --bool.
157 -B NUM, --before-context=NUM
159 Output NUM lines of leading context before matching lines.
160 Places a --group-separator between contiguous groups of matches.
161 If -o is specified, output the match with context to fit NUM
162 columns before the match or shortens the match. See also op‐
163 tions -A, -C and -y.
164 -b, --byte-offset
166 The offset in bytes of a matched line is displayed in front of
167 the respective matched line. If -u is specified, displays the
168 offset for each pattern matched on the same line. Byte offsets
169 are exact for ASCII, UTF-8 and raw binary input. Otherwise, the
170 byte offset in the UTF-8 normalized input is displayed.
171 --binary-files=TYPE
173 Controls searching and reporting pattern matches in binary
174 files. TYPE can be `binary', `without-match`, `text`, `hex` and
175 `with-hex'. The default is `binary' to search binary files and
176 to report a match without displaying the match. `without-match'
177 ignores binary matches. `text' treats all binary files as text,
178 which might output binary garbage to the terminal, which can
179 have problematic consequences if the terminal driver interprets
180 some of it as commands. `hex' reports all matches in hexadeci‐
181 mal. `with-hex' only reports binary matches in hexadecimal,
182 leaving text matches alone. A match is considered binary when
183 matching a zero byte or invalid UTF. Short options are -a, -I,
184 -U, -W and -X.
185 --bool, -%
187 Specifies Boolean query patterns. A Boolean query pattern is
188 composed of `AND', `OR', `NOT' operators and grouping with `('
189 `)'. Spacing between subpatterns is the same as `AND', `|' is
190 the same as `OR' and a `-' is the same as `NOT'. The `OR' oper‐
191 ator binds more tightly than `AND'. For example, --bool 'A|B
192 C|D' matches lines with (`A' or `B') and (`C' or `D'), --bool 'A
193 -B' matches lines with `A' and not `B'. Operators `AND', `OR',
194 `NOT' require proper spacing. For example, --bool 'A OR B AND C
195 OR D' matches lines with (`A' or `B') and (`C' or `D'), --bool
196 'A AND NOT B' matches lines with `A' without `B'. Quoted sub‐
197 patterns are matched literally as strings. For example, --bool
198 'A "AND"|"OR"' matches lines with `A' and also either `AND' or
199 `OR'. Parenthesis are used for grouping. For example, --bool
200 '(A B)|C' matches lines with `A' and `B', or lines with `C'.
201 Note that all subpatterns in a Boolean query pattern are regular
202 expressions, unless -F is specified. Options -E, -F, -G, -P and
203 -Z can be combined with --bool to match subpatterns as strings
204 or regular expressions (-E is the default.) This option does
205 not apply to -f FILE patterns. Option --stats displays the
206 search patterns applied. See also options --and, --andnot,
207 --not, --files and --lines.
208 --break
210 Adds a line break between results from different files. This
211 option is enabled by --pretty when the output is sent to a ter‐
212 minal.
213 -C NUM, --context=NUM
215 Output NUM lines of leading and trailing context surrounding
216 each matching line. Places a --group-separator between contigu‐
217 ous groups of matches. If -o is specified, output the match
218 with context to fit NUM columns before and after the match or
219 shortens the match. See also options -A, -B and -y.
220 -c, --count
222 Only a count of selected lines is written to standard output.
223 If -o or -u is specified, counts the number of patterns matched.
224 If -v is specified, counts the number of non-matching lines. If
225 --tree is specified, outputs directories in a tree-like format.
226 --color[=WHEN], --colour[=WHEN]
228 Mark up the matching text with the expression stored in the
229 GREP_COLOR or GREP_COLORS environment variable. WHEN can be
230 `never', `always', or `auto', where `auto' marks up matches only
231 when output on a terminal. The default is `auto'.
232 --colors=COLORS, --colours=COLORS
234 Use COLORS to mark up text. COLORS is a colon-separated list of
235 one or more parameters `sl=' (selected line), `cx=' (context
236 line), `mt=' (matched text), `ms=' (match selected), `mc='
237 (match context), `fn=' (file name), `ln=' (line number), `cn='
238 (column number), `bn=' (byte offset), `se=' (separator). Param‐
239 eter values are ANSI SGR color codes or `k' (black), `r' (red),
240 `g' (green), `y' (yellow), `b' (blue), `m' (magenta), `c'
241 (cyan), `w' (white). Upper case specifies background colors. A
242 `+' qualifies a color as bright. A foreground and a background
243 color may be combined with font properties `n' (normal), `f'
244 (faint), `h' (highlight), `i' (invert), `u' (underline). Param‐
245 eter `hl' enables file name hyperlinks. Parameter `rv' reverses
246 the `sl=' and `cx=' parameters when option -v is specified. Se‐
247 lectively overrides GREP_COLORS.
248 --config[=FILE], ---[FILE]
250 Use configuration FILE. The default FILE is `.ugrep'. The
251 working directory is checked first for FILE, then the home di‐
252 rectory. The options specified in the configuration FILE are
253 parsed first, followed by the remaining options specified on the
254 command line.
255 --confirm
257 Confirm actions in -Q query mode. The default is confirm.
258 --cpp Output file matches in C++. See also options --format and -u.
260 --csv Output file matches in CSV. If -H, -n, -k, or -b is specified,
262 additional values are output. See also options --format and -u.
263 -D ACTION, --devices=ACTION
265 If an input file is a device, FIFO or socket, use ACTION to
266 process it. By default, ACTION is `skip', which means that de‐
267 vices are silently skipped. If ACTION is `read', devices read
268 just as if they were ordinary files.
269 -d ACTION, --directories=ACTION
271 If an input file is a directory, use ACTION to process it. By
272 default, ACTION is `skip', i.e., silently skip directories un‐
273 less specified on the command line. If ACTION is `read', warn
274 when directories are read as input. If ACTION is `recurse',
275 read all files under each directory, recursively, following sym‐
276 bolic links only if they are on the command line. This is
277 equivalent to the -r option. If ACTION is `dereference-re‐
278 curse', read all files under each directory, recursively, fol‐
279 lowing symbolic links. This is equivalent to the -R option.
280 --depth=[MIN,][MAX], -1, -2, -3, ... -9, --10, --11, --12, ...
282 Restrict recursive searches from MIN to MAX directory levels
283 deep, where -1 (--depth=1) searches the specified path without
284 recursing into subdirectories. Note that -3 -5, -3-5, and -35
285 search 3 to 5 levels deep. Enables -r if -R or -r is not speci‐
286 fied.
287 --dotall
289 Dot `.' in regular expressions matches anything, including new‐
290 line. Note that `.*' matches all input and should not be used.
291 -E, --extended-regexp
293 Interpret patterns as extended regular expressions (EREs). This
294 is the default.
295 -e PATTERN, --regexp=PATTERN
297 Specify a PATTERN used during the search of the input: an input
298 line is selected if it matches any of the specified patterns.
299 Note that longer patterns take precedence over shorter patterns.
300 This option is most useful when multiple -e options are used to
301 specify multiple patterns, when a pattern begins with a dash
302 (`-'), to specify a pattern after option -f or after the FILE
303 arguments.
304 --encoding=ENCODING
306 The encoding format of the input. The default ENCODING is bi‐
307 nary and UTF-8 which are the same. Note that option -U speci‐
308 fies binary PATTERN matching (text matching is the default.)
309 ENCODING can be: `binary', `ASCII', `UTF-8', `UTF-16',
310 `UTF-16BE', `UTF-16LE', `UTF-32', `UTF-32BE', `UTF-32LE',
311 `LATIN1', `ISO-8859-1', `ISO-8859-2', `ISO-8859-3',
312 `ISO-8859-4', `ISO-8859-5', `ISO-8859-6', `ISO-8859-7',
313 `ISO-8859-8', `ISO-8859-9', `ISO-8859-10', `ISO-8859-11',
314 `ISO-8859-13', `ISO-8859-14', `ISO-8859-15', `ISO-8859-16',
315 `MAC', `MACROMAN', `EBCDIC', `CP437', `CP850', `CP858',
316 `CP1250', `CP1251', `CP1252', `CP1253', `CP1254', `CP1255',
317 `CP1256', `CP1257', `CP1258', `KOI8-R', `KOI8-U', `KOI8-RU'.
318 --exclude=GLOB
320 Skip files whose name matches GLOB using wildcard matching, same
321 as -g ^GLOB. GLOB can use **, *, ?, and [...] as wildcards and
322 \ to quote a wildcard or backslash character literally. When
323 GLOB contains a `/', full pathnames are matched. Otherwise
324 basenames are matched. When GLOB ends with a `/', directories
325 are excluded as if --exclude-dir is specified. Otherwise files
326 are excluded. Note that --exclude patterns take priority over
327 --include patterns. GLOB should be quoted to prevent shell
328 globbing. This option may be repeated.
329 --exclude-dir=GLOB
331 Exclude directories whose name matches GLOB from recursive
332 searches, same as -g ^GLOB/. GLOB can use **, *, ?, and [...]
333 as wildcards and \ to quote a wildcard or backslash character
334 literally. When GLOB contains a `/', full pathnames are
335 matched. Otherwise basenames are matched. Note that --ex‐
336 clude-dir patterns take priority over --include-dir patterns.
337 GLOB should be quoted to prevent shell globbing. This option
338 may be repeated.
339 --exclude-from=FILE
341 Read the globs from FILE and skip files and directories whose
342 name matches one or more globs. A glob can use **, *, ?, and
343 [...] as wildcards and \ to quote a wildcard or backslash char‐
344 acter literally. When a glob contains a `/', full pathnames are
345 matched. Otherwise basenames are matched. When a glob ends
346 with a `/', directories are excluded as if --exclude-dir is
347 specified. Otherwise files are excluded. A glob starting with
348 a `!' overrides previously-specified exclusions by including
349 matching files. Lines starting with a `#' and empty lines in
350 FILE are ignored. When FILE is a `-', standard input is read.
351 This option may be repeated.
352 --exclude-fs=MOUNTS
354 Exclude file systems specified by MOUNTS from recursive
355 searches, MOUNTS is a comma-separated list of mount points or
356 pathnames of directories on file systems. Note that --ex‐
357 clude-fs mounts take priority over --include-fs mounts. This
358 option may be repeated.
359 -F, --fixed-strings
361 Interpret pattern as a set of fixed strings, separated by new‐
362 lines, any of which is to be matched. This makes ugrep behave
363 as fgrep. If a PATTERN is specified, or -e PATTERN or -N PAT‐
364 TERN, then this option has no effect on -f FILE patterns to al‐
365 low -f FILE patterns to narrow or widen the scope of the PATTERN
366 search.
367 -f FILE, --file=FILE
369 Read newline-separated patterns from FILE. White space in pat‐
370 terns is significant. Empty lines in FILE are ignored. If FILE
371 does not exist, the GREP_PATH environment variable is used as
372 path to FILE. If that fails, looks for FILE in /usr/lo‐
373 cal/share/ugrep/patterns. When FILE is a `-', standard input is
374 read. Empty files contain no patterns; thus nothing is matched.
375 This option may be repeated.
376 --filter=COMMANDS
378 Filter files through the specified COMMANDS first before search‐
379 ing. COMMANDS is a comma-separated list of `exts:command [op‐
380 tion ...]', where `exts' is a comma-separated list of filename
381 extensions and `command' is a filter utility. Files matching
382 one of `exts' are filtered. When `exts' is a `*', all files are
383 filtered. One or more `option' separated by spacing may be
384 specified, which are passed verbatim to the command. A `%' as
385 `option' expands into the pathname to search. For example,
386 --filter='pdf:pdftotext % -' searches PDF files. The `%' ex‐
387 pands into a `-' when searching standard input. When a `%' is
388 not specified, a filter utility should read from standard input
389 and write to standard output. Option --label=.ext may be used
390 to specify extension `ext' when searching standard input. This
391 option may be repeated.
392 --filter-magic-label=[+]LABEL:MAGIC
394 Associate LABEL with files whose signature "magic bytes" match
395 the MAGIC regex pattern. Only files that have no filename ex‐
396 tension are labeled, unless +LABEL is specified. When LABEL
397 matches an extension specified in --filter=COMMANDS, the corre‐
398 sponding command is invoked. This option may be repeated.
399 --format=FORMAT
401 Output FORMAT-formatted matches. For example --for‐
402 mat='%f:%n:%O%~' outputs matching lines `%O' with filename `%f`
403 and line number `%n' followed by a newline `%~'. If -P is spec‐
404 ified, FORMAT may include `%1' to `%9', `%[NUM]#' and `%[NAME]#'
405 to output group captures. A `%%' outputs `%'. See `ugrep
406 --help format' and `man ugrep' section FORMAT for details. When
407 option -o is specified, option -u is also enabled. Context op‐
408 tions -A, -B, -C and -y are ignored.
409 --free-space
411 Spacing (blanks and tabs) in regular expressions are ignored.
412 -G, --basic-regexp
414 Interpret patterns as basic regular expressions (BREs), i.e.
415 make ugrep behave as traditional grep.
416 -g GLOBS, --glob=GLOBS, --iglob=GLOBS
418 Search only files whose name matches the specified comma-sepa‐
419 rated list of GLOBS, same as --include='glob' for each `glob' in
420 GLOBS. When a `glob' is preceded by a `!' or a `^', skip files
421 whose name matches `glob', same as --exclude='glob'. When
422 `glob' contains a `/', full pathnames are matched. Otherwise
423 basenames are matched. When `glob' ends with a `/', directories
424 are matched, same as --include-dir='glob' and --ex‐
425 clude-dir='glob'. A leading `/' matches the working directory.
426 Option --iglob performs case-insensitive name matching. This
427 option may be repeated and may be combined with options -M, -O
428 and -t to expand searches. See `ugrep --help globs' and `man
429 ugrep' section GLOBBING for details.
430 --glob-ignore-case
432 Perform case-insensitive glob matching in general.
433 --group-separator[=SEP]
435 Use SEP as a group separator for context options -A, -B and -C.
436 The default is a double hyphen (`--').
437 -H, --with-filename
439 Always print the filename with output lines. This is the de‐
440 fault when there is more than one file to search.
441 -h, --no-filename
443 Never print filenames with output lines. This is the default
444 when there is only one file (or only standard input) to search.
445 --heading, -+
447 Group matches per file. Adds a heading and a line break between
448 results from different files. This option is enabled by
449 --pretty when the output is sent to a terminal.
450 --help [WHAT], -? [WHAT]
452 Display a help message on options related to WHAT when speci‐
453 fied. In addition, `--help regex' displays an overview of regu‐
454 lar expressions, `--help globs' displays an overview of glob
455 syntax and conventions. `--help fuzzy' displays details of
456 fuzzy search with option -Z and `--help format' displays a list
457 of --format fields.
458 --hexdump[=[1-8][a][bch][A[NUM]][B[NUM]][C[NUM]]]
460 Output matches in 1 to 8 columns of 8 hexadecimal octets. The
461 default is 2 columns or 16 octets per line. Option `a' outputs
462 a `*' for all hex lines that are identical to the previous hex
463 line, `b' removes all space breaks, `c' removes the character
464 column, `h' removes hex spacing, `A' includes up to NUM hex
465 lines after the match, `B' includes up to NUM hex lines before
466 the match and `C' includes up to NUM hex lines. When NUM is
467 omitted, the matching line is included in the output. See also
468 options -U, -W and -X.
469 --hidden, -.
471 Search hidden files and directories.
472 --hyperlink[=[PREFIX][+]]
474 Hyperlinks are enabled for file names when colors are enabled.
475 Same as --colors=hl. When PREFIX is specified, replaces file://
476 with PREFIX:// in the hyperlink. A `+' includes the line number
477 in the hyperlink and when option -k is specified, the column
478 number.
479 -I, --ignore-binary
481 Ignore matches in binary files. This option is equivalent to
482 the --binary-files=without-match option.
483 -i, --ignore-case
485 Perform case insensitive matching. By default, ugrep is case
486 sensitive. By default, this option applies to ASCII letters
487 only. Use options -P and -i for Unicode case insensitive match‐
488 ing.
489 --ignore-files[=FILE]
491 Ignore files and directories matching the globs in each FILE
492 that is encountered in recursive searches. The default FILE is
493 `.gitignore'. Matching files and directories located in the di‐
494 rectory of a FILE's location and in directories below are ig‐
495 nored by temporarily extending the --exclude and --exclude-dir
496 globs, as if --exclude-from=FILE is locally enforced. Globbing
497 syntax is the same as the --exclude-from=FILE gitignore syntax;
498 directories are excluded when the glob ends in a `/', same as
499 git. Files and directories explicitly specified as command line
500 arguments are never ignored. This option may be repeated with
501 additional files.
502 --include=GLOB
504 Search only files whose name matches GLOB using wildcard match‐
505 ing, same as -g GLOB. GLOB can use **, *, ?, and [...] as wild‐
506 cards and \ to quote a wildcard or backslash character liter‐
507 ally. When GLOB contains a `/', full pathnames are matched.
508 Otherwise basenames are matched. When GLOB ends with a `/', di‐
509 rectories are included as if --include-dir is specified. Other‐
510 wise files are included. Note that --exclude patterns take pri‐
511 ority over --include patterns. GLOB should be quoted to prevent
512 shell globbing. This option may be repeated.
513 --include-dir=GLOB
515 Only directories whose name matches GLOB are included in recur‐
516 sive searches, same as -g GLOB/. GLOB can use **, *, ?, and
517 [...] as wildcards and \ to quote a wildcard or backslash char‐
518 acter literally. When GLOB contains a `/', full pathnames are
519 matched. Otherwise basenames are matched. Note that --ex‐
520 clude-dir patterns take priority over --include-dir patterns.
521 GLOB should be quoted to prevent shell globbing. This option
522 may be repeated.
523 --include-from=FILE
525 Read the globs from FILE and search only files and directories
526 whose name matches one or more globs. A glob can use **, *, ?,
527 and [...] as wildcards and \ to quote a wildcard or backslash
528 character literally. When a glob contains a `/', full pathnames
529 are matched. Otherwise basenames are matched. When a glob ends
530 with a `/', directories are included as if --include-dir is
531 specified. Otherwise files are included. A glob starting with
532 a `!' overrides previously-specified inclusions by excluding
533 matching files. Lines starting with a `#' and empty lines in
534 FILE are ignored. When FILE is a `-', standard input is read.
535 This option may be repeated.
536 --include-fs=MOUNTS
538 Only file systems specified by MOUNTS are included in recursive
539 searches. MOUNTS is a comma-separated list of mount points or
540 pathnames of directories on file systems. --include-fs=. re‐
541 stricts recursive searches to the file system of the working di‐
542 rectory only. Note that --exclude-fs mounts take priority over
543 --include-fs mounts. This option may be repeated.
544 --index
546 Perform indexing-based search on files indexed with ugrep-in‐
547 dexer. Recursive searches are performed by skipping non-match‐
548 ing files. Binary files are skipped with option -I. Note that
549 the start-up time to search is increased, which may be signifi‐
550 cant when complex search patterns are specified that contain
551 large Unicode character classes with `*' or `+' repeats, which
552 should be avoided. Option -U (--ascii) improves performance.
553 Option --stats=vm displays a detailed indexing-based search re‐
554 port. This is a beta feature.
555 -J NUM, --jobs=NUM
557 Specifies the number of threads spawned to search files. By de‐
558 fault an optimum number of threads is spawned to search files
559 simultaneously. -J1 disables threading: files are searched in
560 the same order as specified.
561 -j, --smart-case
563 Perform case insensitive matching like option -i, unless a pat‐
564 tern is specified with a literal ASCII upper case letter.
565 --json Output file matches in JSON. If -H, -n, -k, or -b is specified,
567 additional values are output. See also options --format and -u.
568 -K [MIN,][MAX], --range=[MIN,][MAX], --min-line=MIN, --max-line=MAX
570 Start searching at line MIN, stop at line MAX when specified.
571 -k, --column-number
573 The column number of a matched pattern is displayed in front of
574 the respective matched line, starting at column 1. Tabs are ex‐
575 panded when columns are counted, see also option --tabs.
576 -L, --files-without-match
578 Only the names of files not containing selected lines are writ‐
579 ten to standard output. Pathnames are listed once per file
580 searched. If the standard input is searched, the string
581 ``(standard input)'' is written. If --tree is specified, out‐
582 puts directories in a tree-like format.
583 -l, --files-with-matches
585 Only the names of files containing selected lines are written to
586 standard output. ugrep will only search a file until a match
587 has been found, making searches potentially less expensive.
588 Pathnames are listed once per file searched. If the standard
589 input is searched, the string ``(standard input)'' is written.
590 If --tree is specified, outputs directories in a tree-like for‐
591 mat.
592 --label=LABEL
594 Displays the LABEL value when input is read from standard input
595 where a file name would normally be printed in the output. As‐
596 sociates a filename extension with standard input when LABEL has
597 a suffix. The default value is `(standard input)'.
598 --line-buffered
600 Force output to be line buffered instead of block buffered.
601 --lines
603 Apply Boolean queries to match lines, the opposite of --files.
604 This is the default Boolean query mode to match specific lines.
605 -M MAGIC, --file-magic=MAGIC
607 Only files matching the signature pattern MAGIC are searched.
608 The signature "magic bytes" at the start of a file are compared
609 to the MAGIC regex pattern. When matching, the file will be
610 searched. When MAGIC is preceded by a `!' or a `^', skip files
611 with matching MAGIC signatures. This option may be repeated and
612 may be combined with options -O and -t to expand the search.
613 Every file on the search path is read, making searches poten‐
614 tially more expensive.
615 -m [MIN,][MAX], --min-count=MIN, --max-count=MAX
617 Require MIN matches, stop after MAX matches when specified.
618 Output MIN to MAX matches. For example, -m1 outputs the first
619 match and -cm1, (with a comma) counts non-zero matches. See
620 also option -K.
621 --match
623 Match all input. Same as specifying an empty pattern to search.
624 --max-files=NUM
626 Restrict the number of files matched to NUM. Note that --sort
627 or -J1 may be specified to produce replicable results. If
628 --sort is specified, the number of threads spawned is limited to
629 NUM.
630 --mmap[=MAX]
632 Use memory maps to search files. By default, memory maps are
633 used under certain conditions to improve performance. When MAX
634 is specified, use up to MAX mmap memory per thread.
635 -N PATTERN, --neg-regexp=PATTERN
637 Specify a negative PATTERN used during the search of the input:
638 an input line is selected only if it matches the specified pat‐
639 terns unless it matches the negative PATTERN. Same as -e
640 (?^PATTERN). Negative pattern matches are essentially removed
641 before any other patterns are matched. Note that longer pat‐
642 terns take precedence over shorter patterns. This option may be
643 repeated.
644 -n, --line-number
646 Each output line is preceded by its relative line number in the
647 file, starting at line 1. The line number counter is reset for
648 each file processed.
649 --no-group-separator
651 Removes the group separator line from the output for context op‐
652 tions -A, -B and -C.
653 --not [-e] PATTERN
655 Specifies that PATTERN should not match. Note that -e A --not
656 -e B matches lines with `A' or lines without a `B'. To match
657 lines with `A' that have no `B', specify -e A --andnot -e B.
658 Option --stats displays the search patterns applied. See also
659 options --and, --andnot, --bool, --files and --lines.
660 -O EXTENSIONS, --file-extension=EXTENSIONS
662 Search only files whose filename extensions match the specified
663 comma-separated list of EXTENSIONS, same as --include='*.ext'
664 for each `ext' in EXTENSIONS. When an `ext' is preceded by a
665 `!' or a `^', skip files whose filename extensions matches
666 `ext', same as --exclude='*.ext'. This option may be repeated
667 and may be combined with options -g, -M and -t to expand the re‐
668 cursive search.
669 -o, --only-matching
671 Output only the matching part of lines. Output additional
672 matches on the same line with `+' as the field separator. When
673 multiple lines match a pattern, output the matching lines with
674 `|' as the field separator. If -A, -B or -C is specified, fits
675 the match and its context on a line within the specified number
676 of columns.
677 --only-line-number
679 The line number of the matching line in the file is output with‐
680 out displaying the match. The line number counter is reset for
681 each file processed.
682 --files
684 Apply Boolean queries to match files, the opposite of --lines.
685 A file matches if all Boolean conditions are satisfied by the
686 lines matched in the file. For example, --files -e A --and -e B
687 -e C --andnot -e D matches a file if some lines match `A' and
688 some lines match (`B' or `C') and no line in the file matches
689 `D'. May also be specified as --files --bool 'A B|C -D'. Op‐
690 tion -v cannot be specified with --files. See also options
691 --and, --andnot, --not, --bool and --lines.
692 -P, --perl-regexp
694 Interpret PATTERN as a Perl regular expression using PCRE2.
695 Note that Perl pattern matching differs from the default grep
696 POSIX pattern matching.
697 -p, --no-dereference
699 If -R or -r is specified, do not follow symbolic links, even
700 when symbolic links are specified on the command line.
701 --pager[=COMMAND]
703 When output is sent to the terminal, uses COMMAND to page
704 through the output. The default COMMAND is `less -R'. Enables
705 --heading and --line-buffered.
706 --pretty
708 When output is sent to a terminal, enables --color, --heading,
709 -n, --sort, --tree and -T when not explicitly disabled.
710 -Q[DELAY], --query[=DELAY]
712 Query mode: user interface to perform interactive searches.
713 This mode requires an ANSI capable terminal. An optional DELAY
714 argument may be specified to reduce or increase the response
715 time to execute searches after the last key press, in increments
716 of 100ms, where the default is 5 (0.5s delay). No whitespace
717 may be given between -Q and its argument DELAY. Initial pat‐
718 terns may be specified with -e PATTERN, i.e. a PATTERN argument
719 requires option -e. Press F1 or CTRL-Z to view the help screen.
720 Press F2 or CTRL-Y to invoke a command to view or edit the file
721 shown at the top of the screen. The command can be specified
722 with option --view, or defaults to environment variable PAGER if
723 defined, or EDITOR. Press Tab and Shift-Tab to navigate direc‐
724 tories and to select a file to search. Press Enter to select
725 lines to output. Press ALT-l for option -l to list files, ALT-n
726 for -n, etc. Non-option commands include ALT-] to increase
727 fuzziness and ALT-} to increase context. Enables --heading.
728 See also options --confirm and --view.
729 -q, --quiet, --silent
731 Quiet mode: suppress all output. Only search a file until a
732 match has been found.
733 -R, --dereference-recursive
735 Recursively read all files under each directory. Follow sym‐
736 bolic links to files and directories, unlike -r.
737 -r, --recursive
739 Recursively read all files under each directory, following sym‐
740 bolic links only if they are on the command line. Note that
741 when no FILE arguments are specified and input is read from a
742 terminal, recursive searches are performed as if -r is speci‐
743 fied.
744 --replace=FORMAT
746 Replace matching patterns in the output by the specified FORMAT
747 with `%' fields. If -P is specified, FORMAT may include `%1' to
748 `%9', `%[NUM]#' and `%[NAME]#' to output group captures. A `%%'
749 outputs `%' and `%~' outputs a newline. See option --format,
750 `ugrep --help format' and `man ugrep' section FORMAT for de‐
751 tails.
752 -S, --dereference-files
754 When -r is specified, follow symbolic links to files, but not to
755 directories. The default is not to follow symbolic links.
756 -s, --no-messages
758 Silent mode: nonexistent and unreadable files are ignored, i.e.
759 their error messages and warnings are suppressed.
760 --save-config[=FILE]
762 Save configuration FILE. By default `.ugrep' is saved. If FILE
763 is a `-', write the configuration to standard output.
764 --separator[=SEP]
766 Use SEP as field separator between file name, line number, col‐
767 umn number, byte offset and the matched line. The default is a
768 colon (`:'), a plus (`+') for additional matches on the same
769 line, and a bar (`|') for multi-line pattern matches.
770 --sort[=KEY]
772 Displays matching files in the order specified by KEY in recur‐
773 sive searches. Normally the ug command sorts by name whereas
774 the ugrep batch command displays matches in no particular order
775 to improve performance. The sort KEY can be `name' to sort by
776 pathname (default), `best' to sort by best match with option -Z
777 (sort by best match requires two passes over files, which is ex‐
778 pensive), `size' to sort by file size, `used' to sort by last
779 access time, `changed' to sort by last modification time and
780 `created' to sort by creation time. Sorting is reversed with
781 `rname', `rbest', `rsize', `rused', `rchanged', or `rcreated'.
782 Archive contents are not sorted. Subdirectories are sorted and
783 displayed after matching files. FILE arguments are searched in
784 the same order as specified.
785 --stats
787 Output statistics on the number of files and directories
788 searched and the inclusion and exclusion constraints applied.
789 -T, --initial-tab
791 Add a tab space to separate the file name, line number, column
792 number and byte offset with the matched line.
793 -t TYPES, --file-type=TYPES
795 Search only files associated with TYPES, a comma-separated list
796 of file types. Each file type corresponds to a set of filename
797 extensions passed to option -O and filenames passed to option
798 -g. For capitalized file types, the search is expanded to in‐
799 clude files with matching file signature magic bytes, as if
800 passed to option -M. When a type is preceded by a `!' or a `^',
801 excludes files of the specified type. This option may be re‐
802 peated. The possible file types can be (where -tlist displays a
803 detailed list): `actionscript', `ada', `asm', `asp', `aspx',
804 `autoconf', `automake', `awk', `Awk', `basic', `batch', `bison',
805 `c', `c++', `clojure', `cpp', `csharp', `css', `csv', `dart',
806 `Dart', `delphi', `elisp', `elixir', `erlang', `fortran', `gif',
807 `Gif', `go', `groovy', `gsp', `haskell', `html', `jade', `java',
808 `jpeg', `Jpeg', `js', `json', `jsp', `julia', `kotlin', `less',
809 `lex', `lisp', `lua', `m4', `make', `markdown', `matlab',
810 `node', `Node', `objc', `objc++', `ocaml', `parrot', `pascal',
811 `pdf', `Pdf', `perl', `Perl', `php', `Php', `png', `Png', `pro‐
812 log', `python', `Python', `r', `rpm', `Rpm', `rst', `rtf',
813 `Rtf', `ruby', `Ruby', `rust', `scala', `scheme', `shell',
814 `Shell', `smalltalk', `sql', `svg', `swift', `tcl', `tex',
815 `text', `tiff', `Tiff', `tt', `typescript', `verilog', `vhdl',
816 `vim', `xml', `Xml', `yacc', `yaml'.
817 --tabs[=NUM]
819 Set the tab size to NUM to expand tabs for option -k. The value
820 of NUM may be 1, 2, 4, or 8. The default tab size is 8.
821 --tag[=TAG[,END]]
823 Disables colors to mark up matches with TAG. END marks the end
824 of a match if specified, otherwise TAG. The default is `___'.
825 --tree, -^
827 Output directories with matching files in a tree-like format
828 when options -c, -l or -L are used. This option is enabled by
829 --pretty when the output is sent to a terminal.
830 -U, --ascii, --binary
832 Disables Unicode matching for ASCII and binary matching. PAT‐
833 TERN matches bytes, not Unicode characters. For example, -U
834 '\xa3' matches byte A3 (hex) instead of the Unicode code point
835 U+00A3 represented by the UTF-8 sequence C2 A3. See also option
836 --dotall.
837 -u, --ungroup
839 Do not group multiple pattern matches on the same matched line.
840 Output the matched line again for each additional pattern match,
841 using `+' as a separator.
842 -V, --version
844 Display version with linked libraries and exit.
845 -v, --invert-match
847 Selected lines are those not matching any of the specified pat‐
848 terns.
849 --view[=COMMAND]
851 Use COMMAND to view/edit a file in query mode when pressing
852 CTRL-Y.
853 -W, --with-hex
855 Output binary matches in hexadecimal, leaving text matches
856 alone. This option is equivalent to the --binary-files=with-hex
857 option with --hexdump=2C. To omit the matching line from the
858 hex output, combine option --hexdump with option -W. See also
859 option -U.
860 -w, --word-regexp
862 The PATTERN is searched for as a word, such that the matching
863 text is preceded by a non-word character and is followed by a
864 non-word character. Word characters are letters, digits and the
865 underscore. With option -P, word characters are Unicode let‐
866 ters, digits and underscore. This option has no effect if -x is
867 also specified. If a PATTERN is specified, or -e PATTERN or -N
868 PATTERN, then this option has no effect on -f FILE patterns to
869 allow -f FILE patterns to narrow or widen the scope of the PAT‐
870 TERN search.
871 --width[=NUM]
873 Truncate the output to NUM visible characters per line. The
874 width of the terminal window is used if NUM is not specified.
875 Note that double wide characters in the output may result in
876 wider lines.
877 -X, --hex
879 Output matches in hexadecimal. This option is equivalent to the
880 --binary-files=hex option with --hexdump=2C. To omit the match‐
881 ing line from the hex output, use option --hexdump instead of
882 -X. See also option -U.
883 -x, --line-regexp
885 Select only those matches that exactly match the whole line, as
886 if the patterns are surrounded by ^ and $. If a PATTERN is
887 specified, or -e PATTERN or -N PATTERN, then this option has no
888 effect on -f FILE patterns to allow -f FILE patterns to narrow
889 or widen the scope of the PATTERN search.
890 --xml Output file matches in XML. If -H, -n, -k, or -b is specified,
892 additional values are output. See also options --format and -u.
893 -Y, --empty
895 Permits empty matches. By default, empty matches are disabled,
896 unless a pattern begins with `^' or ends with `$'. With this
897 option, empty-matching patterns such as x? and x*, match all in‐
898 put, not only lines containing the character `x'.
899 -y, --any-line, --passthru
901 Any line is output (passthru). Non-matching lines are output as
902 context with a `-' separator. See also options -A, -B and -C.
903 -Z[best][+-~][MAX], --fuzzy=[best][+-~][MAX]
905 Fuzzy mode: report approximate pattern matches within MAX er‐
906 rors. The default is -Z1: one deletion, insertion or substitu‐
907 tion is allowed. If `+`, `-' and/or `~' is specified, then `+'
908 allows insertions, `-' allows deletions and `~' allows substitu‐
909 tions. For example, -Z+~3 allows up to three insertions or sub‐
910 stitutions, but no deletions. If `best' is specified, then only
911 the best matching lines are output with the lowest cost per
912 file. Option -Zbest requires two passes over a file and cannot
913 be used with standard input or Boolean queries. Option
914 --sort=best orders matching files by best match. The first
915 character of an approximate match always matches a character at
916 the beginning of the pattern. To fuzzy match the first charac‐
917 ter, replace it with a `.' or `.?'. Option -U applies fuzzy
918 matching to ASCII and bytes instead of Unicode text. No white‐
919 space may be given between -Z and its argument.
920 -z, --decompress
922 Decompress files to search, when compressed. Archives (.cpio,
923 .pax, .tar) and compressed archives (e.g. .zip, .taz, .tgz,
924 .tpz, .tbz, .tbz2, .tb2, .tz2, .tlz, .txz, .tzst) are searched
925 and matching pathnames of files in archives are output in
926 braces. When used with option --zmax=NUM, searches the contents
927 of compressed files and archives stored within archives up to
928 NUM levels. If -g, -O, -M, or -t is specified, searches files
929 stored in archives whose filenames match globs, match filename
930 extensions, match file signature magic bytes, or match file
931 types, respectively. Supported compression formats: gzip (.gz),
932 compress (.Z), zip, bzip2 (requires suffix .bz, .bz2, .bzip2,
933 .tbz, .tbz2, .tb2, .tz2), lzma and xz (requires suffix .lzma,
934 .tlz, .xz, .txz), lz4 (requires suffix .lz4), zstd (requires
935 suffix .zst, .zstd, .tzst).
936 --zmax=NUM
938 When used with option -z (--decompress), searches the contents
939 of compressed files and archives stored within archives by up to
940 NUM expansion levels deep. The default --zmax=1 only permits
941 searching uncompressed files stored in cpio, pax, tar and zip
942 archives; compressed files and archives are detected as binary
943 files and are effectively ignored. Specify --zmax=2 to search
944 compressed files and archives stored in cpio, pax, tar and zip
945 archives. NUM may range from 1 to 99 for up to 99 decompression
946 and de-archiving steps. Increasing NUM values gradually de‐
947 grades performance.
948 -0, --null
950 Output a zero-byte (NUL) after the file name. This option can
951 be used with commands such as `find -print0' and `xargs -0' to
952 process arbitrary file names.
953
955 The ugrep utility exits with one of the following values:
956 0 One or more lines were selected.
958 1 No lines were selected.
960 >1 An error occurred.
962 If -q or --quiet or --silent is used and a line is selected, the exit
964 status is 0 even if an error occurred.
965
967 The ug command is intended for context-dependent interactive searching
968 and is equivalent to the ugrep --config --pretty --sort command to load
969 the default configuration file `.ugrep' when present in the working di‐
970 rectory or in the home directory.
971 A configuration file contains `NAME=VALUE' pairs per line, where `NAME`
973 is the name of a long option (without `--') and `=VALUE' is an argu‐
974 ment, which is optional and may be omitted depending on the option.
975 Empty lines and lines starting with a `#' are ignored.
976 The --config=FILE option and its abbreviated form ---FILE load the
978 specified configuration file located in the working directory or, when
979 not found, located in the home directory. An error is produced when
980 FILE is not found or cannot be read.
981 Command line options are parsed in the following order: the configura‐
983 tion file is loaded first, followed by the remaining options and argu‐
984 ments on the command line.
985 The --save-config option saves a `.ugrep' configuration file to the
987 working directory with a subset of the current options. The --save-
988 config=FILE option saves the configuration to FILE. The configuration
989 is written to standard output when FILE is a `-'.
990
992 Globbing is used by options -g, --include, --include-dir, --include-
993 from, --exclude, --exclude-dir, --exclude-from and --ignore-files to
994 match pathnames and basenames in recursive searches. Glob arguments
995 for these options should be quoted to prevent shell globbing.
996 Globbing supports gitignore syntax and the corresponding matching
998 rules, except that a glob normally matches files but not directories.
999 If a glob ends in a path separator `/', then it matches directories but
1000 not files, as if --include-dir or --exclude-dir is specified. When a
1001 glob contains a path separator `/', the full pathname is matched. Oth‐
1002 erwise the basename of a file or directory is matched. For example,
1003 *.h matches foo.h and bar/foo.h. bar/*.h matches bar/foo.h but not
1004 foo.h and not bar/bar/foo.h. Use a leading `/' to force /*.h to match
1005 foo.h but not bar/foo.h.
1006 When a glob starts with a `^' or a `!' as in -g^GLOB, the match is
1008 negated. Likewise, a `!' (but not a `^') may be used with globs in the
1009 files specified --include-from, --exclude-from, and --ignore-files to
1010 negate the glob match. Empty lines or lines starting with a `#' are
1011 ignored.
1012 Glob Syntax and Conventions
1014 * Matches anything except /.
1016 ? Matches any one character except /.
1018 [abc-e]
1020 Matches one character a,b,c,d,e.
1021 [^abc-e]
1023 Matches one character not a,b,c,d,e,/.
1024 [!abc-e]
1026 Matches one character not a,b,c,d,e,/.
1027 / When used at the start of a glob, matches if pathname has no /.
1029 When used at the end of a glob, matches directories only.
1030 **/ Matches zero or more directories.
1032 /** When used at the end of a glob, matches everything after the /.
1034 \? Matches a ? or any other character specified after the back‐
1036 slash.
1037 Glob Matching Examples
1039 * Matches a, b, x/a, x/y/b
1041 a Matches a, x/a, x/y/a, but not b, x/b, a/a/b
1043 /* Matches a, b, but not x/a, x/b, x/y/a
1045 /a Matches a, but not x/a, x/y/a
1047 a?b Matches axb, ayb, but not a, b, ab, a/b
1049 a[xy]b Matches axb, ayb but not a, b, azb
1051 a[a-z]b
1053 Matches aab, abb, acb, azb, but not a, b, a3b, aAb, aZb
1054 a[^xy]b
1056 Matches aab, abb, acb, azb, but not a, b, axb, ayb
1057 a[^a-z]b
1059 Matches a3b, aAb, aZb but not a, b, aab, abb, acb, azb
1060 a/*/b Matches a/x/b, a/y/b, but not a/b, a/x/y/b
1062 **/a Matches a, x/a, x/y/a, but not b, x/b.
1064 a/**/b Matches a/b, a/x/b, a/x/y/b, but not x/a/b, a/b/x
1066 a/** Matches a/x, a/y, a/x/y, but not a, b/x
1068 a\?b Matches a?b, but not a, b, ab, axb, a/b
1070 Note that exclude glob patterns take priority over include glob pat‐
1072 terns when specified with options -g, --exclude, --exclude-dir, --in‐
1073 clude and include-dir.
1074 Glob patterns specified with prefix `!' in any of the files associated
1076 with --include-from, --exclude-from and --ignore-files will negate a
1077 previous glob match. That is, any matching file or directory excluded
1078 by a previous glob pattern specified in the files associated with --ex‐
1079 clude-from or --ignore-file will become included again. Likewise, any
1080 matching file or directory included by a previous glob pattern speci‐
1081 fied in the files associated with --include-from will become excluded
1082 again.
1083
1085 GREP_PATH
1086 May be used to specify a file path to pattern files. The file
1087 path is used by option -f to open a pattern file, when the pat‐
1088 tern file does not exist.
1089 GREP_COLOR
1091 May be used to specify ANSI SGR parameters to highlight matches
1092 when option --color is used, e.g. 1;35;40 shows pattern matches
1093 in bold magenta text on a black background. Deprecated in favor
1094 of GREP_COLORS, but still supported.
1095 GREP_COLORS
1097 May be used to specify ANSI SGR parameters to highlight matches
1098 and other attributes when option --color is used. Its value is
1099 a colon-separated list of ANSI SGR parameters that defaults to
1100 cx=33:mt=1;31:fn=1;35:ln=1;32:cn=1;32:bn=1;32:se=36. The mt=,
1101 ms=, and mc= capabilities of GREP_COLORS take priority over
1102 GREP_COLOR. Option --colors takes priority over GREP_COLORS.
1103
1105 Colors are specified as string of colon-separated ANSI SGR parameters
1106 of the form `what=substring', where `substring' is a semicolon-sepa‐
1107 rated list of ANSI SGR codes or `k' (black), `r' (red), `g' (green),
1108 `y' (yellow), `b' (blue), `m' (magenta), `c' (cyan), `w' (white). Up‐
1109 per case specifies background colors. A `+' qualifies a color as
1110 bright. A foreground and a background color may be combined with one
1111 or more font properties `n' (normal), `f' (faint), `h' (highlight), `i'
1112 (invert), `u' (underline). Substrings may be specified for:
1113 sl= SGR substring for selected lines.
1115 cx= SGR substring for context lines.
1117 rv Swaps the sl= and cx= capabilities when -v is specified.
1119 mt= SGR substring for matching text in any matching line.
1121 ms= SGR substring for matching text in a selected line. The sub‐
1123 string mt= by default.
1124 mc= SGR substring for matching text in a context line. The sub‐
1126 string mt= by default.
1127 fn= SGR substring for filenames.
1129 ln= SGR substring for line numbers.
1131 cn= SGR substring for column numbers.
1133 bn= SGR substring for byte offsets.
1135 se= SGR substring for separators.
1137 rv a Boolean parameter, switches sl= and cx= with option -v.
1139 hl a Boolean parameter, enables filename hyperlinks (\33]8;;link).
1141 ne a Boolean parameter, disables ``erase in line'' \33[K.
1143
1145 Option --format=FORMAT specifies an output format for file matches.
1146 Fields may be used in FORMAT, which expand into the following values:
1147 %[ARG]F
1149 if option -H is used: ARG, the file pathname and separator.
1150 %f the file pathname.
1152 %a the file basename without directory path.
1154 %p the directory path to the file.
1156 %z the file pathname in a (compressed) archive.
1158 %[ARG]H
1160 if option -H is used: ARG, the quoted pathname and separator, \"
1161 and \\ replace " and \.
1162 %h the quoted file pathname, \" and \\ replace " and \.
1164 %[ARG]N
1166 if option -n is used: ARG, the line number and separator.
1167 %n the line number of the match.
1169 %[ARG]K
1171 if option -k is used: ARG, the column number and separator.
1172 %k the column number of the match.
1174 %[ARG]B
1176 if option -b is used: ARG, the byte offset and separator.
1177 %b the byte offset of the match.
1179 %[ARG]T
1181 if option -T is used: ARG and a tab character.
1182 %t a tab character.
1184 %[SEP]$
1186 set field separator to SEP for the rest of the format fields.
1187 %[ARG]<
1189 if the first match: ARG.
1190 %[ARG]>
1192 if not the first match: ARG.
1193 %, if not the first match: a comma, same as %[,]>.
1195 %: if not the first match: a colon, same as %[:]>.
1197 %; if not the first match: a semicolon, same as %[;]>.
1199 %| if not the first match: a vertical bar, same as %[|]>.
1201 %[ARG]S
1203 if not the first match: ARG and separator, see also %[SEP]$.
1204 %s the separator, see also %[ARG]S and %[SEP]$.
1206 %~ a newline character.
1208 %M the number of matching lines
1210 %m the number of matches
1212 %O the matching line is output as a raw string of bytes.
1214 %o the match is output as a raw string of bytes.
1216 %Q the matching line as a quoted string, \" and \\ replace " and \.
1218 %q the match as a quoted string, \" and \\ replace " and \.
1220 %C the matching line formatted as a quoted C/C++ string.
1222 %c the match formatted as a quoted C/C++ string.
1224 %J the matching line formatted as a quoted JSON string.
1226 %j the match formatted as a quoted JSON string.
1228 %V the matching line formatted as a quoted CSV string.
1230 %v the match formatted as a quoted CSV string.
1232 %X the matching line formatted as XML character data.
1234 %x the match formatted as XML character data.
1236 %w the width of the match, counting wide characters.
1238 %d the size of the match, counting bytes.
1240 %e the ending byte offset of the match.
1242 %Z the edit distance cost of an approximate match with option -Z
1244 %u select unique lines only, unless option -u is used.
1246 %1 the first regex group capture of the match, and so on up to
1248 group %9, same as %[1]#; requires option -P.
1249 %[NUM]#
1251 the regex group capture NUM; requires option -P.
1252 %[NUM]b
1254 the byte offset of the group capture NUM; requires option -P.
1255 Use e for the ending byte offset and d for the byte length.
1256 %[NUM1|NUM2|...]#
1258 the first group capture NUM that matched; requires option -P.
1259 %[NUM1|NUM2|...]b
1261 the byte offset of the first group capture NUM that matched; re‐
1262 quires option -P. Use e for the ending byte offset and d for
1263 the byte length.
1264 %[NAME]#
1266 the NAMEd group capture; requires option -P and capturing pat‐
1267 tern `(?<NAME>PATTERN)', see also %G.
1268 %[NAME]b
1270 the byte offset of the NAMEd group capture; requires option -P
1271 and capturing pattern `(?<NAME>PATTERN)'. Use e for the ending
1272 byte offset and d for the byte length.
1273 %[NAME1|NAME2|...]#
1275 the first NAMEd group capture that matched; requires option -P
1276 and capturing pattern `(?<NAME>PATTERN)', see also %G.
1277 %[NAME1|NAME2|...]b
1279 the byte offset of the first NAMEd group capture that matched;
1280 requires option -P and capturing pattern `(?<NAME>PATTERN)'.
1281 Use e for the ending byte offset and d for the byte length.
1282 %G list of group capture indices/names that matched; requires op‐
1284 tion -P.
1285 %[TEXT1|TEXT2|...]G
1287 list of TEXT indexed by group capture indices that matched; re‐
1288 quires option -P.
1289 %g the group capture index/name matched or 1; requires option -P.
1291 %[TEXT1|TEXT2|...]g
1293 the first TEXT indexed by the first group capture index that
1294 matched; requires option -P.
1295 %% the percentage sign.
1297 Formatted output is written without a terminating newline, unless %~ or
1299 `\n' is explicitly specified in the format string.
1300 The [ARG] part of a field is optional and may be omitted. When
1302 present, the argument must be placed in [] brackets, for example %[,]F
1303 to output a comma, the pathname, and a separator.
1304 %[SEP]$ and %u are switches and do not send anything to the output.
1306 The separator used by the %F, %H, %N, %K, %B, %S and %G fields may be
1308 changed by preceding the field by %[SEP]$. When [SEP] is not provided,
1309 this reverts the separator to the default separator or the separator
1310 specified with --separator.
1311 Formatted output is written for each matching pattern, which means that
1313 a line may be output multiple times when patterns match more than once
1314 on the same line. If field %u is specified anywhere in a format
1315 string, matching lines are output only once, unless option -u, --un‐
1316 group is specified or when more than one line of input matched the
1317 search pattern.
1318 Additional formatting options:
1320 --format-begin=FORMAT
1322 the FORMAT when beginning the search.
1323 --format-open=FORMAT
1325 the FORMAT when opening a file and a match was found.
1326 --format-close=FORMAT
1328 the FORMAT when closing a file and a match was found.
1329 --format-end=FORMAT
1331 the FORMAT when ending the search.
1332 The context options -A, -B, -C, -y, and display options --break,
1334 --heading, --color, -T, and --null have no effect on formatted output.
1335
1337 Display lines containing the word `patricia' in `myfile.txt':
1338 $ ugrep -w patricia myfile.txt
1340 Display lines containing the word `patricia', ignoring case:
1342 $ ugrep -wi patricia myfile.txt
1344 Display lines approximately matching the word `patricia', ignoring case
1346 and allowing up to 2 spelling errors using fuzzy search:
1347 $ ugrep -Z2 -wi patricia myfile.txt
1349 Count the number of lines containing `patricia', ignoring case:
1351 $ ugrep -cwi patricia myfile.txt
1353 Count the number of words `patricia', ignoring case:
1355 $ ugrep -cowi patricia myfile.txt
1357 List lines with `amount' and a decimal, ignoring case (space is AND):
1359 $ ugrep -i --bool 'amount +(.+)?' myfile.txt
1361 Alternative query:
1363 $ ugrep -wi -e amount --and '+(.+)?' myfile.txt
1365 List all Unicode words in a file:
1367 $ ugrep -o '\w+' myfile.txt
1369 List all ASCII words in a file:
1371 $ ugrep -o '[[:word:]]+' myfile.txt
1373 List the laughing face emojis (Unicode code points U+1F600 to U+1F60F):
1375 $ ugrep -o '[\x{1F600}-\x{1F60F}]' myfile.txt
1377 Check if a file contains any non-ASCII (i.e. Unicode) characters:
1379 $ ugrep -q '[^[:ascii:]]' myfile.txt && echo "contains Unicode"
1381 Display the line and column number of `FIXME' in C++ files using recur‐
1383 sive search, with one line of context before and after a matched line:
1384 $ ugrep -C1 -R -n -k -tc++ FIXME
1386 Display the line and column number of `FIXME' in long Javascript files
1388 using recursive search, showing only matches with up to 10 characters
1389 of context before and after:
1390 $ ugrep -o -C20 -R -n -k -tjs FIXME
1392 List the C/C++ comments in a file with line numbers:
1394 $ ugrep -n -e '//.*' -e '/\*([^*]|(\*+[^*/]))*\*+\/' myfile.cpp
1396 The same, but using predefined pattern c++/comments:
1398 $ ugrep -n -f c++/comments myfile.cpp
1400 List the lines that need fixing in a C/C++ source file by looking for
1402 the word `FIXME' while skipping any `FIXME' in quoted strings:
1403 $ ugrep -e FIXME -N '"(\\.|\\\r?\n|[^\\\n"])*"' myfile.cpp
1405 The same, but using predefined pattern cpp/zap_strings:
1407 $ ugrep -e FIXME -f cpp/zap_strings myfile.cpp
1409 Find lines with `FIXME' or `TODO', showing line numberes:
1411 $ ugrep -n -e FIXME -e TODO myfile.cpp
1413 Find lines with `FIXME' that also contain `urgent':
1415 $ ugrep -n -e FIXME --and urgent myfile.cpp
1417 The same, but with a Boolean query pattern (a space is AND):
1419 $ ugrep -n --bool 'FIXME urgent' myfile.cpp
1421 Find lines with `FIXME' that do not also contain `later':
1423 $ ugrep -n -e FIXME --andnot later myfile.cpp
1425 The same, but with a Boolean query pattern (a space is AND, - is NOT):
1427 $ ugrep -n --bool 'FIXME -later' myfile.cpp
1429 Output a list of line numbers of lines with `FIXME' but not `later':
1431 $ ugrep -e FIXME --andnot later --format='%,%n' myfile.cpp
1433 Recursively list all files with both `FIXME' and `LICENSE' anywhere in
1435 the file, not necessarily on the same line:
1436 $ ugrep -l --files --bool 'FIXME LICENSE'
1438 Find lines with `FIXME' in the C/C++ files stored in a tarball:
1440 $ ugrep -z -tc++ -n FIXME project.tgz
1442 Recursively find lines with `FIXME' in C/C++ files, but do not search
1444 any `bak' and `old' directories:
1445 $ ugrep -n FIXME -tc++ -g^bak/,^old/
1447 Recursively search for the word `copyright' in cpio/jar/pax/tar/zip ar‐
1449 chives, compressed and regular files, and in PDFs using a PDF filter:
1450 $ ugrep -z -w --filter='pdf:pdftotext % -' copyright
1452 Match the binary pattern `A3hhhhA3' (hex) in a binary file without Uni‐
1454 code pattern matching -U (which would otherwise match `\xaf' as a Uni‐
1455 code character U+00A3 with UTF-8 byte sequence C2 A3) and display the
1456 results in hex with --hexdump with C1 to output one hex line before and
1457 after each match:
1458 $ ugrep -U --hexdump=C1 '\xa3[\x00-\xff]{2}\xa3' a.out
1460 Hexdump an entire file using a pager for viewing:
1462 $ ugrep -X --pager '' a.out
1464 List all files that are not ignored by one or more `.gitignore':
1466 $ ugrep -l '' --ignore-files
1468 List all files containing a RPM signature, located in the `rpm' direc‐
1470 tory and recursively below up to two levels deeper (3 levels total):
1471 $ ugrep -3 -l -tRpm '' rpm/
1473 Monitor the system log for bug reports and ungroup multiple matches on
1475 a line:
1476 $ tail -f /var/log/system.log | ugrep -u -i -w bug
1478 Interactive fuzzy search with Boolean search queries:
1480 $ ugrep -Q --bool -Z3 --sort=best
1482 Display all words in a MacRoman-encoded file that has CR newlines:
1484 $ ugrep --encoding=MACROMAN '\w+' mac.txt
1486 Display options related to "fuzzy" searching:
1488 $ ugrep --help fuzzy
1490
1492 Report bugs at:
1493 https://github.com/Genivia/ugrep/issues
1495
1497 ugrep is released under the BSD-3 license. All parts of the software
1498 have reasonable copyright terms permitting free redistribution. This
1499 includes the ability to reuse all or parts of the ugrep source tree.
1500
1502 grep(1).
1503ugrep 3.12.7 August 14, 2023 UGREP(1)