UGREP(1)

📦
version 7.8.5 · 8 versions
, in arch rolling, nixpkgs unstable

UGREP(1) — User Commands 💅

🌸 NAME 🌸

ugrep, ug — file pattern searcher 💖

✨ SYNOPSIS ✨

ugrep [OPTIONS] [-i|-j] [-Q|PATTERN] [-e PATTERN] [-N PATTERN] [-f FILE]
      [-E|-F|-G|-P|-Z] [-U] [-m [MIN,][MAX]] [--bool [--files|--lines]]
      [-r|-R|-1|...|-9|-10|-11|...] [-t TYPES] [-g GLOBS] [--sort[=KEY]]
      [-q|-l|-c|-o] [-v] [-n] [-k] [-b] [-A NUM] [-B NUM] [-C NUM] [-y]
      [--color[=WHEN]|--colour[=WHEN]] [--pretty] [--pager[=COMMAND]]
      [--hexdump|--csv|--json|--xml] [-I] [-z] [--zmax=NUM] [FILE ...]

🦋 DESCRIPTION 🦋

Okay so ugrep is out here searching any input files you give it, picking out the files and lines that match one or more patterns — and those patterns can be regular expressions or fixed strings. A pattern can match multiple input lines when the pattern’s regular expression matches one or more newlines. An empty pattern matches every line. Every input line that matches at least one of the patterns gets written to standard output. Slay. ✨

The ug command is the interactive-search version, using a .ugrep configuration file in the working directory or, if it’s not found there, in the home directory — see CONFIGURATION. ug is equivalent to ugrep --config --pretty --sort so it loads a configuration file, enhances the terminal output, and sorts files by name.

The ugrep+ and ug+ commands are the same as the ugrep and ug commands, but they also use filters to search pdfs, documents, e-books, and image metadata when the corresponding filter tools are installed. Iconic behavior, honestly. 👑

A list of matching files is produced with option -l (--files-with-matches). Option -c (--count) counts the number of matching lines. When combined with option -o, it counts the total number of matches. When combined with option -m1 (--min-count=1), it skips files with zero matches. No notes. 💅

The default pattern syntax is an extended form of the POSIX ERE syntax, same as option -E (--extended-regexp). Try ug --help regex for help with pattern syntax and how to use logical connectives to specify Boolean search queries with option -% (--bool) to match lines and -%% (--bool --files) to match files. Options -F (--fixed-strings), -G (--basic-regexp) and -P (--perl-regexp) specify other pattern syntaxes. We love options. We contain multitudes. 🌈

Option -i (--ignore-case) ignores letter case in patterns. Option -j (--smart-case) enables -i only if the search patterns are specified in lower case.

Fuzzy (approximate) search is specified with option -Z (--fuzzy) with an optional argument to control character insertions, deletions, and/or substitutions. Try ug --help fuzzy for help with fuzzy search. Lowkey magical. 🧚

Note that pattern . matches any non-newline character. Pattern \n matches a newline character. Multiple lines may be matched with patterns that match one or more newline characters.

The empty pattern "" matches all lines. Other empty-matching patterns do not. For example, the pattern a* will match one or more a’s. Option -Y forces empty matches for compatibility with other grep tools.

Option -f FILE matches patterns specified in FILE.

By default Unicode patterns are matched. Option -U (--ascii or --binary) disables Unicode matching for ASCII and binary pattern matching. Non-Unicode matching is more efficient. Efficient queen behavior. ⚡

ugrep accepts input of various encoding formats and normalizes the output to UTF-8. When a UTF byte order mark is present in the input, the input is automatically normalized. An input encoding format may be specified with option --encoding.

If no FILE arguments are specified and standard input is read from a terminal, recursive searches are performed as if -r is specified. To force reading from standard input, specify - as a FILE argument.

Directories specified as FILE arguments are searched without recursing deeper into subdirectories, unless -R, -r, or -2...-9 is specified to search subdirectories recursively (up to the specified depth.)

Option -I (--ignore-binary) ignores binary files. A binary file is a file with non-text content. A file with zero bytes or invalid UTF formatting is considered binary.

Hidden files and directories are ignored in recursive searches. Option -. (--hidden) includes hidden files and directories in recursive searches.

To match the names of files to search and the names of directories to recurse, one or more of the following options may be specified. Option -O specifies one or more filename extensions to match. Option -t specifies one or more file types to search (-t list outputs a list of types.) Option -g specifies a gitignore-style glob pattern to match filenames. Option --ignore-files specifies a file with gitignore-style globs to ignore directories and files. Try ug --help globs for help with filename and directory name matching. See also section GLOBBING.

Compressed files and archives are searched with option -z (--decompress). When used with option --zmax=NUM, searches the contents of compressed files and archives stored within archives up to NUM levels. Unzipping the mysteries of the universe, honestly. 🎀

Output to a terminal for viewing is enhanced with --pretty, which is enabled by default with the ug command.

A query terminal user interface (TUI) is opened with -Q (--query) to interactively specify search patterns and view search results. A PATTERN argument requires -e PATTERN to start the query TUI with the specified pattern.

A terminal output pager is enabled with --pager that accepts an optional COMMAND to view the output.

Customized output is produced with option --format or --replace. Try ug --help format for help with custom formatting of the output. See also section FORMAT. Predefined formats include CSV with option --csv, JSON with option --json, and XML with option --xml. Hexdumps are output with option -X (--hex) or with option --hexdump to customize hexdumps.

A -- signals the end of options; the rest of the parameters are FILE arguments, allowing filenames to begin with a - character.

Long options may start with --no- to disable, when applicable.

ug --help WHAT displays help on options related to WHAT.

