1UGREP(1) User Commands UGREP(1)
2
6 ugrep, ug -- file pattern searcher
7
9 ugrep [OPTIONS] [-A NUM] [-B NUM] [-C NUM] [-y] [-Q|PATTERN] [-f FILE]
10 [-e PATTERN] [-N PATTERN] [-t TYPES] [-g GLOBS] [--sort[=KEY]]
11 [--color[=WHEN]|--colour[=WHEN]] [--pager[=COMMAND]] [FILE ...]
12
14 The ugrep utility searches any given input files, selecting lines that
15 match one or more patterns. By default, a pattern matches an input
16 line if the regular expression (RE) matches the input line. A pattern
17 matches multiple input lines if the RE in the pattern matches one or
18 more newlines in the input. An empty pattern matches every line. Each
19 input line that matches at least one of the patterns is written to the
20 standard output.
21 The ug command is intended for interactive searching, using a .ugrep
23 configuration file located in the working directory or home directory,
24 see CONFIGURATION. ug is equivalent to ugrep --config and sorts files
25 by name by default.
26 ugrep accepts input of various encoding formats and normalizes the out‐
28 put to UTF-8. When a UTF byte order mark is present in the input, the
29 input is automatically normalized; otherwise, ugrep assumes the input
30 is ASCII, UTF-8, or raw binary. An input encoding format may be speci‐
31 fied with option --encoding.
32 If no FILE arguments are specified and standard input is read from a
34 terminal, recursive searches are performed as if -r is specified. To
35 force reading from standard input, specify `-' as a FILE argument.
36 Directories specified as FILE arguments are searched without recursing
38 deeper into subdirectories, unless -R, -r, or -2...-9 is specified to
39 search subdirectories.
40 Hidden files and directories are ignored in recursive searches. Option
42 -. (--hidden) includes hidden files and directories in recursive
43 searches.
44 A query interface is opened with -Q (--query) to interactively specify
46 search patterns and view search results. Note that a PATTERN argument
47 cannot be specified in this case. To specify one or more patterns with
48 -Q to start searching, use -e PATTERN.
49 Option -f FILE matches patterns specified in FILE. If FILE is large
51 and defines complex regular expression patterns, then option -P (Perl
52 matching) may improve performance (this omits POSIX DFA construction.)
53 ugrep --help WHAT displays help on options related to WHAT; --help for‐
55 mat displays help on --format and --replace formatting; --help regex
56 displays help on regular expression syntax and conventions; --help
57 globs displays help on glob patterns to select files to search; --help
58 fuzzy displays help on fuzzy (approximate) searching.
59 The following options are available:
61 -A NUM, --after-context=NUM
63 Output NUM lines of trailing context after matching lines.
64 Places a --group-separator between contiguous groups of matches.
65 If -o is specified, output the match with context to fit NUM
66 columns after the match or shortens the match. See also options
67 -B, -C and -y.
68 -a, --text
70 Process a binary file as if it were text. This is equivalent to
71 the --binary-files=text option. This option might output binary
72 garbage to the terminal, which can have problematic consequences
73 if the terminal driver interprets some of it as commands.
74 --and [-e] PATTERN ... -e PATTERN
76 Specify additional patterns to match. Patterns must be speci‐
77 fied with -e. Each -e PATTERN following this option is consid‐
78 ered an alternative pattern to match, i.e. each -e is inter‐
79 preted as an OR pattern. For example, -e A -e B --and -e C -e D
80 matches lines with (`A' or `B') and (`C' or `D'). Note that
81 multiple -e PATTERN are alternations that bind more tightly to‐
82 gether than --and. Option --stats displays the search patterns
83 applied. See also options --not, --andnot, --bool, --files and
84 --lines.
85 --andnot [-e] PATTERN
87 Combines --and --not. See also options --and, --not and --bool.
88 -B NUM, --before-context=NUM
90 Output NUM lines of leading context before matching lines.
91 Places a --group-separator between contiguous groups of matches.
92 If -o is specified, output the match with context to fit NUM
93 columns before the match or shortens the match. See also op‐
94 tions -A, -C and -y.
95 -b, --byte-offset
97 The offset in bytes of a matched line is displayed in front of
98 the respective matched line. If -u is specified, displays the
99 offset for each pattern matched on the same line. Byte offsets
100 are exact for ASCII, UTF-8 and raw binary input. Otherwise, the
101 byte offset in the UTF-8 normalized input is displayed.
102 --binary-files=TYPE
104 Controls searching and reporting pattern matches in binary
105 files. TYPE can be `binary', `without-match`, `text`, `hex` and
106 `with-hex'. The default is `binary' to search binary files and
107 to report a match without displaying the match. `without-match'
108 ignores binary matches. `text' treats all binary files as text,
109 which might output binary garbage to the terminal, which can
110 have problematic consequences if the terminal driver interprets
111 some of it as commands. `hex' reports all matches in hexadeci‐
112 mal. `with-hex' only reports binary matches in hexadecimal,
113 leaving text matches alone. A match is considered binary when
114 matching a zero byte or invalid UTF. Short options are -a, -I,
115 -U, -W and -X.
116 --bool, -%
118 Specifies Boolean query patterns. A Boolean query pattern is
119 composed of `AND', `OR', `NOT' operators and grouping with `('
120 `)'. Spacing between subpatterns is the same as `AND', `|' is
121 the same as `OR' and a `-' is the same as `NOT'. The `OR' oper‐
122 ator binds more tightly than `AND'. For example, --bool 'A|B
123 C|D' matches lines with (`A' or `B') and (`C' or `D'), --bool 'A
124 -B' matches lines with `A' and not `B'. Operators `AND', `OR',
125 `NOT' require proper spacing. For example, --bool 'A OR B AND C
126 OR D' matches lines with (`A' or `B') and (`C' or `D'), --bool
127 'A AND NOT B' matches lines with `A' without `B'. Quoted sub‐
128 patterns are matched literally as strings. For example, --bool
129 'A "AND"|"OR"' matches lines with `A' and also either `AND' or
130 `OR'. Parenthesis are used for grouping. For example, --bool
131 '(A B)|C' matches lines with `A' and `B', or lines with `C'.
132 Note that all subpatterns in a Boolean query pattern are regular
133 expressions, unless -F is specified. Options -E, -F, -G, -P and
134 -Z can be combined with --bool to match subpatterns as strings
135 or regular expressions (-E is the default.) This option does
136 not apply to -f FILE patterns. Option --stats displays the
137 search patterns applied. See also options --and, --andnot,
138 --not, --files and --lines.
139 --break
141 Adds a line break between results from different files. This
142 option is enabled by --pretty when the output is sent to a ter‐
143 minal.
144 -C NUM, --context=NUM
146 Output NUM lines of leading and trailing context surrounding
147 each matching line. Places a --group-separator between contigu‐
148 ous groups of matches. If -o is specified, output the match
149 with context to fit NUM columns before and after the match or
150 shortens the match. See also options -A, -B and -y.
151 -c, --count
153 Only a count of selected lines is written to standard output.
154 If -o or -u is specified, counts the number of patterns matched.
155 If -v is specified, counts the number of non-matching lines. If
156 --tree is specified, outputs directories in a tree-like format.
157 --color[=WHEN], --colour[=WHEN]
159 Mark up the matching text with the expression stored in the
160 GREP_COLOR or GREP_COLORS environment variable. WHEN can be
161 `never', `always', or `auto', where `auto' marks up matches only
162 when output on a terminal. The default is `auto'.
163 --colors=COLORS, --colours=COLORS
165 Use COLORS to mark up text. COLORS is a colon-separated list of
166 one or more parameters `sl=' (selected line), `cx=' (context
167 line), `mt=' (matched text), `ms=' (match selected), `mc='
168 (match context), `fn=' (file name), `ln=' (line number), `cn='
169 (column number), `bn=' (byte offset), `se=' (separator). Param‐
170 eter values are ANSI SGR color codes or `k' (black), `r' (red),
171 `g' (green), `y' (yellow), `b' (blue), `m' (magenta), `c'
172 (cyan), `w' (white). Upper case specifies background colors. A
173 `+' qualifies a color as bright. A foreground and a background
174 color may be combined with font properties `n' (normal), `f'
175 (faint), `h' (highlight), `i' (invert), `u' (underline). Param‐
176 eter `hl' enables file name hyperlinks. Parameter `rv' reverses
177 the `sl=' and `cx=' parameters when option -v is specified. Se‐
178 lectively overrides GREP_COLORS.
179 --config[=FILE], ---[FILE]
181 Use configuration FILE. The default FILE is `.ugrep'. The
182 working directory is checked first for FILE, then the home di‐
183 rectory. The options specified in the configuration FILE are
184 parsed first, followed by the remaining options specified on the
185 command line.
186 --confirm
188 Confirm actions in -Q query mode. The default is confirm.
189 --cpp Output file matches in C++. See also options --format and -u.
191 --csv Output file matches in CSV. If -H, -n, -k, or -b is specified,
193 additional values are output. See also options --format and -u.
194 -D ACTION, --devices=ACTION
196 If an input file is a device, FIFO or socket, use ACTION to
197 process it. By default, ACTION is `skip', which means that de‐
198 vices are silently skipped. If ACTION is `read', devices read
199 just as if they were ordinary files.
200 -d ACTION, --directories=ACTION
202 If an input file is a directory, use ACTION to process it. By
203 default, ACTION is `skip', i.e., silently skip directories un‐
204 less specified on the command line. If ACTION is `read', warn
205 when directories are read as input. If ACTION is `recurse',
206 read all files under each directory, recursively, following sym‐
207 bolic links only if they are on the command line. This is
208 equivalent to the -r option. If ACTION is `dereference-re‐
209 curse', read all files under each directory, recursively, fol‐
210 lowing symbolic links. This is equivalent to the -R option.
211 --depth=[MIN,][MAX], -1, -2, -3, ... -9, --10, --11, --12, ...
213 Restrict recursive searches from MIN to MAX directory levels
214 deep, where -1 (--depth=1) searches the specified path without
215 recursing into subdirectories. Note that -3 -5, -3-5, and -35
216 search 3 to 5 levels deep. Enables -r if -R or -r is not speci‐
217 fied.
218 --dotall
220 Dot `.' in regular expressions matches anything, including new‐
221 line. Note that `.*' matches all input and should not be used.
222 -E, --extended-regexp
224 Interpret patterns as extended regular expressions (EREs). This
225 is the default.
226 -e PATTERN, --regexp=PATTERN
228 Specify a PATTERN used during the search of the input: an input
229 line is selected if it matches any of the specified patterns.
230 Note that longer patterns take precedence over shorter patterns.
231 This option is most useful when multiple -e options are used to
232 specify multiple patterns, when a pattern begins with a dash
233 (`-'), to specify a pattern after option -f or after the FILE
234 arguments.
235 --encoding=ENCODING
237 The encoding format of the input. The default ENCODING is bi‐
238 nary and UTF-8 which are the same. Note that option -U speci‐
239 fies binary PATTERN matching (text matching is the default.)
240 ENCODING can be: `binary', `ASCII', `UTF-8', `UTF-16',
241 `UTF-16BE', `UTF-16LE', `UTF-32', `UTF-32BE', `UTF-32LE',
242 `LATIN1', `ISO-8859-1', `ISO-8859-2', `ISO-8859-3',
243 `ISO-8859-4', `ISO-8859-5', `ISO-8859-6', `ISO-8859-7',
244 `ISO-8859-8', `ISO-8859-9', `ISO-8859-10', `ISO-8859-11',
245 `ISO-8859-13', `ISO-8859-14', `ISO-8859-15', `ISO-8859-16',
246 `MAC', `MACROMAN', `EBCDIC', `CP437', `CP850', `CP858',
247 `CP1250', `CP1251', `CP1252', `CP1253', `CP1254', `CP1255',
248 `CP1256', `CP1257', `CP1258', `KOI8-R', `KOI8-U', `KOI8-RU'.
249 --exclude=GLOB
251 Skip files whose name matches GLOB using wildcard matching, same
252 as -g ^GLOB. GLOB can use **, *, ?, and [...] as wildcards and
253 \ to quote a wildcard or backslash character literally. When
254 GLOB contains a `/', full pathnames are matched. Otherwise
255 basenames are matched. When GLOB ends with a `/', directories
256 are excluded as if --exclude-dir is specified. Otherwise files
257 are excluded. Note that --exclude patterns take priority over
258 --include patterns. GLOB should be quoted to prevent shell
259 globbing. This option may be repeated.
260 --exclude-dir=GLOB
262 Exclude directories whose name matches GLOB from recursive
263 searches, same as -g ^GLOB/. GLOB can use **, *, ?, and [...]
264 as wildcards and \ to quote a wildcard or backslash character
265 literally. When GLOB contains a `/', full pathnames are
266 matched. Otherwise basenames are matched. Note that --ex‐
267 clude-dir patterns take priority over --include-dir patterns.
268 GLOB should be quoted to prevent shell globbing. This option
269 may be repeated.
270 --exclude-from=FILE
272 Read the globs from FILE and skip files and directories whose
273 name matches one or more globs. A glob can use **, *, ?, and
274 [...] as wildcards and \ to quote a wildcard or backslash char‐
275 acter literally. When a glob contains a `/', full pathnames are
276 matched. Otherwise basenames are matched. When a glob ends
277 with a `/', directories are excluded as if --exclude-dir is
278 specified. Otherwise files are excluded. A glob starting with
279 a `!' overrides previously-specified exclusions by including
280 matching files. Lines starting with a `#' and empty lines in
281 FILE are ignored. When FILE is a `-', standard input is read.
282 This option may be repeated.
283 --exclude-fs=MOUNTS
285 Exclude file systems specified by MOUNTS from recursive
286 searches, MOUNTS is a comma-separated list of mount points or
287 pathnames of directories on file systems. Note that --ex‐
288 clude-fs mounts take priority over --include-fs mounts. This
289 option may be repeated.
290 -F, --fixed-strings
292 Interpret pattern as a set of fixed strings, separated by new‐
293 lines, any of which is to be matched. This makes ugrep behave
294 as fgrep. If a PATTERN is specified, or -e PATTERN or -N PAT‐
295 TERN, then this option has no effect on -f FILE patterns to al‐
296 low -f FILE patterns to narrow or widen the scope of the PATTERN
297 search.
298 -f FILE, --file=FILE
300 Read newline-separated patterns from FILE. White space in pat‐
301 terns is significant. Empty lines in FILE are ignored. If FILE
302 does not exist, the GREP_PATH environment variable is used as
303 path to FILE. If that fails, looks for FILE in /usr/lo‐
304 cal/share/ugrep/patterns. When FILE is a `-', standard input is
305 read. Empty files contain no patterns; thus nothing is matched.
306 This option may be repeated.
307 --filter=COMMANDS
309 Filter files through the specified COMMANDS first before search‐
310 ing. COMMANDS is a comma-separated list of `exts:command [op‐
311 tion ...]', where `exts' is a comma-separated list of filename
312 extensions and `command' is a filter utility. The filter util‐
313 ity should read from standard input and write to standard out‐
314 put. Files matching one of `exts' are filtered. When `exts' is
315 `*', files with non-matching extensions are filtered. One or
316 more `option' separated by spacing may be specified, which are
317 passed verbatim to the command. A `%' as `option' expands into
318 the pathname to search. For example, --filter='pdf:pdftotext %
319 -' searches PDF files. The `%' expands into a `-' when search‐
320 ing standard input. Option --label=.ext may be used to specify
321 extension `ext' when searching standard input.
322 --filter-magic-label=[+]LABEL:MAGIC
324 Associate LABEL with files whose signature "magic bytes" match
325 the MAGIC regex pattern. Only files that have no filename ex‐
326 tension are labeled, unless +LABEL is specified. When LABEL
327 matches an extension specified in --filter=COMMANDS, the corre‐
328 sponding command is invoked. This option may be repeated.
329 --format=FORMAT
331 Output FORMAT-formatted matches. For example --for‐
332 mat='%f:%n:%O%~' outputs matching lines `%O' with filename `%f`
333 and line number `%n' followed by a newline `%~'. If -P is spec‐
334 ified, FORMAT may include `%1' to `%9', `%[NUM]#' and `%[NAME]#'
335 to output group captures. A `%%' outputs `%'. See `ugrep
336 --help format' and `man ugrep' section FORMAT for details. When
337 option -o is specified, option -u is also enabled. Context op‐
338 tions -A, -B, -C and -y are ignored.
339 --free-space
341 Spacing (blanks and tabs) in regular expressions are ignored.
342 -G, --basic-regexp
344 Interpret patterns as basic regular expressions (BREs), i.e.
345 make ugrep behave as traditional grep.
346 -g GLOBS, --glob=GLOBS
348 Search only files whose name matches the specified comma-sepa‐
349 rated list of GLOBS, same as --include='glob' for each `glob' in
350 GLOBS. When a `glob' is preceded by a `!' or a `^', skip files
351 whose name matches `glob', same as --exclude='glob'. When
352 `glob' contains a `/', full pathnames are matched. Otherwise
353 basenames are matched. When `glob' ends with a `/', directories
354 are matched, same as --include-dir='glob' and --ex‐
355 clude-dir='glob'. A leading `/' matches the working directory.
356 This option may be repeated and may be combined with options -M,
357 -O and -t to expand searches. See `ugrep --help globs' and `man
358 ugrep' section GLOBBING for details.
359 --group-separator[=SEP]
361 Use SEP as a group separator for context options -A, -B and -C.
362 The default is a double hyphen (`--').
363 -H, --with-filename
365 Always print the filename with output lines. This is the de‐
366 fault when there is more than one file to search.
367 -h, --no-filename
369 Never print filenames with output lines. This is the default
370 when there is only one file (or only standard input) to search.
371 --heading, -+
373 Group matches per file. Adds a heading and a line break between
374 results from different files. This option is enabled by
375 --pretty when the output is sent to a terminal.
376 --help [WHAT], -? [WHAT]
378 Display a help message, specifically on WHAT when specified. In
379 addition, `--help format' displays an overview of FORMAT fields,
380 `--help regex' displays an overview of regular expressions and
381 `--help globs' displays an overview of glob syntax and conven‐
382 tions.
383 --hexdump=[1-8][a][bch][A[NUM]][B[NUM]][C[NUM]]
385 Output matches in 1 to 8 columns of 8 hexadecimal octets. The
386 default is 2 columns or 16 octets per line. Option `a' outputs
387 a `*' for all hex lines that are identical to the previous hex
388 line, `b' removes all space breaks, `c' removes the character
389 column, `h' removes hex spacing, `A' includes up to NUM hex
390 lines after the match, `B' includes up to NUM hex lines before
391 the match and `C' includes up to NUM hex lines. When NUM is
392 omitted, the matching line is included in the output. See also
393 options -U, -W and -X.
394 --hidden, -.
396 Search hidden files and directories.
397 --hyperlink[=[PREFIX][+]]
399 Hyperlinks are enabled for file names when colors are enabled.
400 Same as --colors=hl. When PREFIX is specified, replaces file://
401 with PREFIX:// in the hyperlink. A `+' includes the line number
402 in the hyperlink and when option -k is specified, the column
403 number.
404 -I, --ignore-binary
406 Ignore matches in binary files. This option is equivalent to
407 the --binary-files=without-match option.
408 -i, --ignore-case
410 Perform case insensitive matching. By default, ugrep is case
411 sensitive. By default, this option applies to ASCII letters
412 only. Use options -P and -i for Unicode case insensitive match‐
413 ing.
414 --ignore-files[=FILE]
416 Ignore files and directories matching the globs in each FILE
417 that is encountered in recursive searches. The default FILE is
418 `.gitignore'. Matching files and directories located in the di‐
419 rectory of a FILE's location and in directories below are ig‐
420 nored by temporarily extending the --exclude and --exclude-dir
421 globs, as if --exclude-from=FILE is locally enforced. Globbing
422 syntax is the same as the --exclude-from=FILE gitignore syntax;
423 directories are excluded when the glob ends in a `/', same as
424 git. Files and directories explicitly specified as command line
425 arguments are never ignored. This option may be repeated with
426 additional files.
427 --include=GLOB
429 Search only files whose name matches GLOB using wildcard match‐
430 ing, same as -g GLOB. GLOB can use **, *, ?, and [...] as wild‐
431 cards and \ to quote a wildcard or backslash character liter‐
432 ally. When GLOB contains a `/', full pathnames are matched.
433 Otherwise basenames are matched. When GLOB ends with a `/', di‐
434 rectories are included as if --include-dir is specified. Other‐
435 wise files are included. Note that --exclude patterns take pri‐
436 ority over --include patterns. GLOB should be quoted to prevent
437 shell globbing. This option may be repeated.
438 --include-dir=GLOB
440 Only directories whose name matches GLOB are included in recur‐
441 sive searches, same as -g GLOB/. GLOB can use **, *, ?, and
442 [...] as wildcards and \ to quote a wildcard or backslash char‐
443 acter literally. When GLOB contains a `/', full pathnames are
444 matched. Otherwise basenames are matched. Note that --ex‐
445 clude-dir patterns take priority over --include-dir patterns.
446 GLOB should be quoted to prevent shell globbing. This option
447 may be repeated.
448 --include-from=FILE
450 Read the globs from FILE and search only files and directories
451 whose name matches one or more globs. A glob can use **, *, ?,
452 and [...] as wildcards and \ to quote a wildcard or backslash
453 character literally. When a glob contains a `/', full pathnames
454 are matched. Otherwise basenames are matched. When a glob ends
455 with a `/', directories are included as if --include-dir is
456 specified. Otherwise files are included. A glob starting with
457 a `!' overrides previously-specified inclusions by excluding
458 matching files. Lines starting with a `#' and empty lines in
459 FILE are ignored. When FILE is a `-', standard input is read.
460 This option may be repeated.
461 --include-fs=MOUNTS
463 Only file systems specified by MOUNTS are included in recursive
464 searches. MOUNTS is a comma-separated list of mount points or
465 pathnames of directories on file systems. --include-fs=. re‐
466 stricts recursive searches to the file system of the working di‐
467 rectory only. Note that --exclude-fs mounts take priority over
468 --include-fs mounts. This option may be repeated.
469 -J NUM, --jobs=NUM
471 Specifies the number of threads spawned to search files. By de‐
472 fault an optimum number of threads is spawned to search files
473 simultaneously. -J1 disables threading: files are searched in
474 the same order as specified.
475 -j, --smart-case
477 Perform case insensitive matching like option -i, unless a pat‐
478 tern is specified with a literal ASCII upper case letter.
479 --json Output file matches in JSON. If -H, -n, -k, or -b is specified,
481 additional values are output. See also options --format and -u.
482 -K [MIN,][MAX], --range=[MIN,][MAX], --min-line=MIN, --max-line=MAX
484 Start searching at line MIN, stop at line MAX when specified.
485 -k, --column-number
487 The column number of a matched pattern is displayed in front of
488 the respective matched line, starting at column 1. Tabs are ex‐
489 panded when columns are counted, see also option --tabs.
490 -L, --files-without-match
492 Only the names of files not containing selected lines are writ‐
493 ten to standard output. Pathnames are listed once per file
494 searched. If the standard input is searched, the string
495 ``(standard input)'' is written. If --tree is specified, out‐
496 puts directories in a tree-like format.
497 -l, --files-with-matches
499 Only the names of files containing selected lines are written to
500 standard output. ugrep will only search a file until a match
501 has been found, making searches potentially less expensive.
502 Pathnames are listed once per file searched. If the standard
503 input is searched, the string ``(standard input)'' is written.
504 If --tree is specified, outputs directories in a tree-like for‐
505 mat.
506 --label=LABEL
508 Displays the LABEL value when input is read from standard input
509 where a file name would normally be printed in the output. As‐
510 sociates a filename extension with standard input when LABEL has
511 a suffix. The default value is `(standard input)'.
512 --line-buffered
514 Force output to be line buffered instead of block buffered.
515 --lines
517 Apply Boolean queries to match lines, the opposite of --files.
518 This is the default Boolean query mode to match specific lines.
519 -M MAGIC, --file-magic=MAGIC
521 Only files matching the signature pattern MAGIC are searched.
522 The signature "magic bytes" at the start of a file are compared
523 to the MAGIC regex pattern. When matching, the file will be
524 searched. When MAGIC is preceded by a `!' or a `^', skip files
525 with matching MAGIC signatures. This option may be repeated and
526 may be combined with options -O and -t to expand the search.
527 Every file on the search path is read, making searches poten‐
528 tially more expensive.
529 -m [MIN,][MAX], --min-count=MIN, --max-count=MAX
531 Require MIN matches, stop after MAX matches when specified.
532 Output MIN to MAX matches. For example, -m1 outputs the first
533 match and -cm1, (with a comma) counts non-zero matches. See
534 also option -K.
535 --match
537 Match all input. Same as specifying an empty pattern to search.
538 --max-files=NUM
540 Restrict the number of files matched to NUM. Note that --sort
541 or -J1 may be specified to produce replicable results. If
542 --sort is specified, the number of threads spawned is limited to
543 NUM.
544 --mmap[=MAX]
546 Use memory maps to search files. By default, memory maps are
547 used under certain conditions to improve performance. When MAX
548 is specified, use up to MAX mmap memory per thread.
549 -N PATTERN, --neg-regexp=PATTERN
551 Specify a negative PATTERN used during the search of the input:
552 an input line is selected only if it matches the specified pat‐
553 terns unless it matches the negative PATTERN. Same as -e
554 (?^PATTERN). Negative pattern matches are essentially removed
555 before any other patterns are matched. Note that longer pat‐
556 terns take precedence over shorter patterns. This option may be
557 repeated.
558 -n, --line-number
560 Each output line is preceded by its relative line number in the
561 file, starting at line 1. The line number counter is reset for
562 each file processed.
563 --no-group-separator
565 Removes the group separator line from the output for context op‐
566 tions -A, -B and -C.
567 --not [-e] PATTERN
569 Specifies that PATTERN should not match. Note that -e A --not
570 -e B matches lines with `A' or lines without a `B'. To match
571 lines with `A' that have no `B', specify -e A --andnot -e B.
572 Option --stats displays the search patterns applied. See also
573 options --and, --andnot, --bool, --files and --lines.
574 -O EXTENSIONS, --file-extension=EXTENSIONS
576 Search only files whose filename extensions match the specified
577 comma-separated list of EXTENSIONS, same as --include='*.ext'
578 for each `ext' in EXTENSIONS. When an `ext' is preceded by a
579 `!' or a `^', skip files whose filename extensions matches
580 `ext', same as --exclude='*.ext'. This option may be repeated
581 and may be combined with options -g, -M and -t to expand the re‐
582 cursive search.
583 -o, --only-matching
585 Output only the matching part of lines. Output additional
586 matches on the same line with `+' as the field separator. When
587 multiple lines match a pattern, output the matching lines with
588 `|' as the field separator. If -A, -B or -C is specified, fits
589 the match and its context on a line within the specified number
590 of columns.
591 --only-line-number
593 The line number of the matching line in the file is output with‐
594 out displaying the match. The line number counter is reset for
595 each file processed.
596 --files
598 Apply Boolean queries to match files, the opposite of --lines.
599 A file matches if all Boolean conditions are satisfied by the
600 lines matched in the file. For example, --files -e A --and -e B
601 -e C --andnot -e D matches a file if some lines match `A' and
602 some lines match (`B' or `C') and no line in the file matches
603 `D'. May also be specified as --files --bool 'A B|C -D'. Op‐
604 tion -v cannot be specified with --files. See also options
605 --and, --andnot, --not, --bool and --lines.
606 -P, --perl-regexp
608 Interpret PATTERN as a Perl regular expression using PCRE2.
609 Note that Perl pattern matching differs from the default grep
610 POSIX pattern matching.
611 -p, --no-dereference
613 If -R or -r is specified, no symbolic links are followed, even
614 when they are specified on the command line.
615 --pager[=COMMAND]
617 When output is sent to the terminal, uses COMMAND to page
618 through the output. The default COMMAND is `less -R'. Enables
619 --heading and --line-buffered.
620 --pretty
622 When output is sent to a terminal, enables --color, --heading,
623 -n, --sort, --tree and -T when not explicitly disabled.
624 -Q[DELAY], --query[=DELAY]
626 Query mode: user interface to perform interactive searches.
627 This mode requires an ANSI capable terminal. An optional DELAY
628 argument may be specified to reduce or increase the response
629 time to execute searches after the last key press, in increments
630 of 100ms, where the default is 5 (0.5s delay). No whitespace
631 may be given between -Q and its argument DELAY. Initial pat‐
632 terns may be specified with -e PATTERN, i.e. a PATTERN argument
633 requires option -e. Press F1 or CTRL-Z to view the help screen.
634 Press F2 or CTRL-Y to invoke a command to view or edit the file
635 shown at the top of the screen. The command can be specified
636 with option --view, or defaults to environment variable PAGER if
637 defined, or EDITOR. Press Tab and Shift-Tab to navigate direc‐
638 tories and to select a file to search. Press Enter to select
639 lines to output. Press ALT-l for option -l to list files, ALT-n
640 for -n, etc. Non-option commands include ALT-] to increase
641 fuzziness and ALT-} to increase context. Enables --heading.
642 See also options --confirm and --view.
643 -q, --quiet, --silent
645 Quiet mode: suppress all output. ugrep will only search until a
646 match has been found.
647 -R, --dereference-recursive
649 Recursively read all files under each directory. Follow all
650 symbolic links, unlike -r. See also option --sort.
651 -r, --recursive
653 Recursively read all files under each directory, following sym‐
654 bolic links only if they are specified on the command line.
655 Note that when no FILE arguments are specified and input is read
656 from a terminal, recursive searches are performed as if -r is
657 specified. See also option --sort.
658 --replace=FORMAT
660 Replace matching patterns in the output by the specified FORMAT
661 with `%' fields. If -P is specified, FORMAT may include `%1' to
662 `%9', `%[NUM]#' and `%[NAME]#' to output group captures. A `%%'
663 outputs `%' and `%~' outputs a newline. See option --format,
664 `ugrep --help format' and `man ugrep' section FORMAT for de‐
665 tails.
666 -S, --dereference
668 If -r is specified, all symbolic links are followed, like -R.
669 The default is not to follow symbolic links to directories.
670 -s, --no-messages
672 Silent mode: nonexistent and unreadable files are ignored, i.e.
673 their error messages and warnings are suppressed.
674 --save-config[=FILE]
676 Save configuration FILE. By default `.ugrep' is saved. If FILE
677 is a `-', write the configuration to standard output.
678 --separator[=SEP]
680 Use SEP as field separator between file name, line number, col‐
681 umn number, byte offset and the matched line. The default is a
682 colon (`:'), a plus (`+') for additional matches on the same
683 line, and a bar (`|') for multi-line pattern matches.
684 --sort[=KEY]
686 Displays matching files in the order specified by KEY in recur‐
687 sive searches. Normally the ug command sorts by name whereas
688 the ugrep batch command displays matches in no particular order
689 to improve performance. The sort KEY can be `name' to sort by
690 pathname (default), `best' to sort by best match with option -Z
691 (sort by best match requires two passes over files, which is ex‐
692 pensive), `size' to sort by file size, `used' to sort by last
693 access time, `changed' to sort by last modification time and
694 `created' to sort by creation time. Sorting is reversed with
695 `rname', `rbest', `rsize', `rused', `rchanged', or `rcreated'.
696 Archive contents are not sorted. Subdirectories are sorted and
697 displayed after matching files. FILE arguments are searched in
698 the same order as specified.
699 --stats
701 Output statistics on the number of files and directories
702 searched and the inclusion and exclusion constraints applied.
703 -T, --initial-tab
705 Add a tab space to separate the file name, line number, column
706 number and byte offset with the matched line.
707 -t TYPES, --file-type=TYPES
709 Search only files associated with TYPES, a comma-separated list
710 of file types. Each file type corresponds to a set of filename
711 extensions passed to option -O and filenames passed to option
712 -g. For capitalized file types, the search is expanded to in‐
713 clude files with matching file signature magic bytes, as if
714 passed to option -M. When a type is preceded by a `!' or a `^',
715 excludes files of the specified type. This option may be re‐
716 peated. The possible file types can be (where -tlist displays a
717 detailed list): `actionscript', `ada', `asm', `asp', `aspx',
718 `autoconf', `automake', `awk', `Awk', `basic', `batch', `bison',
719 `c', `c++', `clojure', `cpp', `csharp', `css', `csv', `dart',
720 `Dart', `delphi', `elisp', `elixir', `erlang', `fortran', `gif',
721 `Gif', `go', `groovy', `gsp', `haskell', `html', `jade', `java',
722 `jpeg', `Jpeg', `js', `json', `jsp', `julia', `kotlin', `less',
723 `lex', `lisp', `lua', `m4', `make', `markdown', `matlab',
724 `node', `Node', `objc', `objc++', `ocaml', `parrot', `pascal',
725 `pdf', `Pdf', `perl', `Perl', `php', `Php', `png', `Png', `pro‐
726 log', `python', `Python', `r', `rpm', `Rpm', `rst', `rtf',
727 `Rtf', `ruby', `Ruby', `rust', `scala', `scheme', `shell',
728 `Shell', `smalltalk', `sql', `svg', `swift', `tcl', `tex',
729 `text', `tiff', `Tiff', `tt', `typescript', `verilog', `vhdl',
730 `vim', `xml', `Xml', `yacc', `yaml'.
731 --tabs[=NUM]
733 Set the tab size to NUM to expand tabs for option -k. The value
734 of NUM may be 1, 2, 4, or 8. The default tab size is 8.
735 --tag[=TAG[,END]]
737 Disables colors to mark up matches with TAG. END marks the end
738 of a match if specified, otherwise TAG. The default is `___'.
739 --tree, -^
741 Output directories with matching files in a tree-like format
742 when options -c, -l or -L are used. This option is enabled by
743 --pretty when the output is sent to a terminal.
744 -U, --binary
746 Disables Unicode matching for binary file matching, forcing PAT‐
747 TERN to match bytes, not Unicode characters. For example, -U
748 '\xa3' matches byte A3 (hex) instead of the Unicode code point
749 U+00A3 represented by the UTF-8 sequence C2 A3. See also option
750 --dotall.
751 -u, --ungroup
753 Do not group multiple pattern matches on the same matched line.
754 Output the matched line again for each additional pattern match,
755 using `+' as a separator.
756 -V, --version
758 Display version with linked libraries and exit.
759 -v, --invert-match
761 Selected lines are those not matching any of the specified pat‐
762 terns.
763 --view[=COMMAND]
765 Use COMMAND to view/edit a file in query mode when pressing
766 CTRL-Y.
767 -W, --with-hex
769 Output binary matches in hexadecimal, leaving text matches
770 alone. This option is equivalent to the --binary-files=with-hex
771 option with --hexdump=2C. To omit the matching line from the
772 hex output, combine option --hexdump with option -W. See also
773 option -U.
774 -w, --word-regexp
776 The PATTERN is searched for as a word, such that the matching
777 text is preceded by a non-word character and is followed by a
778 non-word character. Word characters are letters, digits and the
779 underscore. With option -P, word characters are Unicode let‐
780 ters, digits and underscore. This option has no effect if -x is
781 also specified. If a PATTERN is specified, or -e PATTERN or -N
782 PATTERN, then this option has no effect on -f FILE patterns to
783 allow -f FILE patterns to narrow or widen the scope of the PAT‐
784 TERN search.
785 --width[=NUM]
787 Truncate the output to NUM visible characters per line. The
788 width of the terminal window is used if NUM is not specified.
789 Note that double wide characters in the output may result in
790 wider lines.
791 -X, --hex
793 Output matches in hexadecimal. This option is equivalent to the
794 --binary-files=hex option with --hexdump=2C. To omit the match‐
795 ing line from the hex output, use option --hexdump instead of
796 -X. See also option -U.
797 -x, --line-regexp
799 Select only those matches that exactly match the whole line, as
800 if the patterns are surrounded by ^ and $. If a PATTERN is
801 specified, or -e PATTERN or -N PATTERN, then this option has no
802 effect on -f FILE patterns to allow -f FILE patterns to narrow
803 or widen the scope of the PATTERN search.
804 --xml Output file matches in XML. If -H, -n, -k, or -b is specified,
806 additional values are output. See also options --format and -u.
807 -Y, --empty
809 Permits empty matches. By default, empty matches are disabled,
810 unless a pattern begins with `^' or ends with `$'. With this
811 option, empty-matching patterns such as x? and x*, match all in‐
812 put, not only lines containing the character `x'.
813 -y, --any-line, --passthru
815 Any line is output (passthru). Non-matching lines are output as
816 context with a `-' separator. See also options -A, -B and -C.
817 -Z[best][+-~][MAX], --fuzzy=[best][+-~][MAX]
819 Fuzzy mode: report approximate pattern matches within MAX er‐
820 rors. The default is -Z1: one deletion, insertion or substitu‐
821 tion is allowed. If `+`, `-' and/or `~' is specified, then `+'
822 allows insertions, `-' allows deletions and `~' allows substitu‐
823 tions. For example, -Z+~3 allows up to three insertions or sub‐
824 stitutions, but no deletions. If `best' is specified, then only
825 the best matching lines are output with the lowest cost per
826 file. Option -Zbest requires two passes over a file and cannot
827 be used with standard input or Boolean queries. Option
828 --sort=best orders matching files by best match. The first
829 character of an approximate match always matches a character at
830 the beginning of the pattern. To fuzzy match the first charac‐
831 ter, replace it with a `.' or `.?'. Option -U applies fuzzy
832 matching to ASCII and bytes instead of Unicode text. No white‐
833 space may be given between -Z and its argument.
834 -z, --decompress
836 Decompress files to search, when compressed. Archives (.cpio,
837 .pax, .tar and .zip) and compressed archives (e.g. .taz, .tgz,
838 .tpz, .tbz, .tbz2, .tb2, .tz2, .tlz, .txz, .tzst) are searched
839 and matching pathnames of files in archives are output in
840 braces. If -g, -O, -M, or -t is specified, searches files
841 stored in archives whose filenames match globs, match filename
842 extensions, match file signature magic bytes, or match file
843 types, respectively. Supported compression formats: gzip (.gz),
844 compress (.Z), zip, bzip2 (requires suffix .bz, .bz2, .bzip2,
845 .tbz, .tbz2, .tb2, .tz2), lzma and xz (requires suffix .lzma,
846 .tlz, .xz, .txz), lz4 (requires suffix .lz4), zstd (requires
847 suffix .zst, .zstd, .tzst).
848 --zmax=NUM
850 When used with option -z (--decompress), searches the contents
851 of compressed files and archives stored within archives by up to
852 NUM recursive expansions. The default --zmax=1 only permits
853 searching uncompressed files stored in cpio, pax, tar and zip
854 archives; compressed files and archives are detected as binary
855 files and are effectively ignored. Specify --zmax=2 to search
856 compressed files and archives stored in cpio, pax, tar and zip
857 archives. NUM may range from 1 to 99 for up to 99 decompression
858 and de-archiving steps. Increasing NUM values gradually de‐
859 grades performance.
860 -0, --null
862 Output a zero-byte (NUL) after the file name. This option can
863 be used with commands such as `find -print0' and `xargs -0' to
864 process arbitrary file names.
865 A `--' signals the end of options; the rest of the parameters are FILE
867 arguments, allowing filenames to begin with a `-' character.
868 Long options may start with `--no-' to disable, when applicable.
870 The regular expression pattern syntax is an extended form of the POSIX
872 ERE syntax. For an overview of the syntax see README.md or visit:
873 https://github.com/Genivia/ugrep
875 Note that `.' matches any non-newline character. Pattern `\n' matches
877 a newline character. Multiple lines may be matched with patterns that
878 match one or more newline characters.
879
881 The ugrep utility exits with one of the following values:
882 0 One or more lines were selected.
884 1 No lines were selected.
886 >1 An error occurred.
888 If -q or --quiet or --silent is used and a line is selected, the exit
890 status is 0 even if an error occurred.
891
893 The ug command is intended for context-dependent interactive searching
894 and is equivalent to the ugrep --config command to load the default
895 configuration file `.ugrep' when present in the working directory or in
896 the home directory.
897 A configuration file contains `NAME=VALUE' pairs per line, where `NAME`
899 is the name of a long option (without `--') and `=VALUE' is an argu‐
900 ment, which is optional and may be omitted depending on the option.
901 Empty lines and lines starting with a `#' are ignored.
902 The --config=FILE option and its abbreviated form ---FILE load the
904 specified configuration file located in the working directory or, when
905 not found, located in the home directory. An error is produced when
906 FILE is not found or cannot be read.
907 Command line options are parsed in the following order: the configura‐
909 tion file is loaded first, followed by the remaining options and argu‐
910 ments on the command line.
911 The --save-config option saves a `.ugrep' configuration file to the
913 working directory with a subset of the current options. The --save-
914 config=FILE option saves the configuration to FILE. The configuration
915 is written to standard output when FILE is a `-'.
916
918 Globbing is used by options -g, --include, --include-dir, --include-
919 from, --exclude, --exclude-dir, --exclude-from and --ignore-files to
920 match pathnames and basenames in recursive searches. Glob arguments
921 for these options should be quoted to prevent shell globbing.
922 Globbing supports gitignore syntax and the corresponding matching
924 rules, except that a glob normally matches files but not directories.
925 If a glob ends in a path separator `/', then it matches directories but
926 not files, as if --include-dir or --exclude-dir is specified. When a
927 glob contains a path separator `/', the full pathname is matched. Oth‐
928 erwise the basename of a file or directory is matched. For example,
929 *.h matches foo.h and bar/foo.h. bar/*.h matches bar/foo.h but not
930 foo.h and not bar/bar/foo.h. Use a leading `/' to force /*.h to match
931 foo.h but not bar/foo.h.
932 When a glob starts with a `^' or a `!' as in -g^GLOB, the match is
934 negated. Likewise, a `!' (but not a `^') may be used with globs in the
935 files specified --include-from, --exclude-from, and --ignore-files to
936 negate the glob match. Empty lines or lines starting with a `#' are
937 ignored.
938 Glob Syntax and Conventions
940 * Matches anything except /.
942 ? Matches any one character except /.
944 [abc-e]
946 Matches one character a,b,c,d,e.
947 [^abc-e]
949 Matches one character not a,b,c,d,e,/.
950 [!abc-e]
952 Matches one character not a,b,c,d,e,/.
953 / When used at the start of a glob, matches if pathname has no /.
955 When used at the end of a glob, matches directories only.
956 **/ Matches zero or more directories.
958 /** When used at the end of a glob, matches everything after the /.
960 \? Matches a ? or any other character specified after the back‐
962 slash.
963 Glob Matching Examples
965 * Matches a, b, x/a, x/y/b
967 a Matches a, x/a, x/y/a, but not b, x/b, a/a/b
969 /* Matches a, b, but not x/a, x/b, x/y/a
971 /a Matches a, but not x/a, x/y/a
973 a?b Matches axb, ayb, but not a, b, ab, a/b
975 a[xy]b Matches axb, ayb but not a, b, azb
977 a[a-z]b
979 Matches aab, abb, acb, azb, but not a, b, a3b, aAb, aZb
980 a[^xy]b
982 Matches aab, abb, acb, azb, but not a, b, axb, ayb
983 a[^a-z]b
985 Matches a3b, aAb, aZb but not a, b, aab, abb, acb, azb
986 a/*/b Matches a/x/b, a/y/b, but not a/b, a/x/y/b
988 **/a Matches a, x/a, x/y/a, but not b, x/b.
990 a/**/b Matches a/b, a/x/b, a/x/y/b, but not x/a/b, a/b/x
992 a/** Matches a/x, a/y, a/x/y, but not a, b/x
994 a\?b Matches a?b, but not a, b, ab, axb, a/b
996 Note that exclude glob patterns take priority over include glob pat‐
998 terns when specified with options -g, --exclude, --exclude-dir, --in‐
999 clude and include-dir.
1000 Glob patterns specified with prefix `!' in any of the files associated
1002 with --include-from, --exclude-from and --ignore-files will negate a
1003 previous glob match. That is, any matching file or directory excluded
1004 by a previous glob pattern specified in the files associated with --ex‐
1005 clude-from or --ignore-file will become included again. Likewise, any
1006 matching file or directory included by a previous glob pattern speci‐
1007 fied in the files associated with --include-from will become excluded
1008 again.
1009
1011 GREP_PATH
1012 May be used to specify a file path to pattern files. The file
1013 path is used by option -f to open a pattern file, when the pat‐
1014 tern file does not exist.
1015 GREP_COLOR
1017 May be used to specify ANSI SGR parameters to highlight matches
1018 when option --color is used, e.g. 1;35;40 shows pattern matches
1019 in bold magenta text on a black background. Deprecated in favor
1020 of GREP_COLORS, but still supported.
1021 GREP_COLORS
1023 May be used to specify ANSI SGR parameters to highlight matches
1024 and other attributes when option --color is used. Its value is
1025 a colon-separated list of ANSI SGR parameters that defaults to
1026 cx=33:mt=1;31:fn=1;35:ln=1;32:cn=1;32:bn=1;32:se=36. The mt=,
1027 ms=, and mc= capabilities of GREP_COLORS take priority over
1028 GREP_COLOR. Option --colors takes priority over GREP_COLORS.
1029
1031 Colors are specified as string of colon-separated ANSI SGR parameters
1032 of the form `what=substring', where `substring' is a semicolon-sepa‐
1033 rated list of ANSI SGR codes or `k' (black), `r' (red), `g' (green),
1034 `y' (yellow), `b' (blue), `m' (magenta), `c' (cyan), `w' (white). Up‐
1035 per case specifies background colors. A `+' qualifies a color as
1036 bright. A foreground and a background color may be combined with one
1037 or more font properties `n' (normal), `f' (faint), `h' (highlight), `i'
1038 (invert), `u' (underline). Substrings may be specified for:
1039 sl= SGR substring for selected lines.
1041 cx= SGR substring for context lines.
1043 rv Swaps the sl= and cx= capabilities when -v is specified.
1045 mt= SGR substring for matching text in any matching line.
1047 ms= SGR substring for matching text in a selected line. The sub‐
1049 string mt= by default.
1050 mc= SGR substring for matching text in a context line. The sub‐
1052 string mt= by default.
1053 fn= SGR substring for filenames.
1055 ln= SGR substring for line numbers.
1057 cn= SGR substring for column numbers.
1059 bn= SGR substring for byte offsets.
1061 se= SGR substring for separators.
1063 rv a Boolean parameter, switches sl= and cx= with option -v.
1065 hl a Boolean parameter, enables filename hyperlinks (\33]8;;link).
1067 ne a Boolean parameter, disables ``erase in line'' \33[K.
1069
1071 Option --format=FORMAT specifies an output format for file matches.
1072 Fields may be used in FORMAT, which expand into the following values:
1073 %[ARG]F
1075 if option -H is used: ARG, the file pathname and separator.
1076 %f the file pathname.
1078 %a the file basename without directory path.
1080 %p the directory path to the file.
1082 %z the file pathname in a (compressed) archive.
1084 %[ARG]H
1086 if option -H is used: ARG, the quoted pathname and separator, \"
1087 and \\ replace " and \.
1088 %h the quoted file pathname, \" and \\ replace " and \.
1090 %[ARG]N
1092 if option -n is used: ARG, the line number and separator.
1093 %n the line number of the match.
1095 %[ARG]K
1097 if option -k is used: ARG, the column number and separator.
1098 %k the column number of the match.
1100 %[ARG]B
1102 if option -b is used: ARG, the byte offset and separator.
1103 %b the byte offset of the match.
1105 %[ARG]T
1107 if option -T is used: ARG and a tab character.
1108 %t a tab character.
1110 %[SEP]$
1112 set field separator to SEP for the rest of the format fields.
1113 %[ARG]<
1115 if the first match: ARG.
1116 %[ARG]>
1118 if not the first match: ARG.
1119 %, if not the first match: a comma, same as %[,]>.
1121 %: if not the first match: a colon, same as %[:]>.
1123 %; if not the first match: a semicolon, same as %[;]>.
1125 %| if not the first match: a vertical bar, same as %[|]>.
1127 %[ARG]S
1129 if not the first match: ARG and separator, see also %[SEP]$.
1130 %s the separator, see also %[ARG]S and %[SEP]$.
1132 %~ a newline character.
1134 %M the number of matching lines
1136 %m the number of matches
1138 %O the matching line is output as a raw string of bytes.
1140 %o the match is output as a raw string of bytes.
1142 %Q the matching line as a quoted string, \" and \\ replace " and \.
1144 %q the match as a quoted string, \" and \\ replace " and \.
1146 %C the matching line formatted as a quoted C/C++ string.
1148 %c the match formatted as a quoted C/C++ string.
1150 %J the matching line formatted as a quoted JSON string.
1152 %j the match formatted as a quoted JSON string.
1154 %V the matching line formatted as a quoted CSV string.
1156 %v the match formatted as a quoted CSV string.
1158 %X the matching line formatted as XML character data.
1160 %x the match formatted as XML character data.
1162 %w the width of the match, counting wide characters.
1164 %d the size of the match, counting bytes.
1166 %e the ending byte offset of the match.
1168 %Z the edit distance cost of an approximate match with option -Z
1170 %u select unique lines only, unless option -u is used.
1172 %1 the first regex group capture of the match, and so on up to
1174 group %9, same as %[1]#; requires option -P.
1175 %[NUM]#
1177 the regex group capture NUM; requires option -P.
1178 %[NUM]b
1180 the byte offset of the group capture NUM; requires option -P.
1181 Use e for the ending byte offset and d for the byte length.
1182 %[NUM1|NUM2|...]#
1184 the first group capture NUM that matched; requires option -P.
1185 %[NUM1|NUM2|...]b
1187 the byte offset of the first group capture NUM that matched; re‐
1188 quires option -P. Use e for the ending byte offset and d for
1189 the byte length.
1190 %[NAME]#
1192 the NAMEd group capture; requires option -P and capturing pat‐
1193 tern `(?<NAME>PATTERN)', see also %G.
1194 %[NAME]b
1196 the byte offset of the NAMEd group capture; requires option -P
1197 and capturing pattern `(?<NAME>PATTERN)'. Use e for the ending
1198 byte offset and d for the byte length.
1199 %[NAME1|NAME2|...]#
1201 the first NAMEd group capture that matched; requires option -P
1202 and capturing pattern `(?<NAME>PATTERN)', see also %G.
1203 %[NAME1|NAME2|...]b
1205 the byte offset of the first NAMEd group capture that matched;
1206 requires option -P and capturing pattern `(?<NAME>PATTERN)'.
1207 Use e for the ending byte offset and d for the byte length.
1208 %G list of group capture indices/names that matched; requires op‐
1210 tion -P.
1211 %[TEXT1|TEXT2|...]G
1213 list of TEXT indexed by group capture indices that matched; re‐
1214 quires option -P.
1215 %g the group capture index/name matched or 1; requires option -P.
1217 %[TEXT1|TEXT2|...]g
1219 the first TEXT indexed by the first group capture index that
1220 matched; requires option -P.
1221 %% the percentage sign.
1223 Formatted output is written without a terminating newline, unless %~ or
1225 `\n' is explicitly specified in the format string.
1226 The [ARG] part of a field is optional and may be omitted. When
1228 present, the argument must be placed in [] brackets, for example %[,]F
1229 to output a comma, the pathname, and a separator.
1230 %[SEP]$ and %u are switches and do not send anything to the output.
1232 The separator used by the %F, %H, %N, %K, %B, %S and %G fields may be
1234 changed by preceding the field by %[SEP]$. When [SEP] is not provided,
1235 this reverts the separator to the default separator or the separator
1236 specified with --separator.
1237 Formatted output is written for each matching pattern, which means that
1239 a line may be output multiple times when patterns match more than once
1240 on the same line. If field %u is specified anywhere in a format
1241 string, matching lines are output only once, unless option -u, --un‐
1242 group is specified or when more than one line of input matched the
1243 search pattern.
1244 Additional formatting options:
1246 --format-begin=FORMAT
1248 the FORMAT when beginning the search.
1249 --format-open=FORMAT
1251 the FORMAT when opening a file and a match was found.
1252 --format-close=FORMAT
1254 the FORMAT when closing a file and a match was found.
1255 --format-end=FORMAT
1257 the FORMAT when ending the search.
1258 The context options -A, -B, -C, -y, and display options --break,
1260 --heading, --color, -T, and --null have no effect on formatted output.
1261
1263 Display lines containing the word `patricia' in `myfile.txt':
1264 $ ugrep -w patricia myfile.txt
1266 Display lines containing the word `patricia', ignoring case:
1268 $ ugrep -wi patricia myfile.txt
1270 Display lines approximately matching the word `patricia', ignoring case
1272 and allowing up to 2 spelling errors using fuzzy search:
1273 $ ugrep -Z2 -wi patricia myfile.txt
1275 Count the number of lines containing `patricia', ignoring case:
1277 $ ugrep -cwi patricia myfile.txt
1279 Count the number of words `patricia', ignoring case:
1281 $ ugrep -cowi patricia myfile.txt
1283 List lines with `amount' and a decimal, ignoring case (space is AND):
1285 $ ugrep -i --bool 'amount +(.+)?' myfile.txt
1287 Alternative query:
1289 $ ugrep -wi -e amount --and '+(.+)?' myfile.txt
1291 List all Unicode words in a file:
1293 $ ugrep -o '\w+' myfile.txt
1295 List all ASCII words in a file:
1297 $ ugrep -o '[[:word:]]+' myfile.txt
1299 List the laughing face emojis (Unicode code points U+1F600 to U+1F60F):
1301 $ ugrep -o '[\x{1F600}-\x{1F60F}]' myfile.txt
1303 Check if a file contains any non-ASCII (i.e. Unicode) characters:
1305 $ ugrep -q '[^[:ascii:]]' myfile.txt && echo "contains Unicode"
1307 Display the line and column number of `FIXME' in C++ files using recur‐
1309 sive search, with one line of context before and after a matched line:
1310 $ ugrep -C1 -R -n -k -tc++ FIXME
1312 Display the line and column number of `FIXME' in long Javascript files
1314 using recursive search, showing only matches with up to 10 characters
1315 of context before and after:
1316 $ ugrep -o -C20 -R -n -k -tjs FIXME
1318 List the C/C++ comments in a file with line numbers:
1320 $ ugrep -n -e '//.*' -e '/\*([^*]|(\*+[^*/]))*\*+\/' myfile.cpp
1322 The same, but using predefined pattern c++/comments:
1324 $ ugrep -n -f c++/comments myfile.cpp
1326 List the lines that need fixing in a C/C++ source file by looking for
1328 the word `FIXME' while skipping any `FIXME' in quoted strings:
1329 $ ugrep -e FIXME -N '"(\\.|\\\r?\n|[^\\\n"])*"' myfile.cpp
1331 The same, but using predefined pattern cpp/zap_strings:
1333 $ ugrep -e FIXME -f cpp/zap_strings myfile.cpp
1335 Find lines with `FIXME' or `TODO', showing line numberes:
1337 $ ugrep -n -e FIXME -e TODO myfile.cpp
1339 Find lines with `FIXME' that also contain `urgent':
1341 $ ugrep -n -e FIXME --and urgent myfile.cpp
1343 The same, but with a Boolean query pattern (a space is AND):
1345 $ ugrep -n --bool 'FIXME urgent' myfile.cpp
1347 Find lines with `FIXME' that do not also contain `later':
1349 $ ugrep -n -e FIXME --andnot later myfile.cpp
1351 The same, but with a Boolean query pattern (a space is AND, - is NOT):
1353 $ ugrep -n --bool 'FIXME -later' myfile.cpp
1355 Output a list of line numbers of lines with `FIXME' but not `later':
1357 $ ugrep -e FIXME --andnot later --format='%,%n' myfile.cpp
1359 Recursively list all files with both `FIXME' and `LICENSE' anywhere in
1361 the file, not necessarily on the same line:
1362 $ ugrep -l --files --bool 'FIXME LICENSE'
1364 Find lines with `FIXME' in the C/C++ files stored in a tarball:
1366 $ ugrep -z -tc++ -n FIXME project.tgz
1368 Recursively find lines with `FIXME' in C/C++ files, but do not search
1370 any `bak' and `old' directories:
1371 $ ugrep -n FIXME -tc++ -g^bak/,^old/
1373 Recursively search for the word `copyright' in cpio/jar/pax/tar/zip ar‐
1375 chives, compressed and regular files, and in PDFs using a PDF filter:
1376 $ ugrep -z -w --filter='pdf:pdftotext % -' copyright
1378 Match the binary pattern `A3hhhhA3' (hex) in a binary file without Uni‐
1380 code pattern matching -U (which would otherwise match `\xaf' as a Uni‐
1381 code character U+00A3 with UTF-8 byte sequence C2 A3) and display the
1382 results in hex with --hexdump with C1 to output one hex line before and
1383 after each match:
1384 $ ugrep -U --hexdump=C1 '\xa3[\x00-\xff]{2}\xa3' a.out
1386 Hexdump an entire file using a pager for viewing:
1388 $ ugrep -X --pager '' a.out
1390 List all files that are not ignored by one or more `.gitignore':
1392 $ ugrep -l '' --ignore-files
1394 List all files containing a RPM signature, located in the `rpm' direc‐
1396 tory and recursively below up to two levels deeper (3 levels total):
1397 $ ugrep -3 -l -tRpm '' rpm/
1399 Monitor the system log for bug reports and ungroup multiple matches on
1401 a line:
1402 $ tail -f /var/log/system.log | ugrep -u -i -w bug
1404 Interactive fuzzy search with Boolean search queries:
1406 $ ugrep -Q --bool -Z3 --sort=best
1408 Display all words in a MacRoman-encoded file that has CR newlines:
1410 $ ugrep --encoding=MACROMAN '\w+' mac.txt
1412 Display options related to "fuzzy" searching:
1414 $ ugrep --help fuzzy
1416
1418 Report bugs at:
1419 https://github.com/Genivia/ugrep/issues
1421
1423 ugrep is released under the BSD-3 license. All parts of the software
1424 have reasonable copyright terms permitting free redistribution. This
1425 includes the ability to reuse all or parts of the ugrep source tree.
1426
1428 grep(1).
1429ugrep 3.11.2 April 07, 2023 UGREP(1)