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 shortening the match. See also op‐
67 tions -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 shortening 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.
142 -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 -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 --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 --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 --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 --confirm
185 Confirm actions in -Q query mode. The default is confirm.
186 --cpp Output file matches in C++. See also options --format and -u.
188 --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 -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 -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 --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 --dotall
217 Dot `.' in regular expressions matches anything, including new‐
218 line. Note that `.*' matches all input and should not be used.
219 -E, --extended-regexp
221 Interpret patterns as extended regular expressions (EREs). This
222 is the default.
223 -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 --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 --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 --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 --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 --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 -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 -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 --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 --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 --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 --free-space
337 Spacing (blanks and tabs) in regular expressions are ignored.
338 -G, --basic-regexp
340 Interpret patterns as basic regular expressions (BREs), i.e.
341 make ugrep behave as traditional grep.
342 -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 --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 -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 -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 --heading, -+
369 Group matches per file. Adds a heading and a line break between
370 results from different files.
371 --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 --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 --hidden, -.
391 Search hidden files and directories.
392 --hyperlink
394 Hyperlinks are enabled for file names when colors are enabled.
395 Same as --colors=hl.
396 -I, --ignore-binary
398 Ignore matches in binary files. This option is equivalent to
399 the --binary-files=without-match option.
400 -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 --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 --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 --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 --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 --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 -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 -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 --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 -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 -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 -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 -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 --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 --line-buffered
503 Force output to be line buffered instead of block buffered.
504 --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 -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 -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 --match
526 Match all input. Same as specifying an empty pattern to search.
527 --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 --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 -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 -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 --no-group-separator
554 Removes the group separator line from the output for context op‐
555 tions -A, -B and -C.
556 --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 -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 -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 --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 --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 -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 -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 --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 --pretty
611 When output is sent to a terminal, enables --color, --heading,
612 -n, --sort and -T when not explicitly disabled.
613 -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 -q, --quiet, --silent
634 Quiet mode: suppress all output. ugrep will only search until a
635 match has been found.
636 -R, --dereference-recursive
638 Recursively read all files under each directory. Follow all
639 symbolic links, unlike -r. See also option --sort.
640 -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 --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 -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 -s, --no-messages
661 Silent mode: nonexistent and unreadable files are ignored, i.e.
662 their error messages and warnings are suppressed.
663 --save-config[=FILE]
665 Save configuration FILE. By default `.ugrep' is saved. If FILE
666 is a `-', write the configuration to standard output.
667 --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 --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 --stats
689 Output statistics on the number of files and directories
690 searched and the inclusion and exclusion constraints applied.
691 -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 -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 --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 --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 -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 -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 -V, --version
741 Display version with linked libraries and exit.
742 -v, --invert-match
744 Selected lines are those not matching any of the specified pat‐
745 terns.
746 --view[=COMMAND]
748 Use COMMAND to view/edit a file in query mode when pressing
749 CTRL-Y.
750 -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 -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 --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 -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 -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 --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 -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 -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 -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 -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 --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 -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 A `--' signals the end of options; the rest of the parameters are FILE
850 arguments, allowing filenames to begin with a `-' character.
851 Long options may start with `--no-' to disable, when applicable.
853 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 https://github.com/Genivia/ugrep
858 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 0 One or more lines were selected.
867 1 No lines were selected.
869 >1 An error occurred.
871 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 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 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 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 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 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 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 Glob Syntax and Conventions
923 * Matches anything except /.
925 ? Matches any one character except /.
927 [abc-e]
929 Matches one character a,b,c,d,e.
930 [^abc-e]
932 Matches one character not a,b,c,d,e,/.
933 [!abc-e]
935 Matches one character not a,b,c,d,e,/.
936 / 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 **/ Matches zero or more directories.
941 /** When used at the end of a glob, matches everything after the /.
943 \? Matches a ? or any other character specified after the back‐
945 slash.
946 Glob Matching Examples
948 * Matches a, b, x/a, x/y/b
950 a Matches a, x/a, x/y/a, but not b, x/b, a/a/b
952 /* Matches a, b, but not x/a, x/b, x/y/a
954 /a Matches a, but not x/a, x/y/a
956 a?b Matches axb, ayb, but not a, b, ab, a/b
958 a[xy]b Matches axb, ayb but not a, b, azb
960 a[a-z]b
962 Matches aab, abb, acb, azb, but not a, b, a3b, aAb, aZb
963 a[^xy]b
965 Matches aab, abb, acb, azb, but not a, b, axb, ayb
966 a[^a-z]b
968 Matches a3b, aAb, aZb but not a, b, aab, abb, acb, azb
969 a/*/b Matches a/x/b, a/y/b, but not a/b, a/x/y/b
971 **/a Matches a, x/a, x/y/a, but not b, x/b.
973 a/**/b Matches a/b, a/x/b, a/x/y/b, but not x/a/b, a/b/x
975 a/** Matches a/x, a/y, a/x/y, but not a, b/x
977 a\?b Matches a?b, but not a, b, ab, axb, a/b
979 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 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 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 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 sl= SGR substring for selected lines.
1024 cx= SGR substring for context lines.
1026 rv Swaps the sl= and cx= capabilities when -v is specified.
1028 mt= SGR substring for matching text in any matching line.
1030 ms= SGR substring for matching text in a selected line. The sub‐
1032 string mt= by default.
1033 mc= SGR substring for matching text in a context line. The sub‐
1035 string mt= by default.
1036 fn= SGR substring for filenames.
1038 ln= SGR substring for line numbers.
1040 cn= SGR substring for column numbers.
1042 bn= SGR substring for byte offsets.
1044 se= SGR substring for separators.
1046 rv a Boolean parameter, switches sl= and cx= with option -v.
1048 hl a Boolean parameter, enables filename hyperlinks (\33]8;;link).
1050 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 %[ARG]F
1058 if option -H is used: ARG, the file pathname and separator.
1059 %f the file pathname.
1061 %a the file basename without directory path.
1063 %p the directory path to the file.
1065 %z the file pathname in a (compressed) archive.
1067 %[ARG]H
1069 if option -H is used: ARG, the quoted pathname and separator, \"
1070 and \\ replace " and \.
1071 %h the quoted file pathname, \" and \\ replace " and \.
1073 %[ARG]N
1075 if option -n is used: ARG, the line number and separator.
1076 %n the line number of the match.
1078 %[ARG]K
1080 if option -k is used: ARG, the column number and separator.
1081 %k the column number of the match.
1083 %[ARG]B
1085 if option -b is used: ARG, the byte offset and separator.
1086 %b the byte offset of the match.
1088 %[ARG]T
1090 if option -T is used: ARG and a tab character.
1091 %t a tab character.
1093 %[SEP]$
1095 set field separator to SEP for the rest of the format fields.
1096 %[ARG]<
1098 if the first match: ARG.
1099 %[ARG]>
1101 if not the first match: ARG.
1102 %, if not the first match: a comma, same as %[,]>.
1104 %: if not the first match: a colon, same as %[:]>.
1106 %; if not the first match: a semicolon, same as %[;]>.
1108 %| if not the first match: a vertical bar, same as %[|]>.
1110 %[ARG]S
1112 if not the first match: ARG and separator, see also %[SEP]$.
1113 %s the separator, see also %[ARG]S and %[SEP]$.
1115 %~ a newline character.
1117 %m the number of matches or matched files.
1119 %O the matching line is output as a raw string of bytes.
1121 %o the match is output as a raw string of bytes.
1123 %Q the matching line as a quoted string, \" and \\ replace " and \.
1125 %q the match as a quoted string, \" and \\ replace " and \.
1127 %C the matching line formatted as a quoted C/C++ string.
1129 %c the match formatted as a quoted C/C++ string.
1131 %J the matching line formatted as a quoted JSON string.
1133 %j the match formatted as a quoted JSON string.
1135 %V the matching line formatted as a quoted CSV string.
1137 %v the match formatted as a quoted CSV string.
1139 %X the matching line formatted as XML character data.
1141 %x the match formatted as XML character data.
1143 %w the width of the match, counting wide characters.
1145 %d the size of the match, counting bytes.
1147 %e the ending byte offset of the match.
1149 %Z the edit distance cost of an approximate match with option -Z
1151 %u select unique lines only, unless option -u is used.
1153 %1 the first regex group capture of the match, and so on up to
1155 group %9, same as %[1]#; requires option -P.
1156 %[NUM]#
1158 the regex group capture NUM; requires option -P.
1159 %[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 %[NUM1|NUM2|...]#
1165 the first group capture NUM that matched; requires option -P.
1166 %[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 %[NAME]#
1173 the NAMEd group capture; requires option -P and capturing pat‐
1174 tern `(?<NAME>PATTERN)', see also %G.
1175 %[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 %[NAME1|NAME2|...]#
1182 the first NAMEd group capture that matched; requires option -P
1183 and capturing pattern `(?<NAME>PATTERN)', see also %G.
1184 %[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 %G list of group capture indices/names that matched; requires op‐
1191 tion -P.
1192 %[TEXT1|TEXT2|...]G
1194 list of TEXT indexed by group capture indices that matched; re‐
1195 quires option -P.
1196 %g the group capture index/name matched or 1; requires option -P.
1198 %[TEXT1|TEXT2|...]g
1200 the first TEXT indexed by the first group capture index that
1201 matched; requires option -P.
1202 %% the percentage sign.
1204 Formatted output is written without a terminating newline, unless %~ or
1206 `\n' is explicitly specified in the format string.
1207 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 %[SEP]$ and %u are switches and do not send anything to the output.
1213 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 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 Additional formatting options:
1227 --format-begin=FORMAT
1229 the FORMAT when beginning the search.
1230 --format-open=FORMAT
1232 the FORMAT when opening a file and a match was found.
1233 --format-close=FORMAT
1235 the FORMAT when closing a file and a match was found.
1236 --format-end=FORMAT
1238 the FORMAT when ending the search.
1239 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 $ ugrep -w patricia myfile.txt
1247 Display lines containing the word `patricia', ignoring case:
1249 $ ugrep -wi patricia myfile.txt
1251 Display lines approximately matching the word `patricia', ignoring case
1253 and allowing up to 2 spelling errors using fuzzy search:
1254 $ ugrep -Z2 -wi patricia myfile.txt
1256 Count the number of lines containing `patricia', ignoring case:
1258 $ ugrep -cwi patricia myfile.txt
1260 Count the number of words `patricia', ignoring case:
1262 $ ugrep -cowi patricia myfile.txt
1264 List lines with `amount' and a decimal, ignoring case (space is AND):
1266 $ ugrep -i --bool 'amount +(.+)?' myfile.txt
1268 Alternative query:
1270 $ ugrep -wi -e amount --and '+(.+)?' myfile.txt
1272 List all Unicode words in a file:
1274 $ ugrep -o '\w+' myfile.txt
1276 List all ASCII words in a file:
1278 $ ugrep -o '[[:word:]]+' myfile.txt
1280 List the laughing face emojis (Unicode code points U+1F600 to U+1F60F):
1282 $ ugrep -o '[\x{1F600}-\x{1F60F}]' myfile.txt
1284 Check if a file contains any non-ASCII (i.e. Unicode) characters:
1286 $ ugrep -q '[^[:ascii:]]' myfile.txt && echo "contains Unicode"
1288 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 $ ugrep -C1 -R -n -k -tc++ FIXME
1293 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 $ ugrep -o -C20 -R -n -k -tjs FIXME
1299 List the C/C++ comments in a file with line numbers:
1301 $ ugrep -n -e '//.*' -e '/\*([^*]|(\*+[^*/]))*\*+\/' myfile.cpp
1303 The same, but using predefined pattern c++/comments:
1305 $ ugrep -n -f c++/comments myfile.cpp
1307 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 $ ugrep -e FIXME -N '"(\\.|\\\r?\n|[^\\\n"])*"' myfile.cpp
1312 The same, but using predefined pattern cpp/zap_strings:
1314 $ ugrep -e FIXME -f cpp/zap_strings myfile.cpp
1316 Find lines with `FIXME' or `TODO', showing line numberes:
1318 $ ugrep -n -e FIXME -e TODO myfile.cpp
1320 Find lines with `FIXME' that also contain `urgent':
1322 $ ugrep -n -e FIXME --and urgent myfile.cpp
1324 The same, but with a Boolean query pattern (a space is AND):
1326 $ ugrep -n --bool 'FIXME urgent' myfile.cpp
1328 Find lines with `FIXME' that do not also contain `later':
1330 $ ugrep -n -e FIXME --andnot later myfile.cpp
1332 The same, but with a Boolean query pattern (a space is AND, - is NOT):
1334 $ ugrep -n --bool 'FIXME -later' myfile.cpp
1336 Output a list of line numbers of lines with `FIXME' but not `later':
1338 $ ugrep -e FIXME --andnot later --format='%,%n' myfile.cpp
1340 Recursively list all files with both `FIXME' and `LICENSE' anywhere in
1342 the file, not necessarily on the same line:
1343 $ ugrep -l --files --bool 'FIXME LICENSE'
1345 Find lines with `FIXME' in the C/C++ files stored in a tarball:
1347 $ ugrep -z -tc++ -n FIXME project.tgz
1349 Recursively find lines with `FIXME' in C/C++ files, but do not search
1351 any `bak' and `old' directories:
1352 $ ugrep -n FIXME -tc++ -g^bak/,^old/
1354 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 $ ugrep -z -w --filter='pdf:pdftotext % -' copyright
1359 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 $ ugrep -U --hexdump=C1 '\xa3[\x00-\xff]{2}\xa3' a.out
1367 Hexdump an entire file using a pager for viewing:
1369 $ ugrep -X --pager '' a.out
1371 List all files that are not ignored by one or more `.gitignore':
1373 $ ugrep -l '' --ignore-files
1375 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 $ ugrep -3 -l -tRpm '' rpm/
1380 Monitor the system log for bug reports and ungroup multiple matches on
1382 a line:
1383 $ tail -f /var/log/system.log | ugrep -u -i -w bug
1385 Interactive fuzzy search with Boolean search queries:
1387 $ ugrep -Q --bool -Z3 --sort=best
1389 Display all words in a MacRoman-encoded file that has CR newlines:
1391 $ ugrep --encoding=MACROMAN '\w+' mac.txt
1393 Display options related to "fuzzy" searching:
1395 $ ugrep --help fuzzy
1397
1399 Report bugs at:
1400 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).
1410ugrep 3.9.0 August 12, 2022 UGREP(1)