💅 The following options are available: 💅

  • -A NUM, --after-context=NUM — Outputs NUM lines of trailing context after matching lines. It places a --group-separator between contiguous groups of matches. If -o is specified, it outputs the match with context to fit NUM columns after the match or shortens the match. See also options -B, -C and -y. Trailing context bestie.
  • -a, --text — Processes a binary file as if it were text. This is equivalent to the --binary-files=text option. This option might output binary garbage to the terminal, which can have problematic consequences if the terminal driver interprets some of it as terminal commands. Be careful with that one, fr fr.
  • --all, -@ — Searches all files except hidden files: it cancels previous file and directory search restrictions and cancels --ignore-binary and --ignore-files when specified. Restrictions specified after this option, i.e. to the right, are still applied. For example, -@I searches all non-binary files and -@. searches all files including hidden files. Note that hidden files and directories are never searched, unless option -. or --hidden is specified. We love a cleanup moment.
  • --and [-e] PATTERN — Specifies additional PATTERN that must match. Additional -e PATTERN following this option is considered an alternative pattern to match, i.e. each -e is interpreted as an OR pattern enclosed within the AND. For example, -e A -e B --and -e C -e D matches lines with (A or B) and (C or D). Note that multiple -e PATTERN are alternations that bind more tightly together than --and. Option --stats displays the search patterns applied. See also options --not, --andnot, --bool, --files and --lines. Boolean drama, but make it useful.
  • --andnot [-e] PATTERN — Combines --and --not. See also options --and, --not and --bool.
  • -B NUM, --before-context=NUM — Outputs NUM lines of leading context before matching lines. It places a --group-separator between contiguous groups of matches. If -o is specified, it outputs the match with context to fit NUM columns before the match or shortens the match. See also options -A, -C and -y. Leading context, coming through.
  • -b, --byte-offset — The offset in bytes of a pattern match is displayed in front of the respective matched line. When -u or --ungroup is specified, it displays the offset for each pattern matched on the same line. Byte offsets are exact for ASCII, UTF-8 and raw binary input. Otherwise, the offset in the UTF-8-normalized input is displayed.
  • --binary-files=TYPE — Controls searching and reporting pattern matches in binary files. TYPE can be binary, without-match, text, hex and with-hex. The default is binary to search binary files and to report a match without displaying the match. without-match ignores binary matches. text treats all binary files as text, which might output binary garbage to the terminal, which can have problematic consequences if the terminal driver interprets some of it as commands. hex reports all matches in hexadecimal. with-hex only reports binary matches in hexadecimal, leaving text matches alone. Files having NUL (zero) bytes are binary and files with invalid UTF encoding are binary unless option -U or --ascii or --binary is specified. Short options are -a, -I, -W, -X. That’s the binary-files breakdown, periodt.
  • --bool, -%, -%% — okay bestie, this is the Boolean query era 💅. A Boolean query pattern is built out of AND, OR, NOT operators plus grouping with ( and ). Spacing between subpatterns does the same job as AND, a | does the same job as OR, and a - does the same job as NOT. Heads up: the OR operator binds more tightly than AND. So --bool 'A|B C|D' matches lines with (A or B) and (C or D), and --bool 'A -B' matches lines with A and not B. The operators AND, OR, NOT need proper spacing — like, actual spaces, she's not flexible about this. For example, --bool 'A OR B AND C OR D' matches lines with (A or B) and (C or D), and --bool 'A AND NOT B' matches lines with A without B. Quoted subpatterns get matched literally as strings — so --bool 'A "AND"|"OR"' matches lines with A and also either AND or OR. Parentheses are for grouping: --bool '(A B)|C' matches lines with A and B, or lines with C. Note that all subpatterns in a Boolean query pattern are regular expressions, unless -F is specified. Options -E, -F, -G, -P and -Z can be combined with --bool to match subpatterns as strings or regular expressions (-E is the default). This option does not apply to -f FILE patterns. The double short option -%% enables options --bool --files. Option --stats displays the Boolean search patterns applied. See also options --and, --andnot, --not, --files and --lines.
  • --break — adds a line break between results from different files 🎀. This option is enabled by --heading.
  • -C NUM, --context=NUM — outputs NUM lines of leading and trailing context surrounding each matching line. Drops a --group-separator between contiguous groups of matches. If -o is specified, it outputs the match with context to fit NUM columns before and after the match, or shortens the match. See also options -A, -B and -y.
  • -c, --count — only a count of selected lines gets written to standard output ✨. When -o or -u is specified, it counts the number of patterns matched. When -v is specified, it counts the number of non-matching lines. When -m1, (with a comma, or --min-count=1) is specified, it counts only matching files without outputting zero matches.
  • --color[=WHEN], --colour[=WHEN] — marks up the matching text with the colors specified with option --colors or the GREP_COLOR or GREP_COLORS environment variable 🌈. WHEN can be never, always, or auto, where auto marks up matches only when output on a terminal. The default is auto.
  • --colors=COLORS, --colours=COLORS — uses COLORS to mark up text 🎨. COLORS is a colon-separated list of one or more parameters: sl= (selected line), cx= (context line), mt= (matched text), ms= (match selected), mc= (match context), fn= (file name), ln= (line number), cn= (column number), bn= (byte offset), se= (separator), qp= (TUI prompt), qe= (TUI errors), qr= (TUI regex), qm= (TUI regex meta characters), ql= (TUI regex lists and literals), qb= (TUI regex braces). Parameter values are ANSI SGR color codes, or k (black), r (red), g (green), y (yellow), b (blue), m (magenta), c (cyan), w (white), or leave it empty for no color. Upper case specifies background colors. A + qualifies a color as bright. A foreground and a background color may be combined with font properties n (normal), f (faint), h (highlight), i (invert), u (underline). Parameter hl enables file name hyperlinks. Parameter rv reverses the sl= and cx= parameters when option -v is specified. Selectively overrides GREP_COLORS. Legacy grep single parameter codes may be specified, for example --colors='7;32' or --colors=ig to set ms (match selected). iconic, honestly.
  • --config[=FILE], ---[FILE] — use configuration FILE 🗂️. The default FILE is .ugrep. The working directory is checked first for FILE, then the home directory. The options specified in the configuration FILE are parsed first, followed by the remaining options specified on the command line. The ug command automatically loads a .ugrep configuration file when present, unless --config=FILE or --no-config is specified.
  • --no-config — do not automatically load the default .ugrep configuration file 🙅‍♀️.
  • --no-confirm — do not confirm actions in -Q query TUI. The default is confirm.
  • --cpp — output file matches in C++ 💻. See also options --format and -u.
  • --csv — output file matches in CSV 📊. When -H, -n, -k, or -b is specified, additional values are output. See also options --format and -u.
  • -D ACTION, --devices=ACTION — if an input file is a device, FIFO or socket, use ACTION to process it 🔌. When ACTION is skip, devices are ignored. When ACTION is read, devices are read just as if they were ordinary files. The default ACTION is skip, except for devices specified as arguments on the command line, which can be explicitly skipped with -Dskip.
  • -d ACTION, --directories=ACTION — if an input file is a directory, use ACTION to process it 📁. When ACTION is read, warn when directories are read as input. When ACTION is recurse, read all files under each directory, recursively, following symbolic links only if they are on the command line — this is equivalent to the -r option. When ACTION is dereference-recurse, read all files under each directory, recursively, following symbolic links — this is equivalent to the -R option. When no files or directories are specified on the command line, ACTION defaults to recurse or option -r.
  • --delay=DELAY — sets the default -Q key response delay ⏱️. Default is 3 for 300ms.
  • --depth=[MIN,][MAX], -1, -2, -3, … -9, -10, -11, … — restricts recursive searches from MIN to MAX directory levels deep, where -1 (--depth=1) searches the specified path without recursing into subdirectories. The short forms -3 -5, -3-5 and -3,5 search 3 to 5 levels deep. Enables -r if -R or -r is not specified.
  • --dotall — dot . in regular expressions matches anything, including newline 🫧.
