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