Note that .* matches all input and should not be used. Like, genuinely, don't. 😭
  • -E, --extended-regexp — interpret patterns as extended regular expressions (EREs). This is the default ⭐.
  • -e PATTERN, --regexp=PATTERN — specify a PATTERN to search the input. An input line is selected if it matches any of the specified patterns. This option is useful when multiple -e options are used to specify multiple patterns, or when a pattern starts with a dash (-), or to specify a pattern after option -f or after the FILE arguments 💖.
  • --encoding=ENCODING — the encoding format of the input 🌍. The default ENCODING is binary or UTF-8 which are treated the same. Therefore, --encoding=binary has no effect. Contrast this with option -U or --ascii or --binary that specifies raw binary PATTERN matching. ENCODING can be: binary, ASCII, UTF-8, UTF-16, UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, LATIN1, ISO-8859-1, ISO-8859-2, ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, ISO-8859-9, ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14, ISO-8859-15, ISO-8859-16, MAC, MACROMAN, EBCDIC, CP437, CP850, CP858, CP1250, CP1251, CP1252, CP1253, CP1254, CP1255, CP1256, CP1257, CP1258, KOI8-R, KOI8-U, KOI8-RU, null-data. The way that list just goes off, she really said "every encoding" and meant it 💀.
  • --exclude=GLOB — excludes files whose name matches GLOB, same as -g ^GLOB 🚫. GLOB can use **, *, ?, and [...] as wildcards and \ to quote a wildcard or backslash character literally. When GLOB contains a /, full pathnames are matched. Otherwise basenames are matched. When GLOB ends with a /, directories are excluded as if --exclude-dir is specified. Otherwise files are excluded. Note that --exclude patterns take priority over --include patterns. GLOB should be quoted to prevent shell globbing. This option may be repeated.
  • --exclude-dir=GLOB — excludes directories whose name matches GLOB from recursive searches, same as -g ^GLOB/ 📂. GLOB may use **, *, ?, and [...] as wildcards and \ to quote a wildcard or backslash character literally. When GLOB contains a /, full pathnames are matched. Otherwise basenames are matched. Note that --exclude-dir patterns take priority over --include-dir patterns. GLOB should be quoted to prevent shell globbing. This option may be repeated.
  • --exclude-from=FILE — reads the globs from FILE and skips files and directories whose name matches one or more globs 📜. A glob may use **, *, ?, and [...] as wildcards and \ to quote a wildcard or backslash character literally. When a glob contains a /, full pathnames are matched. Otherwise basenames are matched. When a glob ends with a /, directories are excluded as if --exclude-dir is specified. Otherwise files are excluded. A glob starting with a ! overrides previously-specified exclusions by including matching files. Lines starting with a # in FILE are ignored. When FILE is a -, standard input is read. This option may be repeated. See also related option --ignore-files for subdirectory-specific exclusions.
  • --exclude-fs=MOUNTS — excludes file systems specified by MOUNTS from recursive searches 💽. MOUNTS is a comma-separated list of mount points or pathnames to directories. When MOUNTS is not specified, it only descends into the file systems associated with the specified file and directory search targets, i.e. it excludes all other file systems. Note that --exclude-fs=MOUNTS take priority over --include-fs=MOUNTS. This option may be repeated.
  • -F, --fixed-strings — interpret pattern as a set of fixed strings, separated by newlines, any of which is to be matched 🧵. This makes ugrep behave as fgrep. If a PATTERN is specified, or -e PATTERN or -N PATTERN, then this option has no effect on -f FILE patterns — to allow -f FILE patterns to narrow or widen the scope of the PATTERN search.
  • -f FILE, --file=FILE — bestie, this is your pattern plug 🔌. It reads patterns from FILE, one per line (newline-separated, obvi). White space inside patterns is significant — do not sleep on your spaces, they matter. Empty lines in FILE are just ignored, they're not the vibe. If FILE doesn't exist, the GREP_PATH environment variable gets used as the path to FILE. And if that fails? It goes looking for FILE in /usr/local/share/ugrep/patterns. When FILE is a -, standard input is read. Empty files contain no patterns — which means nothing is matched, iykyk. This option may be repeated 💅
  • --files, -%% — Boolean file matching mode, aka the opposite of --lines. When you combine it with option --bool, it matches a file if all Boolean conditions are satisfied. Example era: --bool --files 'A B|C -D' matches a file if some lines match A, and some lines match either B or C, and no line matches D. See also options --and, --andnot, --not, --bool and --lines. The double short option -%% enables options --bool --files. Two percent signs, absolutely iconic 🎀
  • --filter=COMMANDS — run your files through the specified COMMANDS first, before searching. COMMANDS is a comma-separated list of exts:command arguments, where exts is a comma-separated list of filename extensions and command is a filter utility. Files matching one of exts get filtered. A * matches any file. The specified command may include arguments separated by spaces. An argument may be quoted to include spacing, commas or a %. A % argument expands into the pathname to search. For example, --filter='pdf:pdftotext % -' searches PDF files 🔥. The % expands into a - when searching standard input. When a % is not specified, the filter command should read from standard input and write to standard output. Option --label=.ext may be used to specify extension ext when searching standard input. Note that exts filename extension matching is case insensitive. This option may be repeated ✨
  • --filter-magic-label=[+]LABEL:MAGIC — associate LABEL with files whose signature "magic bytes" match the MAGIC regex pattern 🪄. Only files that have no filename extension are labeled, unless +LABEL is specified. When LABEL matches an extension specified in --filter=COMMANDS, the corresponding command is invoked. This option may be repeated.
  • --format=FORMAT — output FORMAT-formatted matches, so you can make your output all cute and custom 💖. For example --format='%f:%n:%O%~' outputs matching lines %O with filename %f and line number %n followed by a newline %~. If -P is specified, FORMAT may include %1 to %9, %[NUM]# and %[NAME]# to output group captures. A %% outputs %. See ugrep --help format and man ugrep section FORMAT for details. When option -o is specified, option -u is also enabled. Context options -A, -B, -C and -y are ignored — yeah they just get left on read 🙈
  • --free-space — spacing (blanks and tabs) in regular expressions is ignored. She's breezy, she's chill 🌸
  • --from=FILE — read additional pathnames of files to search from FILE. When FILE is a -, standard input is read. This option is useful with find ... -print | ugrep --from=- ... to search specific files. Slay, pipeline queen 👑
  • -G, --basic-regexp — interpret patterns as basic regular expressions (BREs). Classic, retro, lowkey vintage.
  • -g GLOBS, --glob=GLOBS, --iglob=GLOBS — only search files whose name matches the specified comma-separated list of GLOBS, same as --include='glob' for each glob in GLOBS. When a glob is preceded by a ! or a ^, skip files whose name matches glob, same as --exclude='glob'. When glob contains a /, full pathnames are matched and option -r is enabled to recurse into directories if -d, -r or -R is not already specified. Otherwise basenames are matched. When glob ends with a /, directories are matched, same as --include-dir='glob' and --exclude-dir='glob'. A leading ./ or just / matches the working directory. Option --iglob=GLOBS performs case-insensitive name matching. This option may be repeated and may be combined with options -M, -O and -t. For more details, see ugrep --help globs and man ugrep section GLOBBING for details 🦋
  • --glob-ignore-case — perform case-insensitive glob matching in general. She does not care about your capital letters 💅
  • --group-separator[=SEP] — use SEP as a group separator for context options -A, -B and -C. The default is a double hyphen (--). Aesthetic divider energy 💀
  • --no-group-separator — removes the group separator line from the output for context options -A, -B and -C. Clean girl aesthetic, no dividers 🎀
  • -H, --with-filename — always print the filename with output lines. This is the default when there is more than one file to search. Name and shame, respectfully 🫶
  • -h, --no-filename — never print filenames with output lines. This is the default when there is only one file (or only standard input) to search. She's mysterious, no name needed.
  • --heading, -+ — group matches per file. Adds a heading and a line break between results from different files. This option is enabled by --pretty when the output is sent to the terminal. Organized queen behavior ✨
  • --help [WHAT], -? [WHAT] — display a help message on options related to WHAT when specified. In addition, --help regex displays an overview of regular expressions, --help globs displays an overview of glob syntax and conventions, --help fuzzy displays details of fuzzy search, and --help format displays a list of option --format=FORMAT fields. When in doubt, ask for help bestie 😭
  • --hexdump[=[1-8][a][bch][A[NUM]][B[NUM]][C[NUM]]] — output matches in 1 to 8 columns of 8 hexadecimal octets 🔥. The default is 2 columns or 16 octets per line. Argument a outputs a * for all hex lines that are identical to the previous hex line, b removes all space breaks, c removes the character column, h removes hex spacing, A includes up to NUM hex lines after a match, B includes up to NUM hex lines before a match and C includes up to NUM hex lines before and after a match. Arguments A, B and C are the same as options -A, -B and -C when used with --hexdump. See also options -U, -W and -X. Hexadecimal hex girl fall 🍓
  • --hidden, -. — search hidden files and directories (enabled by default in grep compatibility mode). Not me digging up the hidden files 🙈
  • --hyperlink[=[PREFIX][+]] — hyperlinks are enabled for file names when colors are enabled. Same as --colors=hl. When PREFIX is specified, replaces file:// with PREFIX:// in the hyperlink. A + includes the line number in the hyperlink and when option -k is specified, the column number. Clickable, gorgeous, main character energy 👑
  • -I, --ignore-binary — ignore matches in binary files. This option is equivalent to the --binary-files=without-match option. Files having NUL (zero) bytes are binary. Also files with invalid UTF encoding are binary unless option -U or --ascii or --binary is specified. Binary files? Not invited to the function 💀
  • -i, --ignore-case — perform case insensitive matching. By default, ugrep is case sensitive. Turn on the chill mode 😌
  • --ignore-files[=FILE] — ignore files and directories matching the globs in each FILE that is encountered in recursive searches. The default FILE is .gitignore 💅. Matching files and directories located in the directory of the FILE and in subdirectories are ignored. When FILE is a full pathname, FILE is read ahead of the recursive search and globs are globally applied to ignore files and directories. When FILE is a -, standard input is read. Globbing is the same as for --exclude-from=FILE, except that --ignore-files excludes files and also directories when globs match. This option may be repeated.
  • --no-ignore-files — do not ignore files, i.e. cancel --ignore-files when specified. Never mind, we're looking at everything bestie 😭
  • --include=GLOB — only search files whose name matches GLOB, same as -g GLOB. GLOB may use **, *, ?, and [...] as wildcards and \ to quote a wildcard or backslash character literally. When GLOB contains a /, full pathnames are matched and option -r is enabled to recurse into directories if -d, -r or -R is not already specified. Otherwise basenames are matched. When GLOB ends with a /, directories are included as if --include-dir is specified. Otherwise files are included. Note that --exclude patterns take priority over --include patterns — rude but true 🙃. GLOB should be quoted to prevent shell globbing. This option may be repeated ✨
  • --include-dir=GLOB — only directories whose name matches GLOB are included in recursive searches, same as -g GLOB/. GLOB may use **, *, ?, and [...] as wildcards and \ to quote a wildcard or backslash character literally. When GLOB contains a /, full pathnames are matched and option -r is enabled to recurse into directories if -d, -r or -R is not already specified. Otherwise basenames are matched. Note that --exclude-dir patterns take priority over --include-dir patterns. GLOB should be quoted to prevent shell globbing. This option may be repeated 🦋
  • --include-from=FILE — read the globs from FILE and search only files and directories whose name matches one or more globs. A glob may use **, *, ?, and [...] as wildcards and \ to quote a wildcard or backslash character literally. When a glob contains a /, full pathnames are matched. Otherwise basenames are matched. When a glob ends with a /, directories are included as if --include-dir is specified. Otherwise files are included. A glob starting with a ! overrides previously-specified inclusions by excluding matching files. Lines starting with a # and empty lines in FILE are ignored. When FILE is a -, standard input is read. This option may be repeated 🌈
  • --include-fs=MOUNTS — only file systems specified by MOUNTS are included in recursive searches. MOUNTS is a comma-separated list of mount points or pathnames to directories. When MOUNTS is not specified, restricts recursive searches to the file system of the working directory, same as --include-fs=. (dot). Note that --exclude-fs=MOUNTS take priority over --include-fs=MOUNTS. This option may be repeated 🧚
  • --index — the fast index-based recursive search era 💅 this option assumes (but does not require, no pressure bestie) that your files are indexed with ugrep-indexer. It also turns on option -r or --recursive for you, iconic behaviour honestly. It skips indexed non-matching files, archives and compressed files. Big acceleration may happen on cold (not file-cached) and large file systems, or any file system that's slow to search — literally so satisfying. Heads up though: the start-up time to search may be increased when you specify complex search patterns that contain large Unicode character classes combined with * or + repeats, and those should be avoided. Option -U or --ascii or --binary improves performance. Option --stats displays an index search report. 🫶
  • -J NUM, --jobs=NUM — specifies the number of threads spawned to search files. By default an optimum number of threads is spawned to search files simultaneously (the computer is doing its little multitasking slay ✨). -J1 disables threading: files are searched in the same order as specified. Deterministic queen behaviour 👑
  • -j, --smart-case — perform case insensitive matching, unless a pattern is specified with a literal upper case letter. So if you type a capital, it takes you seriously. Smart fr 🧠
  • --json — output file matches in JSON. When -H, -n, -k, or -b is specified, additional values are output. See also options --format and -u. Machine-readable realness 🎀
  • -K [MIN,][MAX], --range=[MIN,][MAX], --min-line=MIN, --max-line=MAX — start searching at line MIN, stop reading input after line MAX. Slice out exactly the lines you want, no cap 🍓
  • -k, --column-number — the column number of a pattern match is displayed in front of the respective matched line, starting at column 1. Tabs are expanded in counting columns, see also option --tabs. So you know exactly where the hit landed 💅
  • -L, --files-without-match — only the names of files not containing selected lines are written to standard output. Pathnames are listed once per file searched. If the standard input is searched, the string (standard input) is written. The anti-hype list, we love a contrarian 😭
  • -l, --files-with-matches — only the names of files containing selected lines are written to standard output. Pathnames are listed once per file searched. If the standard input is searched, the string (standard input) is written. Stop reading input upon the first match. Efficient icon behaviour ⚡
  • --label=LABEL — displays the LABEL value when input is read from standard input where a file name would normally be printed in the output. Associates a filename extension with standard input when LABEL has a suffix. The default value is (standard input). Give your stdin a little name tag 🏷️
  • --line-buffered — force output to be line buffered instead of block buffered. For when you need your output to arrive immediately, main character energy 🌈
  • --lines — boolean line matching mode for option --bool, the default mode.
  • -M MAGIC, --file-magic=MAGIC — only search files matching the magic signature pattern MAGIC. The signature "magic bytes" at the start of a file are compared to the MAGIC regex pattern. When matching, the file will be searched. When MAGIC is preceded by a ! or a ^, skip files with matching MAGIC signatures. This option may be repeated and may be combined with options -O and -t. Warning bestie: every file on the search path is read, making recursive searches potentially more expensive 😬
  • -m [MIN,][MAX], --min-count=MIN, --max-count=MAX — require MIN matches, stop reading input upon MAX matches. Output MIN to MAX matches. For example, -m1 outputs the first match and -cm1, (with a comma) counts nonzero matches. When -u or --ungroup is specified, each individual match counts. See also option -K. Quota queen 👑
  • --match — match all lines. Same as specifying an empty pattern to search. Everything. All of it. 🌸
  • --max-files=NUM — restrict the number of files matched to NUM. Note that --sort or -J1 may be specified to produce replicable results. If --sort is specified, then the number of threads spawned is limited to NUM.
  • --max-size=MAX — only search files whose physical size does not exceed MAX bytes. Suffix MAX with kb, mb, gb, tb for kilo, mega, giga, or terabytes. Little files only pls 🙈
  • --min-size=MIN — only search files whose physical size equals or exceeds MIN bytes. Suffix MIN with kb, mb, gb, tb for kilo, mega, giga, or terabytes. Big files only, no crumbs 🍓
  • --mmap[=MAX] — use memory maps to search files. By default, memory maps are used under certain conditions to improve performance. When MAX is specified, use up to MAX mmap memory per thread. Memory map slay 🧚
  • -N PATTERN, --neg-regexp=PATTERN — specify a negative PATTERN to reject specific -e PATTERN matches with a counter pattern. Note that longer patterns take precedence over shorter patterns, i.e. a negative pattern must be of the same length or longer to reject matching patterns. Option -N cannot be specified with -P. This option may be repeated. It's giving veto power 💀
  • -n, --line-number — each output line is preceded by its relative line number in the file, starting at line 1. The line number counter is reset for each file processed. Numbered like a lil playlist 🎵
  • --not [-e] PATTERN — specifies that PATTERN should not match. Note that -e A --not -e B matches lines with A or lines without a B. To match lines with A that have no B, specify -e A --andnot -e B. Option --stats displays the search patterns applied. See also options --and, --andnot, --bool, --files and --lines. Logic gates but make it fashion 🦋
  • --null, -0 — output a zero byte after the file name. This option can be used with commands such as find -print0 and xargs -0 to process arbitrary file names, even those that contain newlines. See also options -H or --with-filename and --null-data. Newline-proof filenames, we stan 😌
  • --null-data, -00 — input and output are treated as sequences of lines with each line terminated by a zero byte instead of a newline; effectively swaps NUL with LF in the input and the output. When combined with option --encoding=ENCODING, output each line terminated by a zero byte without affecting the input specified as per ENCODING. Instead of option --null-data, option --encoding=null-data treats the input as a sequence of lines terminated by a zero byte without affecting the output. Option --null-data is not compatible with UTF-16/32 input. Since ugrep matches multiple lines when patterns are specified containing a newline \n or \R, this option is not required for multi-line matching. See also options --encoding and --null. Zero byte era 🫶
  • -O EXTENSIONS, --file-extension=EXTENSIONS — only search files whose filename extensions match the specified comma-separated list of EXTENSIONS, same as -g '*.ext' for each ext in EXTENSIONS. When an ext is preceded by a ! or a ^, skip files whose filename extensions matches ext, same as -g '^*.ext'. This option may be repeated and may be combined with options -g, -M and -t. Filter by vibe of file 💅
  • -o, --only-matching — only the matching part of a pattern match is output. When -A, -B or -C is specified, fits the match and its context on a line within the specified number of columns. Just the good part, nothing else ✨
  • --only-line-number — only the line number of a matching line is output. The line number counter is reset for each file processed.
  • -P, --perl-regexp — interpret PATTERN as a Perl regular expression using PCRE2. Note that Perl pattern matching differs from the default grep POSIX pattern matching. Fancy regex bestie, different rules 🎀
  • -p, --no-dereference — if -R or -r is specified, do not follow symbolic links, even when symbolic links are specified on the command line. Links stay put, respectfully 🙅
  • --pager[=COMMAND] — when output is sent to the terminal, uses COMMAND to page through the output. COMMAND defaults to environment variable PAGER when defined or less. Enables --heading and --line-buffered. Scrollable slay 📜
  • --pretty[=WHEN] — when output is sent to the terminal, enables options --color, --heading, -n, --sort, --tree and -T when not explicitly disabled. WHEN can be never, always, or auto. The default is auto. Glow-up mode activated 👑
  • -Q[=DELAY], --query[=DELAY] — query mode: start a TUI to perform interactive searches. This mode requires an ANSI capable terminal. An optional DELAY argument may be specified to reduce or increase the response time to execute searches after the last key press, in increments of 100ms, where the default is 3 (300ms delay). No whitespace may be given between -Q and its argument DELAY. Initial patterns may be specified with -e PATTERN, i.e. a PATTERN argument requires option -e. Press F1 or CTRL+Z to view the help screen. Press F2 or CTRL+Y to invoke a command to view or edit the file shown at the top of the screen. This command can be specified with option --view and defaults to environment variable PAGER when defined, or VISUAL or EDITOR. Press TAB or SHIFT+TAB to navigate directories and to select a file to search. Press ENTER to select lines to output. Press ALT+l for option -l to list files, ALT+n for -n, etc. Non-option commands include ALT+] to increase context and ALT+} to increase fuzzyness. If ALT or OPTION keys are not available, then press CTRL+O + KEY to switch option KEY, or press F1 or CTRL+Z for help and press KEY. See also options --no-confirm, --delay, --split and --view. Interactive searching is literally the moment 💖
  • -q, --quiet, --silent — quiet mode: suppress all output. Only search a file until a match has been found. Silent but deadly (in a cute way) 🤫
  • -R, --dereference-recursive — recursively read all files under each directory, following symbolic links to files and directories, unlike -r. Full send into every link 🔥
  • -r, --recursive — recursively read all files under each directory, following symbolic links only if they are on the command line. Note that when no FILE arguments are specified and input is read from a terminal, recursive searches are performed as if -r is specified. The classic 🫶
  • --replace=FORMAT — replace matching patterns in the output by FORMAT with % fields. If -P is specified, FORMAT may include %1 to %9, %[NUM]# and %[NAME]# to output group captures. A %% outputs % and %~ outputs a newline. See also option --format, ugrep --help format and man ugrep section FORMAT for details. Make the output yours ✨
  • -S, --dereference-files — when -r is specified, follow symbolic links to files, but not to directories. The default is not to follow symbolic links. Half-way dereference, we love a compromise 🎀
  • -s, --no-messages — silent mode, bestie 💅 nonexistent files and unreadable files just get ignored, and their error messages and warnings are suppressed too. Like, no drama, no yelling.
  • --save-config[=FILE] [OPTIONS] — saves a configuration FILE that includes OPTIONS. If you first loaded it with --config=FILE, then FILE gets updated. The default FILE is .ugrep, which the ug command loads automatically ✨. When FILE is -, it writes the configuration to standard output instead. Heads up: only part of the OPTIONS get saved — specifically the ones that won't make searches fail when combined with other options. You can add extra options by editing the saved configuration file yourself. And a config file can be modified by adding one or more config=FILE to include configuration files, but recursive configuration file inclusion is not permitted 🙈 (yes, it will get mad).
  • --separator[=SEP], --context-separator=SEP — uses SEP as the field separator between the file name, line number, column number, byte offset and the matched line. The default separator is a colon (:) — and a bar (|) for multi-line pattern matches, plus a dash (-) for context lines. See also --group-separator 🎀.
  • --split — splits the -Q query TUI screen on startup. That's it, that's the whole vibe 🦋.
  • --sort[=KEY] — displays matching files in the order you specify with KEY in recursive searches. Normally the ug command sorts by name, whereas the ugrep batch command shows matches in no particular order — all in the name of performance, periodt. The sort KEY values are:
    • name — sort by pathname (this is the default)
    • best — sort by best match, works with option -Z (ngl this requires two passes over your files, so it's expensive 💀)
    • size — sort by file size
    • used — sort by last access time
    • changed — sort by last modification time
    • created — sort by creation time

Want it backwards? Say less — rname, rbest, rsize, rused, rchanged, or rcreated reverse the sorting. Archive contents are not sorted. Subdirectories are sorted and displayed after the matching files. And FILE arguments get searched in the same order you specified them 🌸.

  • --stats — outputs statistics on the number of files and directories searched, plus the inclusion and exclusion constraints that were applied. Receipts, basically 🧾✨.
  • -T, --initial-tab — adds a tab space to separate the file name, line number, column number and byte offset from the matched line. Clean columns, immaculate alignment 👑
  • -t TYPES, --file-type=TYPES — search only files associated with TYPES, which is a comma-separated list of file types. Each file type maps to a set of filename extensions passed to option -O and filenames passed to option -g. For capitalized file types, the search expands to include files with matching file signature magic bytes, as if you'd passed them to option -M 🔥. If a type is preceded by a ! or a ^, it excludes files of that type. Specifying just the initial part of a type name is enough when the choice is unambiguous. This option may be repeated ♻️. The possible file types are (and -tlist displays the list): actionscript, ada, adoc, asm, asp, aspx, autoconf, automake, awk, Awk, basic, batch, bison, c, c++, clojure, cpp, csharp, css, csv, dart, Dart, delphi, elisp, elixir, erlang, fortran, gif, Gif, go, groovy, gsp, haskell, html, jade, java, jpeg, Jpeg, js, json, jsp, julia, kotlin, less, lex, lisp, lua, m4, make, markdown, matlab, node, Node, objc, objc++, ocaml, parrot, pascal, pdf, Pdf, perl, Perl, php, Php, png, Png, prolog, python, Python, r, rpm, Rpm, rst, rtf, Rtf, ruby, Ruby, rust, scala, scheme, seed7, shell, Shell, smalltalk, sql, svg, swift, tcl, tex, text, tiff, Tiff, tt, typescript, verilog, vhdl, vim, xml, Xml, yacc, yaml, zig 💖.
  • --tabs[=NUM] — sets the tab size to NUM so tabs get expanded for option -k. NUM can be 1 (no expansion at all), 2, 4, or 8. The default size is 8 🎀.
  • --tag[=TAG[,END]] — disables colors so matches get marked up with TAG instead. END marks the end of a match if you specify it, otherwise TAG does both ends. The default is ___ ✨.
  • --tree, -^ — outputs directories with matching files in a tree-like format 🌳, for option -c or --count, -l or --files-with-matches, and -L or --files-without-match. This option is enabled by --pretty when the output is sent to the terminal.
  • -U, --ascii, --binary — disables Unicode matching, giving you ASCII and binary matching instead. PATTERN matches bytes now. For example, -U '\xa3' matches byte A3 (hex) instead of the Unicode code point U+00A3 represented by the UTF-8 sequence C2 A3. And important: input is not flagged as "binary" just for having invalid UTF — only for having NUL (zero) bytes 💀.
  • -u, --ungroup — do not group multiple pattern matches on the same matched line. Output the matched line again for each additional pattern match. Same line, over and over, main character energy 🫶.
  • -V, --version — displays the version with linked libraries and exits. Bye 👋
  • -v, --invert-match — selected lines are the ones that do not match any of the specified patterns. Swapped the vibe check 😌.
  • --view[=[+]COMMAND] — use COMMAND to view/edit a file in the -Q query TUI by pressing Ctrl+Y. If you put a + in front, +COMMAND waits for a key press after COMMAND terminates 🦋.
  • -W, --with-hex — outputs binary matches in hexadecimal, but leaves text matches alone. Equivalent to the --binary-files=with-hex option. To omit the matching line from the hex output, use both options -W and --hexdump together. See also option -U 🔥.
  • -w, --word-regexp — the PATTERN is searched for as a word, so the matching text is preceded by a non-word character and followed by a non-word character. Word-like characters are Unicode letters, digits and connector punctuations such as underscore 💅.
  • --width[=NUM] — truncates the output to NUM visible characters per line. If you don't give NUM, the width of the terminal window is used. Small caveat: double-width characters in the output may result in wider lines than you asked for 🙈.
  • -X, --hex — outputs matches and matching lines in hexadecimal. Equivalent to the --binary-files=hex option. To omit the matching line from the hex output, use option --hexdump. See also option -U ⭐.
  • -x, --line-regexp — selects only those matches that exactly match the whole line, as if the patterns were surrounded by ^ and $ 🎯.
  • --xml — outputs file matches in XML. When -H, -n, -k, or -b is specified, additional values are output. See also options --format and -u 🧚.
  • -Y, --empty — empty-matching patterns match all lines. Normally, empty matches are not output, unless a pattern starts with ^ or ends with $. With this option, empty-matching patterns such as x*y?, x*y*z*, and x*(y?|z) match all lines — not just the pattern you expected 😭. This option is enabled by default in grep compatibility mode; specify option --no-empty to prevent matching all lines.
  • -y, --any-line, --passthru — every line is output (passthru). Non-matching lines are output as context with a - separator. See also options -A, -B and -C 🌈.
  • -Z[best][+-~][MAX], --fuzzy[=[best][+-~][MAX]] — fuzzy mode, bestie: report approximate pattern matches within MAX errors 💫. The default is -Z1: one deletion, insertion or substitution is allowed. If +, - and/or ~ is specified, then + allows insertions, - allows deletions and ~ allows substitutions. For example, -Z+~3 allows up to three insertions or substitutions, but no deletions. If best is specified, then only the best matching lines are output with the lowest cost per file. Option -Zbest requires two passes over a file and cannot be used with standard input or Boolean queries 💀. Option --sort=best orders matching files by best match. The first character of an approximate match always matches a character at the beginning of the pattern — to fuzzy match the first character, replace it with a . or .?. Option -U applies fuzzy matching to ASCII and bytes instead of Unicode text. And ⚠️ no whitespace may be given between -Z and its argument.
  • -z, --decompress — search compressed files and archives 🗜️. Archives (.cpio, .pax, .tar) and compressed archives (e.g. .zip, .7z, .taz, .tgz, .tpz, .tbz, .tbz2, .tb2, .tz2, .tlz, .txz, .tzst) are searched, and matching pathnames of files inside archives are output in braces. When used with option --zmax=NUM, it searches the contents of compressed files and archives stored within archives up to NUM levels. When -g, -O, -M, or -t is specified, it searches archives for files that match the specified globs, filename extensions, file signature magic bytes, or file types, respectively — and heads up, a side-effect of those options is that the compressed files and archives searched are only those with filename extensions matching known compression and archive types 🙈. Supported compression formats: gzip (.gz), compress (.Z), zip, 7z, bzip2 (.bz, .bz2, .bzip2, .tbz, .tbz2, .tb2, .tz2), xz (.xz, .txz) and lzma (requires suffix .lzma, .tlz), zstd (.zst, .zstd, .tzst), lz4 (requires suffix .lz4), brotli (requires suffix .br), bzip3 (requires suffix .bz3) 🔥.
  • --zmax=NUM — when used with option -z or --decompress, it searches the contents of compressed files and archives stored within archives by up to NUM expansion stages 🌀. The default --zmax=1 only permits searching uncompressed files stored in cpio, pax, tar, zip and 7z archives; compressed files and archives get detected as binary files and are effectively ignored. Specify --zmax=2 to search compressed files and archives stored in cpio, pax, tar, zip and 7z archives. NUM may range from 1 to 99 for up to 99 decompression and de-archiving steps. And ngl, increasing NUM values gradually degrades performance 💀.

Specify ugrep --help WHAT for help on WHAT ✨.

💀 EXIT STATUS 💀

The ugrep utility exits with one of the following values, bestie:

  • 0 — one or more lines were selected 🎉
  • 1 — no lines were selected 😔
  • >1 — an error occurred 💀

And a lil exception: if -q or --quiet or --silent is used and a line is selected, the exit status is 0 even if an error occurred. Slay, we take those 🫶.

🛠️ CONFIGURATION 🛠️

So the ug command? It's made for interactive searching, and it's literally just the ugrep --config --pretty --sort command in a trench coat 💅 — it loads the .ugrep config file that lives in your working directory or, if it's not there, in your home directory.

A config file is just NAME=VALUE pairs, one per line. NAME is a long option name (no -- in front, bestie), and =VALUE is the argument — which is optional and can be straight up omitted depending on the option. Empty lines? Ignored. Lines starting with #? Also ignored. Vibes only ✨

The --config=FILE option — and its abbreviated lil form ---FILE — loads the config file you point at, from the working directory or, when it's not found there, from your home directory. And if FILE isn't found or can't be read? Boom, error. No cap.

Options get parsed in this exact order: the config file loads first, then the rest of the options and arguments on the command line. That's the sequence, periodt.

Now, --save-config saves a .ugrep config file into the working directory, containing a subset of the options you specified on the command line. And "subset" is the key word here — it only saves the part of your options that won't make searches fail when combined with other options 🙈. --save-config=FILE saves the config to FILE instead. And if FILE is -? The config gets written to standard output, iconic behavior honestly.

🌈 GLOBBING 🌈

Globbing is what gets used by -g (--glob and --iglob), --include, --include-dir, --include-from, --exclude, --exclude-dir, --exclude-from and --ignore-files to match pathnames or basenames in recursive searches. And heads up — quote your glob arguments for these options so your shell doesn't gobble them up first 💀

Globbing with --ignore-files supports gitignore syntax and rules. Same deal for every other globbing-related option, except that a glob matches filenames, not directory names. And if a glob ends in a path separator /, then it matches directory names instead of filenames — like you'd typed --include-dir or --exclude-dir. Sneaky but fair.

When a glob contains a path separator /, the full pathname is matched. Otherwise it's the basename of a file or directory that gets matched. For example, *.h matches foo.h and bar/foo.h. Meanwhile bar/*.h matches bar/foo.h but not foo.h and not bar/bar/foo.h. Want to force /*.h to match foo.h in the working directory but not bar/foo.h? Slap a leading ./ on it, or just /. 🌸

When a glob starts with a ! or a ^, like in -g^GLOB, the match is negated. Same energy: a ! (but not a ^) can be used with globs inside the files specified by --include-from, --exclude-from, and --ignore-files to negate the glob match. Empty lines or lines starting with # are ignored, as always 🎀

✨ Glob Syntax and Conventions ✨

*      Matches anything except /.

?      Matches any one character except /.

[abc-e]
       Matches one character a,b,c,d,e.

[^abc-e]
       Matches one character not a,b,c,d,e,/.

[!abc-e]
       Matches one character not a,b,c,d,e,/.

/      When used at the start of a glob, matches the working directory.
       When used at the end of a glob, matches directories only.

**/    Matches zero or more directories.

/**    When used at the end of a glob, matches everything after the /.

\?     Matches a ? or any other character specified after the backslash.

💖 Glob Matching Examples 💖

These are so satisfying to look at, ngl:

*      Matches a, b, x/a, x/y/b

a      Matches a, x/a, x/y/a,       but not b, x/b, a/a/b

/*     Matches a, b,                but not x/a, x/b, x/y/a

/a     Matches a,                   but not x/a, x/y/a

a?b    Matches axb, ayb,            but not a, b, ab, a/b

a[xy]b Matches axb, ayb             but not a, b, azb

a[a-z]b
       Matches aab, abb, acb, azb,  but not a, b, a3b, aAb, aZb

a[^xy]b
       Matches aab, abb, acb, azb,  but not a, b, axb, ayb

a[^a-z]b
       Matches a3b, aAb, aZb        but not a, b, aab, abb, acb, azb

a/*/b  Matches a/x/b, a/y/b,        but not a/b, a/x/y/b

**/a   Matches a, x/a, x/y/a,       but not b, x/b.

a/**/b Matches a/b, a/x/b, a/x/y/b, but not x/a/b, a/b/x

a/**   Matches a/x, a/y, a/x/y,     but not a, b/x

a\?b   Matches a?b,                 but not a, b, ab, axb, a/b
⚠️ Okay important one: exclude glob patterns take priority over include glob patterns when specified with options -g, --exclude, --exclude-dir, --include and include-dir. Exclusion is the main character here, sorry 💅

Option --ignore-files specifies a file with gitignore-style globs, and the default file is .gitignore. When ignore files pop up in recursive searches, the search gets narrowed by excluding filenames and directory names matching the globs. But heads up — this gitignore glob-matching rule is different from option --exclude-from, which requires globs ending in / to match directory names. Subtle, but it matters 🦋

🌿 ENVIRONMENT 🌿

  • GREP_PATH — may be used to specify a file path to pattern files. Option -f uses that file path to open a pattern file when the pattern file doesn't exist. When GREP_PATH is undefined, it defaults to /usr/local/share/ugrep/patterns.
  • GREP_COLOR — may be used to specify ANSI SGR parameters to highlight matches when option --color is used. Like, 1;35;40 shows pattern matches in bold magenta text on a black background. It's deprecated in favor of GREP_COLORS, but still supported (we love a comeback arc 🫶).
  • GREP_COLORS — may be used to specify ANSI SGR parameters to highlight matches and other attributes when option --color is used. Its value is a colon-separated list of ANSI SGR parameters that defaults to cx=33:mt=1;31:fn=1;35:ln=1;32:cn=1;32:bn=1;32:se=36 with additional parameters for TUI colors :qp=1;32:qe=1;37;41:qm=1;32:ql=36:qb=1;35. The mt=, ms=, and mc= capabilities of GREP_COLORS take priority over GREP_COLOR. And option --colors takes priority over GREP_COLORS. Priority queenies, all of them 👑

🎨 GREP_COLORS 🎨

Colors are specified as a string of colon-separated ANSI SGR parameters of the form what=substring, where substring is a semicolon-separated list of ANSI SGR codes — or one of the single-letter shortcuts: k (black), r (red), g (green), y (yellow), b (blue), m (magenta), c (cyan), w (white). Uppercase letters specify background colors, and a + qualifies a color as bright ✨. You can combine a foreground and a background color with one or more font properties: n (normal), f (faint), h (highlight), i (invert), u (underline).

Substrings may be specified for:

  • sl= — selected lines.
  • cx= — context lines.
  • rv — swaps the sl= and cx= capabilities when -v is specified.
  • mt= — matching text in any matching line.
  • ms= — matching text in a selected line. The substring mt= by default.
  • mc= — matching text in a context line. The substring mt= by default.
  • fn= — filenames.
  • ln= — line numbers.
  • cn= — column numbers.
  • bn= — byte offsets.
  • se= — separators.
  • rv — a Boolean parameter, switches sl= and cx= with option -v.
  • hl — a Boolean parameter, enables filename hyperlinks (\33]8;;link).
  • ne — a Boolean parameter, disables "erase in line" \33[K.
  • qp= — TUI prompt.
  • qe= — TUI errors.
  • qr= — TUI regex.
  • qm= — TUI regex meta characters.
  • ql= — TUI regex lists and literals.
  • qb= — TUI regex braces.
🔥 And yes, rv shows up twice in that list — once as the swap rule and once as the Boolean parameter. That's just how the page says it, bestie, I don't make the rules 💀

🌈 FORMAT 🌈

okay bestie, this is the custom-output glow-up section. Option --format=FORMAT specifies an output format for matches. Option --replace=FORMAT only replaces the matching patterns. Fields may be used in FORMAT, which expand into the following values:

  • %[TEXT]F — if option -H is used: TEXT, the file pathname and separator. 💅
  • %f — the file pathname.
  • %a — the file basename without directory path.
  • %p — the directory path to the file.
  • %z — the file pathname in a (compressed) archive. 🦋
  • %[TEXT]H — if option -H is used: TEXT, the quoted pathname and separator, \" and \\ replace " and \.
  • %h — the quoted file pathname, \" and \\ replace " and \.
  • %[TEXT]I — if option -H is used: TEXT, the pathname as XML character data and separator.
  • %i — the file pathname as XML character data.
  • %[TEXT]N — if option -n is used: TEXT, the line number and separator.
  • %n — the line number of the match.
  • %[TEXT]K — if option -k is used: TEXT, the column number and separator.
  • %k — the column number of the match.
  • %[TEXT]B — if option -b is used: TEXT, the byte offset and separator.
  • %b — the byte offset of the match.
  • %[TEXT]T — if option -T is used: TEXT and a tab character.
  • %t — a tab character.
  • %[SEP]$ — set field separator to SEP for the rest of the format fields. 🎀
  • %[TEXT]< — if the first match: TEXT.
  • %[TEXT]> — if not the first match: TEXT.
  • %, — if not the first match: a comma, same as %[,]>.
  • %: — if not the first match: a colon, same as %[:]>.
  • %; — if not the first match: a semicolon, same as %[;]>.
  • %| — if not the first match: a vertical bar, same as %[|]>.
  • %[TEXT]S — if not the first match: TEXT and separator, see also %[SEP]$.
  • %s — the separator, see also %[TEXT]S and %[SEP]$.
  • %~ — a newline character.
  • %M — the number of matching lines.
  • %m — the number of matches.
  • %O — the matching line is output as a raw string of bytes.
  • %o — the match is output as a raw string of bytes.
  • %Q — the matching line as a quoted string, \" and \\ replace " and \.
  • %q — the match as a quoted string, \" and \\ replace " and \.
  • %C — the matching line formatted as a quoted C/C++ string.
  • %c — the match formatted as a quoted C/C++ string.
  • %J — the matching line formatted as a quoted JSON string.
  • %j — the match formatted as a quoted JSON string.
  • %V — the matching line formatted as a quoted CSV string.
  • %v — the match formatted as a quoted CSV string.
  • %X — the matching line formatted as XML character data.
  • %x — the match formatted as XML character data.
  • %w — the width of the match, counting wide characters.
  • %d — the size of the match, counting bytes.
  • %e — the ending byte offset of the match.
  • %Z — the edit distance cost of an approximate match with option -Z.
  • %u — select unique lines only, unless option -u is used.
  • %1 — the first regex group capture of the match, and so on up to group %9, same as %[1]#; requires option -P.
  • %[NUM]# — the regex group capture NUM; requires option -P.
  • %[NUM]b — the byte offset of the group capture NUM; requires option -P. Use e for the ending byte offset and d for the byte length.
  • %[NUM1|NUM2|...]# — the first group capture NUM that matched; requires option -P.
  • %[NUM1|NUM2|...]b — the byte offset of the first group capture NUM that matched; requires option -P. Use e for the ending byte offset and d for the byte length.
  • %[NAME]# — the group capture named NAME; requires option -P and capturing pattern (?<NAME>PATTERN), see also %G.
  • %[NAME]b — the byte offset of the group capture named NAME; requires option -P and capturing pattern (?<NAME>PATTERN). Use e for the ending byte offset and d for the byte length.
  • %[NAME1|NAME2|...]# — the first group capture named NAME that matched; requires option -P and capturing pattern (?<NAME>PATTERN), see also %G.
  • %[NAME1|NAME2|...]b — the byte offset of the first group capture named NAME that matched; requires option -P and capturing pattern (?<NAME>PATTERN). Use e for the ending byte offset and d for the byte length.
  • %G — list of group capture indices/names that matched; requires option -P.
  • %[TEXT1|TEXT2|...]G — list of TEXT indexed by group capture indices that matched; requires option -P.
  • %g — the group capture index/name matched or 1; requires option -P.
  • %[TEXT1|TEXT2|...]g — the first TEXT indexed by the first group capture index that matched; requires option -P.
  • %% — the percentage sign.

Formatted output is written without a terminating newline, unless %~ or \n is explicitly specified in the format string. 😭

The [TEXT] part of a field is optional and may be omitted. When present, the argument must be placed in [] brackets, for example %[,]F to output a comma, the pathname, and a separator. ✨

%[SEP]$ and %u are switches and do not send anything to the output.

The separator used by the %F, %H, %I, %N, %K, %B, %S and %G fields may be changed by preceding the field by %[SEP]$. When [SEP] is not provided, this reverts the separator to the default separator or the separator specified with --separator. 🫶

Formatted output is written for each matching pattern, which means that a line may be output multiple times when patterns match more than once on the same line. If field %u is specified anywhere in a format string, matching lines are output only once, unless option -u, --ungroup is specified or when more than one line of input matched the search pattern. 💀

Additional formatting options:

  • --format-begin=FORMAT — the FORMAT when beginning the search.
  • --format-open=FORMAT — the FORMAT when opening a file and a match was found.
  • --format-close=FORMAT — the FORMAT when closing a file and a match was found.
  • --format-end=FORMAT — the FORMAT when ending the search.

The context options -A, -B, -C, -y, and display options --break, --heading, --color, -T, and --null have no effect on formatted output. periodt. 💜

✨ EXAMPLES ✨

Okay bestie, this is the fun part — literally the whole vibe of the page is show, don't tell. Every single one of these is copy-pasteable, so go off 💅

Show the lines in myfile.txt that have the word patricia:

$ ugrep -w patricia myfile.txt

Same thing, but we're ignoring case now (because Patricia, PATRICIA, pAtRiCiA are all iconic and deserve equal treatment):

$ ugrep -wi patricia myfile.txt

Now here's the ✨fuzzy✨ one — match patricia approximately, ignoring case, and let it slide if there are up to 2 spelling errors:

$ ugrep -Z2 -wi patricia myfile.txt

Count how many lines contain patricia, case ignored:

$ ugrep -cwi patricia myfile.txt

Count how many words patricia show up, case ignored (subtle difference, but it's giving precision):

$ ugrep -cowi patricia myfile.txt

List the lines with amount plus a decimal, case ignored — and yeah, in Boolean query mode a space is an AND:

$ ugrep -i -% 'amount \d+(\.\d+)?' myfile.txt

The exact same Boolean search, but written out with -e and --and instead:

$ ugrep -wi -e amount --and '\d+(\.\d+)?' myfile.txt

List every Unicode word in a file, no cap:

$ ugrep -o '\w+' myfile.txt

List the laughing face emojis 😂 — that's Unicode code points U+1F600 to U+1F60F:

$ ugrep -o '[\x{1F600}-\x{1F60F}]' myfile.txt

Quick vibe check: does this file contain any non-ASCII (a.k.a. Unicode) characters at all?

$ ugrep -q '[^[:ascii:]]' myfile.txt && echo "contains Unicode"

Show the line and column number of FIXME in C++ files, recursive, with one line of context before and after each matched line:

$ ugrep -C1 -R -n -k -tc++ FIXME

Same deal for long Javascript files — recursive, line and column numbers for FIXME, but only showing matches with up to 10 characters of context before and after:

$ ugrep -o -C20 -R -n -k -tjs FIXME

Find blocks of text between lines matching BEGIN and END, using a lazy quantifier *? so we only match what's necessary, plus \n to match newlines:

$ ugrep -n 'BEGIN.*\n(.*\n)*?.*END' myfile.txt

Same energy — list the C/C++ comments in a file with line numbers:

$ ugrep -n -e '//.*' -e '/\*(.*\n)*?.*\*+\/' myfile.cpp

Literally the same thing, but using the predefined pattern c++/comments:

$ ugrep -n -f c++/comments myfile.cpp

List the lines that need fixing in a C/C++ source file by hunting for FIXME while skipping any FIXME that's trapped inside quoted strings:

$ ugrep -e FIXME -N '"(\\.|\\\r?\n|[^\\\n"])*"' myfile.cpp

Same, but with the predefined pattern cpp/zap_strings:

$ ugrep -e FIXME -f cpp/zap_strings myfile.cpp

Find lines with FIXME or TODO, line numbers included:

$ ugrep -n -e FIXME -e TODO myfile.cpp

Find lines with FIXME that also contain urgent:

$ ugrep -n -e FIXME --and urgent myfile.cpp

Same result, but using a Boolean query pattern (remember: a space is AND):

$ ugrep -n -% 'FIXME urgent' myfile.cpp

Find lines with FIXME that do not also contain later:

$ ugrep -n -e FIXME --andnot later myfile.cpp

Same, but as a Boolean query pattern (space is AND, - is NOT):

$ ugrep -n -% 'FIXME -later' myfile.cpp

Output just a list of line numbers for lines with FIXME but not later:

$ ugrep -e FIXME --andnot later --format='%,%n' myfile.cpp

Recursively list all files that contain both FIXME and LICENSE anywhere in the file — not necessarily on the same line:

$ ugrep -l -%% 'FIXME LICENSE'

Find lines with FIXME in the C/C++ files stored inside a tarball:

$ ugrep -z -tc++ -n FIXME project.tgz

Recursively find lines with FIXME in C/C++ files, but skip any bak and old directories entirely:

$ ugrep -n FIXME -tc++ -g^bak/,^old/

Recursively search for the word copyright in cpio, jar, pax, tar, zip and 7z archives, in compressed and regular files, and in PDFs using a PDF filter:

$ ugrep -z -w --filter='pdf:pdftotext % -' copyright

Match the binary pattern A3hhhhA3 (hex) in a binary file without Unicode pattern matching, so -U — otherwise \xaf would be matched as the Unicode character U+00A3 with UTF-8 byte sequence C2 A3 — and show the results in hex with --hexdump, using C1 to output one hex line before and after each match:

$ ugrep -U --hexdump=C1 '\xa3[\x00-\xff]{2}\xa3' a.out

Hexdump an entire file through a pager for easy viewing:

$ ugrep -X --pager '' a.out

List every file that is not ignored by one or more .gitignore files:

$ ugrep -l '' --ignore-files

List all files containing an RPM signature, located in the rpm directory and recursively below it up to two levels deeper (3 levels total):

$ ugrep -3 -l -tRpm '' rpm/

Monitor the system log for bug reports and ungroup multiple matches within matching lines into separate lines:

$ tail -f /var/log/system.log | ugrep -u -i -w bug

Interactive fuzzy search with Boolean search queries — yes, this is as fun as it sounds:

$ ugrep -Q -l -% -Z2 --sort=best

Display all words in a MacRoman-encoded file that uses CR newlines:

$ ugrep --encoding=MACROMAN '\w+' mac.txt

Display the options related to "fuzzy" searching (a little menu of the fuzzy stuff):

$ ugrep --help fuzzy

Copyright (c) 2021-2025 Robert A. van Engelen <engelen@acm.org>

ugrep is released under the BSD-3 license. Every part of the software has reasonable copyright terms that permit free redistribution — and yes, that includes the ability to reuse all or parts of the ugrep source tree. Slay, honestly 🫶

🦋 SEE ALSO 🦋

🙈 BUGS 🙈

Report bugs at: https://github.com/Genivia/ugrep/issues

Found something cursed? Don't suffer in silence, bestie — drop it in the issue tracker 💀

And that's the whole page! ✨ This gorgeous thing is ugrep version 7.8.5, dated September 15, 2026, and it's the UGREP(1) manual page — go forth and grep fearlessly, queen 👑🎀

📦 where this page comes from