Table of contents

How to install

MacOS

Performance comparisons

Please note that the ugrep and ug commands search binary files by default and do not ignore .gitignore specified files, which will not make recursive search performance comparisons meaningful unless options -I and --ignore-files are used. To make these options the default for ug, simply add ignore-binary and ignore-files to your .ugrep configuration file.

Using ugrep within Vim

First, let's define the :grep command in Vim to search files recursively. To do so, add the following lines to your .vimrc located in the root directory:

if executable('ugrep')
    set grepprg=ugrep\ -RInk\ -j\ -u\ --tabs=1\ --ignore-files
    set grepformat=%f:%l:%c:%m,%f+%l+%c+%m,%-G%f\\\|%l\\\|%c\\\|%m
endif

Using ugrep within Emacs

Using ugrep to replace GNU/BSD grep

Equivalence to GNU/BSD grep

When the ugrep executable file is symlinked or copied to grep, egrep, fgrep, zgrep, zegrep and zfgrep executables, then those executables will behave as GNU grep equivalents. This behavior is implicit and automatic, essentially using the following translations:

grep   = ugrep -G -Y -. --sort
egrep  = ugrep -E -Y -. --sort
fgrep  = ugrep -F -Y -. --sort

zgrep  = ugrep -z -G -Y -. --sort
zegrep = ugrep -z -E -Y -. --sort
zfgrep = ugrep -z -F -Y -. --sort

please note that:

Short and quick command aliases

Commonly-used aliases to add to .bashrc to increase productivity:

alias uq     = 'ug -Q'                # interactive TUI search (uses .ugrep config)
alias uz     = 'ug -z'                # compressed files and archives search (uses .ugrep config)
alias ux     = 'ug -U --hexdump'      # binary pattern search (uses .ugrep config)

alias ugit   = 'ug -R --ignore-files' # works like git-grep & define your preferences in .ugrep config

alias grep   = 'ug -G'                # search with basic regular expressions (BRE) like grep
alias egrep  = 'ug -E'                # search with extended regular expressions (ERE) like egrep
alias fgrep  = 'ug -F'                # find string(s) like fgrep
alias zgrep  = 'ug -zG'               # search compressed files and archives with BRE
alias zegrep = 'ug -zE'               # search compressed files and archives with ERE
alias zfgrep = 'ug -zF'               # find string(s) in compressed files and/or archives

alias xdump  = 'ugrep -X ""'                 # hexdump files without searching (don't use .ugrep config)
alias zmore  = 'ugrep+ -z -I -+ --pager ""'  # view compressed, archived and regular files (don't use .ugrep config)

Notable improvements over grep

• ugrep starts an interactive query TUI with option -Q.
• ugrep matches patterns across multiple lines when patterns match \n.
• ugrep matches full Unicode by default (disabled with option -U).
• ugrep supports Boolean patterns with AND, OR and NOT (option --bool).
• ugrep supports gitignore with option --ignore-files.
• ugrep supports fuzzy (approximate) matching with option -Z.
• ugrep supports user-defined global and local configuration files.
• ugrep searches compressed files and archives with option -z.
• ugrep searches cpio, jar, pax, tar, zip and 7z archives with option -z.
• ugrep searches cpio, jar, pax, tar, zip and 7z archives recursively stored within archives with -z and --zmax=NUM for up to NUM levels deep.
• ugrep searches pdf, doc, docx, xls, xlsx, epub, and more with --filter using third-party format conversion utilities as plugins.
• ugrep searches a directory when the FILE argument is a directory, like most Unix/Linux utilities; use option -r to search directories recursively.
• ugrep does not match hidden files by default like most Unix/Linux utilities (hidden dotfile file matching is enabled with -.).
• ugrep regular expression patterns are more expressive than GNU grep and BSD grep POSIX ERE and support Unicode pattern matching. Extended regular expression (ERE) syntax is the default (i.e. option -E as egrep, whereas -G enables BRE).
• ugrep spawns threads to search files concurrently to improve search speed (disabled with option -J1).
• ugrep produces hexdumps with -W (output binary matches in hex with text matches output as usual) and -X (output all matches in hex).
• ugrep can output matches in JSON, XML, CSV and user-defined formats (with option --format).
• ugrep option -f uses GREP_PATH environment variable or the predefined patterns installed in /usr/local/share/ugrep/patterns. If -f is specified and also one or more -e patterns are specified, then options -F, -x, and -w do not apply to -f patterns. This is to avoid confusion when -f is used with predefined patterns that may no longer work properly with these options.
• ugrep options -O, -M, and -t specify file extensions, file signature magic byte patterns, and predefined file types, respectively. This allows searching for certain types of files in directory trees, for example with recursive search options -R and -r. Options -O, -M, and -t also applies to archived files in cpio, jar, pax, tar, zip and 7z files.
• ugrep option -k, --column-number to display the column number, taking tab spacing into account by expanding tabs, as specified by option --tabs.
• ugrep option -P (Perl regular expressions) supports backreferences (with --format) and lookbehinds, which uses the PCRE2 or Boost.Regex library for fast Perl regex matching with a PCRE-like syntax.
• ugrep option -b with option -o or with option -u, ugrep displays the exact byte offset of the pattern match instead of the byte offset of the start of the matched line reported by GNU/BSD grep.
• ugrep option -u, --ungroup to not group multiple matches per line. This option displays a matched input line again for each additional pattern match on the line. This option is particularly useful with option -c to report the total number of pattern matches per file instead of the number of lines matched per file.
• ugrep option -Y enables matching empty patterns. Grepping with empty-matching patterns is weird and gives different results with GNU grep versus BSD grep. Empty matches are not output by ugrep by default, which avoids making mistakes that may produce "random" results. For example, with GNU/BSD grep, pattern a* matches every line in the input, and actually matches xyz three times (the empty transitions before and between the x, y, and z). Allowing empty matches requires ugrep option -Y. Patterns that start with ^ or end with $, such as ^\h*$, match empty. These patterns automatically enable option -Y.
• ugrep option -D, --devices=ACTION is skip by default, instead of read. This prevents unexpectedly hanging on named pipes in directories that are recursively searched, as may happen with GNU/BSD grep that read devices by default.
• ugrep option -d, --directories=ACTION is skip by default, instead of read. By default, directories specified on the command line are searched, but not recursively deeper into subdirectories.
• ugrep offers negative patterns -N PATTERN, which are patterns of the form (?^X) that skip all X input, thus removing X from the search. For example, negative patterns can be used to skip strings and comments when searching for identifiers in source code and find matches that aren't in strings and comments. Predefined zap patterns use negative patterns, for example, use -f cpp/zap_comments to ignore pattern matches in C++ comments.
• ugrep ignores the GREP_OPTIONS environment variable, because the behavior of ugrep must be portable and predictable on every system. Also GNU grep abandoned GREP_OPTIONS for this reason. Please use the ug command that loads the .ugrep configuration file located in the working directory or in the home directory when present, or use shell aliases to create new commands with specific search options.

Tutorial

Examples

To perform a search using a configuration file .ugrep placed in the working directory or home directory (note that ug is the same as ugrep --config):

ug PATTERN FILE...

To save a .ugrep configuration file to the working directory, then edit this file in your home directory to customize your preferences for ug defaults:

ug --save-config

To search the working directory and recursively deeper for main (note that -r recurse symlinks is enabled by default if no file arguments are specified):

ug main

Same, but only search C++ source code files recursively, ignoring all other files:

ug -tc++ main

Same, using the interactive query TUI, starting with the initial search pattern main (note that -Q with an initial pattern requires option -e because patterns are normally specified interactively and all command line arguments are considered files/directories):

ug -Q -tc++ -e main

To search for #define (and # define etc) using a regex pattern in C++ files (note that patterns should be quoted to prevent shell globbing of * and ?):

ug -tc++ '#[\t ]*define'

To search for main as a word (-w) recursively without following symlinks (-r) in directory myproject, showing the matching line (-n) and column (-k) numbers next to the lines matched:

ug -r -nkw main myproject

Same, but only search myproject without recursing deeper (note that directory arguments are searched at one level by default):

ug -nkw main myproject

Same, but search myproject and one subdirectory level deeper (two levels) with -2:

ug -2 -nkw main myproject

Same, but only search C++ files in myproject and its subdirectories with -tc++:

ug -tc++ -2 -nkw main myproject

Same, but also search inside archives (e.g. zip and tar files) and compressed files with -z:

ug -z -tc++ -2 -nkw main myproject

Search recursively the working directory for main while ignoring gitignored files (e.g. assuming .gitignore is in the working directory or below):

ug --ignore-files -tc++ -nkw main

To list all files in the working directory and deeper that are not ignored by .gitignore file(s):

ug --ignore-files -l ''

To display the list of file name extensions and "magic bytes" (shebangs) that are searched corresponding to -t arguments:

ug -tlist

To list all shell files recursively, based on extensions and shebangs with -l (note that '' matches any non-empty file):

ug -l -tShell ''

Advanced examples

To search for main in source code while ignoring strings and comment blocks you can use negative patterns with option -N to skip unwanted matches in C/C++ quoted strings and comment blocks:

ug -r -nkw -e 'main' -N '"(\\.|\\\r?\n|[^\\\n"])*"|//.*|/\*(.*\n)*?.*\*+\/' myproject

This is a lot of work to type in correctly! If you are like me, I don't want to spend time fiddling with regex patterns when I am working on something more important. There is an easier way by using ugrep's predefined patterns (-f) that are installed with the ugrep tool:

ug -r -nkw 'main' -f c/zap_strings -f c/zap_comments myproject

This query also searches through other files than C/C++ source code, like READMEs, Makefiles, and so on. We're also skipping symlinks with -r. So let's refine this query by selecting C/C++ files only using option -tc,c++ and include symlinks to files and directories with -R:

ug -R -tc,c++ -nkw 'main' -f c/zap_strings -f c/zap_comments myproject

What if you only want to look for the identifier main but not as a function main(? In this case, use a negative pattern for this to skip unwanted main\h*( pattern matches:

ug -R -tc,c++ -nkw -e 'main' -N 'main\h*\(' -f c/zap_strings -f c/zap_comments myproject

This uses the -e and -N options to explicitly specify a pattern and a negative pattern, respectively, which is essentially forming the pattern main|(?^main\h*\(), where \h matches space and tab. In general, negative patterns are useful to filter out pattern matches that we are not interested in.

As another example, let's say we may want to search for the word FIXME in C/C++ comment blocks. To do so we can first select the comment blocks with ugrep's predefined c/comments pattern AND THEN select lines with FIXME using a pipe:

ug -R -tc,c++ -nk -f c/comments myproject | ug -w 'FIXME'

Filtering results with pipes is generally easier than using AND-OR logic that some search tools use. This approach follows the Unix spirit to keep utilities simple and use them in combination for more complex tasks.

Let's produce a sorted list of all identifiers found in Java source code while skipping strings and comments:

ug -R -tjava -f java/names myproject | sort -u

This matches Java Unicode identifiers using the regex \p{JavaIdentifierStart}\p{JavaIdentifierPart}* defined in patterns/java/names.

With traditional grep and grep-like tools it takes great effort to recursively search for the C/C++ source file that defines function qsort, requiring something like this:

ug -R --include='*.c' --include='*.cpp' '^([ \t]*[[:word:]:*&]+)+[ \t]+qsort[ \t]*\([^;\n]+$' myproject

Fortunately, with ugrep we can simply select all function definitions in files with extension .c or .cpp by using option -Oc,cpp and by using a predefined pattern functions that is installed with the tool to produce all function definitions. Then we select the one we want:

ug -R -Oc,cpp -nk -f c/functions | ug 'qsort'

Note that we could have used -tc,c++ to select C/C++ files, but this also includes header files when we want to only search .c and .cpp files.

We can also skip files and directories from being searched that are defined in .gitignore. To do so we use --ignore-files to exclude any files and directories from recursive searches that match the globs in .gitignore, when one or more .gitignore files are found:

ug -R -tc++ --ignore-files -f c++/defines

This searches C++ files (-tc++) in the working directory for #define lines (-f c++/defines), while skipping files and directories declared in .gitignore. If you find this too long to type then define an alias to search GitHub directories:

alias ugit='ugrep -R --ignore-files'
ugit -tc++ -f c++/defines

To highlight matches when pushed through a chain of pipes we should use --color=always:

ugit --color=always -tc++ -f c++/defines | ugrep -w 'FOO.*'

This returns a color-highlighted list of all #define FOO... macros in C/C++ source code files, skipping files defined in .gitignore.

Note that the complement of --exclude is not --include, because exclusions always take precedence over inclusions, so we cannot reliably list the files that are ignored with --include-from='.gitignore'. Only files explicitly specified with --include and directories explicitly specified with --include-dir are visited. The --include-from from lists globs that are considered both files and directories to add to --include and --include-dir, respectively. This means that when directory names and directory paths are not explicitly listed in this file then it will not be visited using --include-from.

Because ugrep checks if the input is valid UTF-encoded Unicode (unless -U is used), it is possible to use it as a filter to ignore non-UTF output produced by a program:

program | ugrep -I ''

If the program produces valid output then the output is passed through, otherwise the output is filtered out option -I. If the output is initially valid for a very large portion but is followed by invalid output, then ugrep may initially show the output up to but excluding the invalid output after which further output is blocked.

To filter lines that are valid ASCII or UTF-encoded, while removing lines that are not:

program | ugrep '[\p{Unicode}--[\n]]+'

Note that \p{Unicode} matches \n but we don't want to matche the whole file! Just lines with [\p{Unicode}--[\n]]+.

Displaying helpful info

The ugrep man page:

man ugrep

To show a help page:

ug --help

To show options that mention WHAT:

ug --help WHAT

To show a list of -t TYPES option values:

ug -tlist

In the interactive query TUI, press F1 or CTRL-Z for help and options:

ug -Q

Configuration files

--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,
        unless --config=FILE or --no-config is specified.
--no-config
        Do not load the default .ugrep configuration file.
--save-config[=FILE] [OPTIONS]
        Save configuration FILE to include OPTIONS.  Update FILE when
        first loaded with --config=FILE.  The default FILE is `.ugrep',
        which is automatically loaded by the ug command.  When FILE is a
        `-', writes the configuration to standard output.  Only part of the
        OPTIONS are saved that do not cause searches to fail when combined
        with other options.  Additional options may be specified by editing
        the saved configuration file.  A configuration file may be modified
        manually to specify one or more config[=FILE] to indirectly load
        the specified FILEs, but recursive config loading is not allowed.

The ug command versus the ugrep command

The ug command is intended for context-dependent interactive searching and is equivalent to the ugrep --config command to load the configuration file .ugrep when present in the working directory or, when not found, in the home directory:

ug PATTERN ...
ugrep --config PATTERN ...

The ug command also sorts files by name per directory searched. A configuration file contains NAME=VALUE pairs per line, where NAME is the name of a long option (without --) and =VALUE is an argument, which is optional and may be omitted depending on the option. Empty lines and lines starting with a # are ignored:

# Color scheme
colors=cx=hb:ms=hiy:mc=hic:fn=hi+y+K:ln=hg:cn=hg:bn=hg:se=
# Disable searching hidden files and directories
no-hidden
# ignore files specified in .ignore and .gitignore in recursive searches
ignore-files=.ignore
ignore-files=.gitignore

Command line options are parsed in the following order: first the (default or named) configuration file is loaded, then the remaining options and arguments on the command line are parsed.

Option --stats displays the configuration file used after searching.

Named configuration files

Named configuration files are intended to streamline custom search tasks, by reducing the number of command line options to just one ---FILE to use the collection of options specified in FILE. The --config=FILE option and its abbreviated form ---FILE load the specified configuration file located in the working directory or, when not found, located in the home directory:

ug ---FILE PATTERN ...
ugrep ---FILE PATTERN ...

An error is produced when FILE is not found or cannot be read.

Named configuration files can be used to define a collection of options that are specific to the requirements of a task in the development workflow of a project. For example to report unresolved issues by checking the source code and documentation for comments with FIXME and TODO items. Such named configuration file can be localized to a project by placing it in the project directory, or it can be made global by placing it in the home directory. For visual feedback, a color scheme specific to this task can be specified with option colors in the configuration FILE to help identify the output produced by a named configuration as opposed to the default configuration.

Saving a configuration file

The --save-config option saves a .ugrep configuration file to the working directory using the current configuration loaded with --config. This saves the current configuration combined with additional options when specified also. Only those options that cannot conflict with other options and options that cannot negatively impact search results will be saved.

The --save-config=FILE option saves the configuration to the specified FILE. The configuration is written to standard output when FILE is a -.

Alternatively, a configuration file may be manually created or modified. A configuration file may include one or more config[=FILE] to indirectly load the specfified FILE, but recursive config loading is prohibited. The simplest way to manuall create a configuration file is to specify config at the top of the file, followed by the long options to override the defaults.

Interactive search with -Q

-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.
        The command can be specified with option --view, or defaults to
        environment variable PAGER when defined, or EDITOR.  Press Tab and
        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.  See also options --no-confirm, --delay,
        --split and --view.
--no-confirm
        Do not confirm actions in -Q query TUI.  The default is confirm.
--delay=DELAY
        Set the default -Q key response delay.  Default is 3 for 300ms.
--split
        Split the -Q query TUI screen on startup.
--view[=COMMAND]
        Use COMMAND to view/edit a file in -Q query TUI by pressing CTRL-Y.

This option starts a user interface to enter search patterns interactively:

• Press F1 or CTRL-Z to view a help screen and to enable or disable options.
• Press Alt with a key corresponding to a ugrep option letter or digit to enable or disable the ugrep option. For example, pressing Alt-c enables option -c to count matches. Pressing Alt-c again disables -c. Options can be toggled with the Alt key while searching or when viewing the help screen. If Alt/Meta keys are not working (e.g. X11 xterm), then press CTRL-O followed by the key corresponding to the option. Alt keys may work in xterm by adding xterm*metaSendsEscape: true to ~/.Xdefaults`.
• Press Alt-g to enter or edit option -g file and directory matching globs, a comma-separated list of gitignore-style glob patterns. Presssing ESC returns control to the query pattern prompt (the globs are saved). When a glob is preceded by a ! or a ^, skips files whose name matches the glob When a glob contains a /, full pathnames are matched. Otherwise basenames are matched. When a glob ends with a /, directories are matched.
• The query TUI prompt switches between Q> (normal), F> (fixed strings), G> (basic regex), P> (Perl matching), and Z> (fuzzy matching). When the --glob= prompt is shown, a comma-separated list of gitignore-style glob patterns may be entered. Presssing ESC returns control to the pattern prompt.
• Press CTRL-T to split the TUI screen to preview a file in the bottom pane.
• Press CTRL-Y to view a file with a pager specified with --view.
• Press Enter to switch to selection mode to select lines to output when ugrep exits. Normally, ugrep in query mode does not output any results unless results are selected. While in selection mode, select or deselect lines with Enter or Del, or press A to select all results.
• The file listed or shown at the top of the screen, or beneath the cursor in selection mode, is edited by pressing F2 or CTRL-Y. A file viewer or editor may be specified with --view=COMMAND. Otherwise, the PAGER or EDITOR environment variables are used to invoke the command with CTRL-Y. Filenames must be enabled and visible in the output to use this feature.
• Press TAB to chdir one level down into the directory of the file listed or viewed at the top of the screen. If no directory exists, the file itself is selected to search. Press Shift-TAB to go back up one level.
• Press CTRL-] to toggle colors on and off. Normally ugrep in query mode uses colors and other markup to highlight results. When colors are turned off, selected results are also not colored in the output produced by ugrep when ugrep exits. When colors are turned on (the default), selected results are colored depending on the --color option.
• The query engine is optimized to limit system load by performing on-demand searches to produce results only for the visible parts shown in the interface. That is, results are shown on demand, when scrolling down and when exiting when all results are selected. When the search pattern is modified, the previous search query is cancelled when incomplete. This effectively limits the load on the system to maintain a high degree of responsiveness of the query engine to user input. Because the search results are produced on demand, occasionally you may notice a flashing "Searching..." message when searching files.
• To display results faster, specify a low DELAY value such as 1. However, lower values may increase system load as a result of repeatedly initiating and cancelling searches by each key pressed.
• To avoid long pathnames to obscure the view, --heading is enabled by default. Press Alt-+ to switch headings off.

Query TUI key mapping:

To interactively search the files in the working directory and below:

ug -Q

Same, but restricted to C++ files only and ignoring .gitignore files:

ug -Q -tc++ --ignore-files

To interactively search all makefiles in the working directory and below:

ug -Q -g 'Makefile*' -g 'makefile*'

Same, but for up to 2 directory levels (working and one subdirectory level):

ug -Q -2 -g 'Makefile*' -g 'makefile*'

To interactively view the contents of main.cpp and search it, where -y shows any nonmatching lines as context:

ug -Q -y main.cpp

To interactively search main.cpp, starting with the search pattern TODO and a match context of 5 lines (context can be interactively enabled and disabled, this also overrides the default context size of 2 lines):

ug -Q -C5 -e TODO main.cpp

To view and search the contents of an archive (e.g. zip, tarball):

ug -Q -z archive.tar.gz

To interactively select files from project.zip to decompress with unzip, using ugrep query selection mode (press Enter to select lines):

unzip project.zip `zipinfo -1 project.zip | ugrep -Q`

Recursively list matching files with -l, -R, -r, -S, --depth, -g, -O, and -t

-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.
-l, --files-with-matches
        Only the names of files containing selected lines are written to
        standard output.  ugrep will only search a file until a match has
        been found, making searches potentially less expensive.  Pathnames
        are listed once per file searched.  If the standard input is
        searched, the string ``(standard input)'' is written.
-R, --dereference-recursive
        Recursively read all files under each directory.  Follow all
        symbolic links to files and directories, unlike -r.
-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.
-S, --dereference-files
        When -r is specified, symbolic links to files are followed, but not
        to directories.  The default is not to follow symbolic links.
--depth=[MIN,][MAX], -1, -2, -3, ... -9, -10, -11, -12, ...
        Restrict recursive searches from MIN to MAX directory levels deep,
        where -1 (--depth=1) searches the specified path without recursing
        into subdirectories.  Note that -3 -5, -3-5, and -35 search 3 to 5
        levels deep.  Enables -r if -R or -r is not specified.
-g GLOBS, --glob=GLOBS
        Search only 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.  Otherwise basenames are matched.
        When `glob' ends with a `/', directories are matched, same as
        --include-dir='glob' and --exclude-dir='glob'.  A leading `/'
        matches the working directory.  This option may be repeated and may
        be combined with options -M, -O and -t to expand searches.  See
        `ugrep --help globs' and `man ugrep' section GLOBBING for details.
-O EXTENSIONS, --file-extension=EXTENSIONS
        Search only files whose filename extensions match the specified
        comma-separated list of EXTENSIONS, same as --include='*.ext' for
        each `ext' in EXTENSIONS.  When `ext' is preceded by a `!' or a
        `^', skip files whose filename extensions matches `ext', same as
        --exclude='*.ext'.  This option may be repeated and may be combined
        with options -g, -M and -t to expand the recursive search.
-t TYPES, --file-type=TYPES
        Search only files associated with TYPES, a comma-separated list of
        file types.  Each file type corresponds to a set of filename
        extensions passed to option -O and filenames passed to option -g.
        For capitalized file types, the search is expanded to include files
        with matching file signature magic bytes, as if passed to option
        -M.  When a type is preceded by a `!' or a `^', excludes files of
        the specified type.  This option may be repeated.
--stats
        Output statistics on the number of files and directories searched,
        and the inclusion and exclusion constraints applied.

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

To recursively list all non-empty files in the working directory:

ug -r -l ''

To list all non-empty files in the working directory but not deeper (since a FILE argument is given, in this case . for the working directory):

ug -l '' .

To list all non-empty files in directory mydir but not deeper (since a FILE argument is given):

ug -l '' mydir

To list all non-empty files in directory mydir and deeper while following symlinks:

ug -R -l '' mydir

To recursively list all non-empty files on the path specified, while visiting subdirectories only, i.e. directories mydir/ and subdirectories at one level deeper mydir/*/ are visited (note that -2 -l can be abbreviated to -l2):

ug -2 -l '' mydir

To recursively list all non-empty files in directory mydir, not following any symbolic links (except when on the command line such as mydir):

ug -rl '' mydir

To recursively list all Makefiles matching the text CPP:

ug -l -tmake 'CPP'

To recursively list all Makefile.* matching bin_PROGRAMS:

ug -l -g'Makefile.*' 'bin_PROGRAMS'

To recursively list all non-empty files with extension .sh, with -Osh:

ug -l -Osh ''

To recursively list all shell scripts based on extensions and shebangs with -tShell:

ug -l -tShell ''

To recursively list all shell scripts based on extensions only with -tshell:

ug -l -tshell ''

Boolean query patterns with -%, -%%, --and, --not

--bool, -%, -%%
        Specifies Boolean query patterns.  A Boolean query pattern is
        composed of `AND', `OR', `NOT' operators and grouping with `(' `)'.
        Spacing between subpatterns is the same as `AND', `|' is the same
        as `OR' and a `-' is the same as `NOT'.  The `OR' operator binds
        more tightly than `AND'.  For example, --bool 'A|B C|D' matches
        lines with (`A' or `B') and (`C' or `D'), --bool 'A -B' matches
        lines with `A' and not `B'.  Operators `AND', `OR', `NOT' require
        proper spacing.  For example, --bool 'A OR B AND C OR D' matches
        lines with (`A' or `B') and (`C' or `D'), --bool 'A AND NOT B'
        matches lines with `A' without `B'.  Quoted subpatterns are matched
        literally as strings.  For example, --bool 'A "AND"|"OR"' matches
        lines with `A' and also either `AND' or `OR'.  Parentheses are used
        for grouping.  For example, --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.
--files
        Boolean file matching mode, the opposite of --lines.  When combined
        with option --bool, matches a file if all Boolean conditions are
        satisfied.  For example, --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.
--lines
        Boolean line matching mode for option --bool, the default mode.
--and [[-e] PATTERN] ... -e PATTERN
        Specify additional patterns to match.  Patterns must be specified
        with -e.  Each -e PATTERN following this option is considered an
        alternative pattern to match, i.e. each -e is interpreted as an OR
        pattern.  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, and --bool.
--andnot [[-e] PATTERN] ...
        Combines --and --not.  See also options --and, --not, and --bool.
--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, and --bool.
--stats
        Output statistics on the number of files and directories searched,
        and the inclusion and exclusion constraints applied.

Note that the --and, --not, and --andnot options require -e PATTERN.

The -% option makes all patterns Boolean-based, supporting the following logical operations listed from the highest level of precedence to the lowest:

• x and y are subpatterns that do not start with the special symbols |, -, and ( (use quotes or a \ escape to match these);

• - and NOT are the same and take precedence over OR, which means that -x|y == (-x)|y for example.

• | and OR are the same and take precedence over AND, which means that x y|z == x (y|z) for example;

The --stats option displays the Boolean queries in human-readable form converted to CNF (Conjunctive Normal Form), after the search is completed. To show the CNF without a search, read from standard input terminated by an EOF, like echo | ugrep -% '...' --stats.

Subpatterns are color-highlighted in the output, except those negated with NOT (a NOT subpattern may still show up in a matching line when using an OR-NOT pattern like x|-y). Note that subpatterns may overlap. In that case only the first matching subpattern is color-highlighted.

Multiple lines may be matched when subpatterns match newlines. There is one exception however: subpatterns ending with (?=X) lookaheads may not match when X spans multiple lines.

Empty patterns match any line (grep standard). Therefore, -% 'x|""|y' matches everything and x and y are not color-highlighted. Option -y should be used to show every line as context, for example -y 'x|y'.

Fzf-like interactive querying (Boolean search with fixed strings with fuzzy matching to allow e.g. up to 4 extra characters matched with -Z+4 in words with -w), press TAB and ALT-y to view a file with matches. Press SHIFT-TAB and ALT-l to go back to the list of matching files:

ug -Q -%% -l -w -F -Z+4 --sort=best

To recursively find all files containing both hot and dog anywhere in the file with option --files:

ug -%% 'hot dog'
ug --files -e hot --and dog

To find lines containing both hot and dog in myfile.txt:

ug -% 'hot dog' myfile.txt
ug -e hot --and dog myfile.txt

To find lines containing place and then also hotdog or taco (or both) in myfile.txt:

ug -% 'hotdog|taco place' myfile.txt
ug -e hotdog -e taco --and place myfile.txt

Same, but exclude lines matching diner:

ug -% 'hotdog|taco place -diner' myfile.txt
ug -e hotdog -e taco --and place --andnot diner myfile.txt

To find lines with diner or lines that match both fast and food but not bad in myfile.txt:

ug -% 'diner|(fast food -bad)' myfile.txt

To find lines with fast food (exactly) or lines with diner but not bad or old in myfile.txt:

ug -% '"fast food"|diner -bad -old' myfile.txt

Same, but using a different Boolean expression that has the same meaning:

ug -% '"fast food"|diner -(bad|old)' myfile.txt

To find lines with diner implying good in myfile.txt (that is, show lines with good without diner and show lines with diner but only those with good, which is logically implied!):

ug -% 'good|-diner' myfile.txt
ug -e good --not diner myfile.txt

To find lines with foo and -bar and "baz" in myfile.txt (not that - and " should be matched using \ escapes and with --and -e -bar):

ug -% 'foo \-bar \"baz\"' myfile.txt
ug -e foo --and -e -bar --and '"baz"' myfile.txt

To search myfile.cpp for lines with TODO or FIXME but not both on the same line, like XOR:

ug -% 'TODO|FIXME -(TODO FIXME)' myfile.cpp
ug -e TODO -e FIXME --and --not TODO --not FIXME myfile.cpp

Search this but not that with -v, -e, -N, -f, -L, -w, -x

-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 begins with a dash (`-'), or to specify a pattern
        after option -f or after the FILE arguments.
-f FILE, --file=FILE
        Read newline-separated patterns from FILE.  White space in patterns
        is significant.  Empty lines in FILE are ignored.  If FILE does not
        exist, the GREP_PATH environment variable is used as path to FILE.
        If that fails, looks for FILE in /usr/local/share/ugrep/pattern.
        When FILE is a `-', standard input is read.  This option may be
        repeated.
-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.
-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.
-v, --invert-match
        Selected lines are those not matching any of the specified
        patterns.
-w, --word-regexp
        The PATTERN is searched for as a word, such that the matching text
        is preceded by a non-word character and is followed by a non-word
        character.  Word-like characters are Unicode letters, digits and
        connector punctuations such as underscore.
-x, --line-regexp
        Select only those matches that exactly match the whole line, as if
        the patterns are surrounded by ^ and $.

Search non-Unicode files with --encoding

--encoding=ENCODING
        The encoding format of the input.  The default ENCODING is binary
        and UTF-8 which are the same.  Note that option -U specifies binary
        PATTERN matching (text matching is the default.)

Matching multiple lines of text

-o, --only-matching
        Output only the matching part of lines.  If -A, -B or -C is
        specified, fits the match and its context on a line within the
        specified number of columns.

Multiple lines may be matched by patterns that match newline characters. Use option -o to output the match only, not the full lines(s) that match.

To match a \n line break, include \n in the pattern to match the LF character. If you want to match \r\n and \n line breaks, use \r?\n or simply use \R to match any Unicode line break \r\n, \r, \v, \f, \n, U+0085, U+2028 and U+2029.

To match C/C++ /*...*/ multi-line comments:

ug '/\*(.*\n)*?.*\*+\/' myfile.cpp

To match C/C++ comments using the predefined c/comments patterns with -f c/comments, restricted to the matching part only with option -o:

ug -of c/comments myfile.cpp

Same as sed -n '/begin/,/end/p': to match all lines between a line containing begin and the first line after that containing end, using lazy repetition:

ug -o '.*begin(.|\n)*?end.*' myfile.txt

Displaying match context with -A, -B, -C, -y, and --width

-A NUM, --after-context=NUM
        Output NUM lines of trailing context after matching lines.  Places
        a --group-separator between contiguous groups of matches.  If -o is
        specified, output the match with context to fit NUM columns after
        the match or shortens the match.  See also options -B, -C and -y.
-B NUM, --before-context=NUM
        Output NUM lines of leading context before matching lines.  Places
        a --group-separator between contiguous groups of matches.  If -o is
        specified, output the match with context to fit NUM columns before
        the match or shortens the match.  See also options -A, -C and -y.
-C NUM, --context=NUM
        Output NUM lines of leading and trailing context surrounding each
        matching line.  Places a --group-separator between contiguous
        groups of matches.  If -o is specified, output the match with
        context to fit NUM columns before and after the match or shortens
        the match.  See also options -A, -B and -y.
-y, --any-line
        Any line is output (passthru).  Non-matching lines are output as
        context with a `-' separator.  See also options -A, -B, and -C.
--width[=NUM]
        Truncate the output to NUM visible characters per line.  The width
        of the terminal window is used if NUM is not specified.  Note that
        double wide characters in the output may result in wider lines.
-o, --only-matching
        Output only the matching part of lines.  If -A, -B or -C is
        specified, fits the match and its context on a line within the
        specified number of columns.

To display two lines of context before and after a matching line:

ug -C2 'FIXME' myfile.cpp

To show three lines of context after a matched line:

ug -A3 'FIXME.*' myfile.cpp:

To display one line of context before each matching line with a C function definition (C names are non-Unicode):

ug -B1 -f c/functions myfile.c

To display one line of context before each matching line with a C++ function definition (C++ names may be Unicode):

ug -B1 -f c++/functions myfile.cpp

To display any non-matching lines as context for matching lines with -y:

ug -y -f c++/functions myfile.cpp

To display a hexdump of a matching line with one line of hexdump context:

ug -C1 -UX '\xaa\xbb\xcc' a.out

Context within a line is displayed with option -o with a context option:

ug -o -C20 'pattern' myfile.cpp

Same, but with pretty output with headings, line numbers and column numbers (-k) and showing context:

ug --pretty -oC20 'pattern' myfile.cpp

Searching source code using -f, -g, -O, and -t

-f FILE, --file=FILE
        Read newline-separated patterns from FILE.  White space in patterns
        is significant.  Empty lines in FILE are ignored.  If FILE does not
        exist, the GREP_PATH environment variable is used as path to FILE.
        If that fails, looks for FILE in /usr/local/share/ugrep/pattern.
        When FILE is a `-', standard input is read.  This option may be
        repeated.
--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.
-g GLOBS, --glob=GLOBS
        Search only 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.  Otherwise basenames are matched.
        When `glob' ends with a `/', directories are matched, same as
        --include-dir='glob' and --exclude-dir='glob'.  A leading `/'
        matches the working directory.  This option may be repeated and may
        be combined with options -M, -O and -t to expand searches.  See
        `ugrep --help globs' and `man ugrep' section GLOBBING for details.
-O EXTENSIONS, --file-extension=EXTENSIONS
        Search only files whose filename extensions match the specified
        comma-separated list of EXTENSIONS, same as --include='*.ext' for
        each `ext' in EXTENSIONS.  When `ext' is preceded by a `!' or a
        `^', skip files whose filename extensions matches `ext', same as
        --exclude='*.ext'.  This option may be repeated and may be combined
        with options -g, -M and -t to expand the recursive search.
-t TYPES, --file-type=TYPES
        Search only files associated with TYPES, a comma-separated list of
        file types.  Each file type corresponds to a set of filename
        extensions passed to option -O and filenames passed to option -g.
        For capitalized file types, the search is expanded to include files
        with matching file signature magic bytes, as if passed to option
        -M.  When a type is preceded by a `!' or a `^', excludes files of
        the specified type.  This option may be repeated.
--stats
        Output statistics on the number of files and directories searched,
        and the inclusion and exclusion constraints applied.

The file types are listed with ugrep -tlist. The list is based on established filename extensions and "magic bytes". If you have a file type that is not listed, use options -O and/or -M. You may want to define an alias, e.g. alias ugft='ugrep -Oft' as a shorthand to search files with filename suffix .ft.

To recursively display function definitions in C/C++ files (.h, .hpp, .c, .cpp etc.) with line numbers with -tc++, -o, -n, and -f c++/functions:

ug -on -tc++ -f c++/functions

To recursively display function definitions in .c and .cpp files with line numbers with -Oc,cpp, -o, -n, and -f c++/functions:

ug -on -Oc,cpp -f c++/functions

To recursively list all shell files with -tShell to match filename extensions and files with shell shebangs, except files with suffix .sh:

ug -l -tShell -O^sh ''

To recursively list all non-shell files with -t^Shell:

ug -l -t^Shell ''

To recursively list all shell files with shell shebangs that have no shell filename extensions:

ug -l -tShell -t^shell ''

To search for lines with FIXME in C/C++ comments, excluding FIXME in multi-line strings:

ug -n 'FIXME' -f c++/zap_strings myfile.cpp

To read patterns TODO and FIXME from standard input to match lines in the input, while excluding matches in C++ strings:

ug -on -f - -f c++/zap_strings myfile.cpp <<END
TODO
FIXME
END

To display XML element and attribute tags in an XML file, restricted to the matching part with -o, excluding tags that are placed in (multi-line) comments:

ug -o -f xml/tags -f xml/zap_comments myfile.xml

Searching compressed files and archives with -z

-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 in archives are output in braces.  When used
        with option --zmax=NUM, searches the contents of compressed files
        and archives stored within archives up to NUM levels.  When -g, -O,
        -M, or -t is specified, searches archives for files that match the
        specified globs, filename extensions, file signature magic bytes,
        or file types, respectively; a side-effect of these options is that
        the compressed files and archives searched are only those with
        filename extensions that match 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).
--zmax=NUM
        When used with option -z (--decompress), 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 are 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.  Increasing NUM values gradually degrades performance.

Files compressed with gzip (.gz), compress (.Z), bzip2 (.bz, .bz2, .bzip2), lzma (.lzma), xz (.xz), lz4 (.lz4), zstd (.zst, .zstd), brotli (.br) and bzip3 (.bz3) are searched with option -z when the corresponding libraries are installed and compiled with ugrep. This option does not require files to be compressed. Uncompressed files are searched also, although slower.

Find files by file signature and shebang "magic bytes" with -M, -O and -t

--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.
-M MAGIC, --file-magic=MAGIC
        Only files matching the signature pattern MAGIC are searched.  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 to expand the search.  Every file on the
        search path is read, making searches potentially more expensive.
-O EXTENSIONS, --file-extension=EXTENSIONS
        Search only files whose filename extensions match the specified
        comma-separated list of EXTENSIONS, same as --include='*.ext' for
        each `ext' in EXTENSIONS.  When `ext' is preceded by a `!' or a
        `^', skip files whose filename extensions matches `ext', same as
        --exclude='*.ext'.  This option may be repeated and may be combined
        with options -g, -M and -t to expand the recursive search.
-t TYPES, --file-type=TYPES
        Search only files associated with TYPES, a comma-separated list of
        file types.  Each file type corresponds to a set of filename
        extensions passed to option -O and filenames passed to option -g.
        For capitalized file types, the search is expanded to include files
        with matching file signature magic bytes, as if passed to option
        -M.  When a type is preceded by a `!' or a `^', excludes files of
        the specified type.  This option may be repeated.
-g GLOBS, --glob=GLOBS
        Search only 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.  Otherwise basenames are matched.
        When `glob' ends with a `/', directories are matched, same as
        --include-dir='glob' and --exclude-dir='glob'.  A leading `/'
        matches the working directory.  This option may be repeated and may
        be combined with options -M, -O and -t to expand searches.  See
        `ugrep --help globs' and `man ugrep' section GLOBBING for details.
--stats
        Output statistics on the number of files and directories searched,
        and the inclusion and exclusion constraints applied.

To recursively list all files that start with #! shebangs:

ug -l -M'#!' ''

To recursively list all files that start with # but not with #! shebangs:

ug -l -M'#' -M'^#!' ''

To recursively list all Python files (extension .py or a shebang) with -tPython:

ug -l -tPython ''

To recursively list all non-shell files with -t^Shell:

ug -l -t^Shell ''

To recursively list Python files (extension .py or a shebang) that have import statements, including hidden files with -.:

ug -l. -tPython -f python/imports

Fuzzy search with -Z

-Z[best][+-~][MAX], --fuzzy=[best][+-~][MAX]
        Fuzzy mode: 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.  No whitespace may be given between -Z and its argument.

The beginning of a pattern always matches the first character of an approximate match as a practical strategy to prevent many false "randomized" matches for short patterns. This also greatly improves search speed. Make the first character optional to optionally match it, e.g. p?attern or use a dot as the start of the pattern to match any wide character (but this is slow).

Line feed (\n) and NUL (\0) characters are never deleted or substituted to ensure that fuzzy matches do not extend the pattern match beyond the number of lines specified by the regex pattern.

Option -U (--ascii or --binary) restricts fuzzy matches to ASCII and binary only with edit distances measured in bytes. Otherwise, fuzzy pattern matching is performed with Unicode patterns and edit distances are measured in Unicode characters.

Option --sort=best orders files by best match. Files with at least one exact match anywhere in the file are shown first, followed by files with approximate matches in increasing minimal edit distance order. That is, ordered by the minimum error (edit distance) found among all approximate matches per file.

To recursively search for approximate matches of the word foobar with -Z, i.e. approximate matching with one error, e.g. Foobar, foo_bar, foo bar, fobar and other forms with one missing, one extra or one deleted character:

ug -Z 'foobar'

Same, but matching words only with -w and ignoring case with -i:

ug -Z -wi 'foobar'

Same, but permit up to 2 insertions with -Z+2, no deletions/substitutions (matches up to 2 extra characters, such as foos bar), insertions-only offers the fastest fuzzy matching method:

ug -Z+3 -wi 'foobar'

Same, but sort matches from best (at least one exact match or fewest fuzzy match errors) to worst:

ug -Z+3 -wi --sort=best 'foobar'

Note: because sorting by best match requires two passes over the input files, the efficiency of concurrent searching is significantly reduced.

Same, but with customized formatting to show the edit distance "cost" of the approximate matches with format field %Z and %F to show the pathname:

ug -Z+3 -wi --format='%F%Z:%O%~' --sort=best 'foobar'

Same, but this time count the matches with option -c and display them with a custom format using %m, where %Z is the average cost per match:

ug -c -Z+3 -wi --format='%F%Z:%m%~' --sort=best 'foobar'

Note: options -c and -l do not report a meaningful %Z value in the --format output, because %Z is the edit distance cost of a single match.

Search hidden files with -.

--hidden, -.
        Search hidden files and directories.

To recursively search the working directory, including hidden files and directories, for the word login in shell scripts:

ug -. -tShell 'login'

Using filter utilities to search documents with --filter

--filter=COMMANDS
        Filter 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' are
        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.  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.

The --filter option associates one or more filter utilities with specific filename extensions. A filter utility is selected based on the filename extension and executed by forking a process: the utility's standard input reads the open input file and the utility's standard output is searched. When a % is specified as an option to the utility, the % is expanded to the pathname of the file to open and read by the utility.

When a specified utility is not found on the system, an error message is displayed. When a utility fails to produce output, e.g. when the specified options for the utility are invalid, the search is silently skipped.

Filtering does not apply to files stored in archives and compressed files. A filter is usually applied to a file that is physically stored in the file system. Archived files are not physically stored.

Common filter utilities are cat (concat, pass through), head (select first lines or bytes) tr (translate), iconv and uconv (convert), and more advanced utilities, such as:

Searching and displaying binary files with -U, -W, and -X

--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.
-U, --ascii, --binary
        Disables Unicode matching for binary file matching, forcing PATTERN
        to match bytes, not Unicode characters.  For example, -U '\xa3'
        matches byte A3 (hex) instead of the Unicode code point U+00A3
        represented by the UTF-8 sequence C2 A3.  See also --dotall.
-W, --with-hex
        Output binary matches in hexadecimal, leaving text matches alone.
        This option is equivalent to the --binary-files=with-hex option.
        To omit the matching line from the hex output, use both options -W
        and --hexdump.  See also options -U.
-X, --hex
        Output matches and matching lines in hexadecimal.  This option is
        equivalent to the --binary-files=hex option.  To omit the matching
        line from the hex output use option --hexdump.  See also option -U.
--dotall
        Dot `.' in regular expressions matches anything, including newline.
        Note that `.*' matches all input and should not be used.

Note that --hexdump differs from -X by omitting the matching line from the hex output, showing only the matching pattern using a minimal number of hex lines. Additional match context hex lines are output with the -ABC context options or with --hexdump=C3 to output 3 hex lines as context, for example.

To search a file for ASCII words, displaying text lines as usual while binary content is shown in hex with -U and -W:

ug -UW '\w+' myfile

To hexdump an entire file as a match with -X:

ug -X '' myfile

To hexdump an entire file with -X, displaying line numbers and byte offsets with -nb (here with -y to display all line numbers):

ug -Xynb '' myfile

To hexdump lines containing one or more \0 in a (binary) file using a non-Unicode pattern with -U and -X:

ug -UX '\x00+' myfile

Same, but hexdump the entire file as context with -y (note that this line-based option does not permit matching patterns with newlines):

ug -UX -y '\x00+' myfile

Same, compacted to 32 bytes per line without the character column:

ug -UX -y '\x00+' myfile

To match the binary pattern A3..A3. (hex) in a binary file without Unicode pattern matching (which would otherwise match \xaf as a Unicode character U+00A3 with UTF-8 byte sequence C2 A3) and display the results in compact hex with --hexdump with pager:

ug --pager --hexdump -U '\xa3[\x00-\xff]{2}\xa3[\x00-\xff]' a.out

Same, but using option --dotall to let . match any byte, including newline that is not matched by dot (the default as required by grep):

ug --dotall --pager --hexdump -U '\xa3.{2}\xa3.' a.out

Ignore binary files with -I

-I      Ignore matches in binary files.  This option is equivalent to the
        --binary-files=without-match option.

To recursively search without following symlinks and ignoring binary files:

ug -rl -I 'xyz'

To ignore specific binary files with extensions such as .exe, .bin, .out, .a, use --exclude or --exclude-from:

ug -rl --exclude-from=ignore_binaries 'xyz'

where ignore_binaries is a file containing a glob on each line to ignore matching files, e.g. *.exe, *.bin, *.out, *.a. Because the command is quite long to type, an alias for this is recommended, for example ugs (ugrep source):

alias ugs="ugrep --exclude-from=~/ignore_binaries"
ugs -rl 'xyz'

Ignoring .gitignore-specified files with --ignore-files

--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.

Option --ignore-files looks for .gitignore, or the specified FILE, in recursive searches. When .gitignore, or the specified FILE, is found while traversing directory tree branches down, the .gitignore file is used to temporarily extend the previous exclusions with the additional globs in .gitignore to apply the combined exclusions to the directory tree rooted at the .gitignore location. Use --stats to show the selection criteria applied to the search results and the locations of each FILE found. To avoid confusion, files and directories specified as command-line arguments to ugrep are never ignored.

Note that exclude glob patterns take priority over include glob patterns when specified with command line options. By contrast, negated glob patterns specified with ! in --ignore-files files take priority. This effectively overrides the exclusions and resolves conflicts in favor of listing matching files that are explicitly specified as exceptions and should be included in the search.

Using gitignore-style globs to select directories and files to search

-g GLOBS, --glob=GLOBS
        Search only 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.  Otherwise basenames are matched.
        When `glob' ends with a `/', directories are matched, same as
        --include-dir='glob' and --exclude-dir='glob'.  A leading `/'
        matches the working directory.  This option may be repeated and may
        be combined with options -M, -O and -t to expand searches.  See
        `ugrep --help globs' and `man ugrep' section GLOBBING for details.
--exclude=GLOB
        Skip files whose name matches GLOB using wildcard matching, 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
        Exclude directories whose name matches GLOB from recursive
        searches, 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.  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
        Read the globs from FILE and skip 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.
--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.
--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.
--include=GLOB
        Search only files whose name matches GLOB using wildcard matching,
        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
        included as if --include-dir is specified.  Otherwise files are
        included.  Note that --exclude patterns take priority over
        --include patterns.  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 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.  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 can 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.
-O EXTENSIONS, --file-extension=EXTENSIONS
        Search only files whose filename extensions match the specified
        comma-separated list of EXTENSIONS, same as --include='*.ext' for
        each `ext' in EXTENSIONS.  When `ext' is preceded by a `!' or a
        `^', skip files whose filename extensions matches `ext', same as
        --exclude='*.ext'.  This option may be repeated and may be combined
        with options -g, -M and -t to expand the recursive search.
--stats
        Output statistics on the number of files and directories searched,
        and the inclusion and exclusion constraints applied.

Including or excluding mounted file systems from searches

--exclude-fs=MOUNTS
        Exclude 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, only descends into the
        file systems associated with the specified file and directory
        search targets, i.e. excludes all other file systems.  Note that
        --exclude-fs=MOUNTS take priority over --include-fs=MOUNTS.  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.

These options control recursive searches across file systems by comparing device numbers. Mounted devices and symbolic links to files and directories located on mounted file systems may be included or excluded from recursive searches by specifying a mount point or a pathname of any directory on the file system to specify the applicable file system.

Note that a list of mounted file systems is typically stored in /etc/mtab.

To restrict recursive searches to the file system(s) of the search targets only, without crossing into other file systems (similar to find option -x):

ug -rl --exclude-fs 'xyz' /sys /var

To restrict recursive searches to the file system of the working directory only, without crossing into other file systems:

ug -l --include-fs 'xyz'

In fact, for this case we can use --exclude-fs because we search the working directory as the target and we want to exclude all other file systems:

ug -l --exclude-fs 'xyz'

To exclude the file systems mounted at /dev and /proc from recursive searches:

ug -l --exclude-fs=/dev,/proc 'xyz'

To only include the file system associated with drive d: in recursive searches:

ug -l --include-fs=d:/ 'xyz'

To exclude fuse and tmpfs type file systems from recursive searches:

exfs=`ugrep -w -e fuse -e tmpfs /etc/mtab | ugrep -P '^\S+ (\S+)' --format='%,%1'`
ug -l --exclude-fs="$exfs" 'xyz'

Counting the number of matches with -c and -co

-c, --count
        Only a count of selected lines is written to standard output.
        If -o or -u is specified, counts the number of patterns matched.
        If -v is specified, counts the number of non-matching lines.  If
        -m1, (with a comma or --min-count=1) is specified, counts only
        matching files without outputting zero matches.

To count the number of lines in a file:

ug -c '' myfile.txt

To count the number of lines with TODO:

ug -c -w 'TODO' myfile.cpp

To count the total number of TODO in a file, use -c and -o:

ug -co -w 'TODO' myfile.cpp

To count the number of ASCII words in a file:

ug -co '[[:word:]]+' myfile.txt

To count the number of ASCII and Unicode words in a file:

ug -co '\w+' myfile.txt

To count the number of Unicode characters in a file:

ug -co '\p{Unicode}' myfile.txt

To count the number of zero bytes in a file:

ug -UX -co '\x00' image.jpg

Displaying file, line, column, and byte offset info with -H, -n, -k, -b, and -T

-b, --byte-offset
        The offset in bytes of a matched line is displayed in front of the
        respective matched line.  When used with option -u, displays the
        offset in bytes of each pattern matched.  Byte offsets are exact
        for ASCII, UTF-8, and raw binary input.  Otherwise, the byte offset
        in the UTF-8 converted input is displayed.
-H, --with-filename
        Always print the filename with output lines.  This is the default
        when there is more than one file to search.
-k, --column-number
        The column number of a matched pattern is displayed in front of the
        respective matched line, starting at column 1.  Tabs are expanded
        when columns are counted, see option --tabs.
-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.
-T, --initial-tab
        Add a tab space to separate the file name, line number, column
        number, and byte offset with the matched line.

To display the file name -H, line -n, and column -k numbers of matches in myfile.cpp, with spaces and tabs to space the columns apart with -T:

ug -THnk 'main' myfile.cpp

To display the line with -n of word main in myfile.cpp:

ug -nw 'main' myfile.cpp

To display the entire file myfile.cpp with line -n numbers:

ug -n '' myfile.cpp

To recursively search for C++ files with main, showing the line and column numbers of matches with -n and -k:

ug -r -nk -tc++ 'main'

To display the byte offset of matches with -b:

ug -r -b -tc++ 'main'

To display the line and column numbers of matches in XML with --xml:

ug -r -nk --xml -tc++ 'main'

Displaying colors with --color and paging the output with --pager

--color[=WHEN], --colour[=WHEN]
        Mark up the matching text with the expression stored in the
        GREP_COLOR or GREP_COLORS environment variable.  The possible
        values of 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
        Use 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 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).
--tag[=TAG[,END]]
        Disables colors to mark up matches with TAG.  END marks the end of
        a match if specified, otherwise TAG.  The default is `___'.
--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.
--pretty[=WHEN]
        When output is sent to a terminal, enables --color, --heading, -n,
        --sort, --tree and -T when not explicitly disabled.  WHEN can be
        `never', `always', or `auto'.  The default is `auto'.
--tree, -^
        Output directories with matching files in a tree-like format for
        option -c or --count, -l or --files-with-matches, -L or
        --files-without-match.  This option is enabled by --pretty when the
        output is sent to a terminal.

To change the color palette, set the GREP_COLORS environment variable or use --colors=COLORS. The 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:

Multiple SGR codes may be specified for a single parameter when separated by a semicolon, e.g. mt=1;31 specifies bright red. The following SGR codes are available on most color terminals:

Output matches in JSON, XML, CSV, C++

--cpp   Output file matches in C++.  See also options --format and -u.
--csv   Output file matches in CSV.  If -H, -n, -k, or -b is specified,
        additional values are output.  See also options --format and -u.
--json  Output file matches in JSON.  If -H, -n, -k, or -b is specified,
        additional values are output.  See also options --format and -u.
--xml   Output file matches in XML.  If -H, -n, -k, or -b is specified,
        additional values are output.  See also options --format and -u.

To recursively search for lines with TODO and display C++ file matches in JSON with line number properties:

ug -tc++ -n --json 'TODO'

To recursively search for lines with TODO and display C++ file matches in XML with line and column number attributes:

ug -tc++ -nk --xml 'TODO'

To recursively search for lines with TODO and display C++ file matches in CSV format with file pathname, line number, and column number fields:

ug -tc++ --csv -Hnk 'TODO'

To extract a table from an HTML file and put it in C/C++ source code using -o:

ug -o --cpp '<tr>.*</tr>' index.html > table.cpp

Customized output with --format

--format=FORMAT
        Output FORMAT-formatted matches.  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.
-P, --perl-regexp
        Interpret PATTERN as a Perl regular expression.

Use option -P to use group captures and backreferences. Capturing groups in regex patterns are parenthesized expressions (pattern). The first group is referenced in FORMAT by %1, the second by %2 and so on. Named captures are of the form (?<NAME>pattern) and are referenced in FORMAT by %[NAME]#.

The following output formatting options may be used. The FORMAT string %-fields are listed in a table further below:

The following tables show the formatting options corresponding to --csv, --json, and --xml.

--csv

--json

--xml

--only-line-number

The following fields may be used in the FORMAT string:

Note:

• Formatted output is written without a terminating newline, unless %~ is explicitly specified in the format string.
• Option -o changes the output of the %O and %Q fields to output the match only.
• Options -c, -l and -o change the output of %C, %J, %X and %Y accordingly
• 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, when option -H is used.
• Numeric fields such as %n are padded with spaces when %{width}n is specified.
• Matching line fields such as %O are cut to width when %{width}O is specified or when %{-width}O is specified to cut from the end of the line.
• Character context on a matching line before or after a match is output when %{-width}o or %{+width}o is specified for match fields such as %o, where %{width}o without a +/- sign cuts the match to the specified width.
• Fields %[SEP]$ and %u are switches and do not write anything to the output.
• The separator used by %F, %H, %N, %K, %B, %S, and %G may be changed by preceding the field with a %[SEP]$. When [SEP] is not provided, reverts the separator to the default separator or the separator specified by --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. When field %u is found anywhere in the specified format string, matching lines are output only once unless option -u, --ungroup is used or when a newline is matched.
• The group capture index value output by %g corresponds to the index of the sub-pattern matched among the alternations in the pattern when option -P is not used. For example foo|bar matches foo with index 1 and bar with index 2. With option -P, the index corresponds to the number of the first group captured in the specified pattern.
• The strings specified in the list %[TEXT1|TEXT2|...]G and %[TEXT1|TEXT2|...]g should correspond to the group capture index (see the note above), i.e. TEXT1 is output for index 1, TEXT2 is output for index 2, and so on. If the list is too short, the index value is output or the name of a named group capture is output.
• Option -T and --pretty add right-justifying spacing to fields %N and %K if no leading [TEXT] part is specified.
• Field %+ may be used in --format-open to output the pathname heading and a newline break, respectively. Field %+ suppresses %a, %F, %f, %H, %h and %p output.

To output matching lines faster by omitting the header output and binary match checks, using --format with field %O (output matching line as is) and field %~ (output newline):

ug --format='%O%~' 'href=' index.html

Same, but also displaying the line and column numbers:

ug --format='%n%k: %O%~' 'href=' index.html

Same, but display a line at most once when matching multiple patterns, unless option -u is used:

ug --format='%u%n%k: %O%~' 'href=' index.html

To string together a list of unique line numbers of matches, separated by commas with field %,:

ug --format='%u%,%n' 'href=' index.html

To output the matching part of a line only with field %o (or option -o with field %O):

ug --format='%o%~' "href=[\"'][^\"'][\"']" index.html

To string together the pattern matches as CSV-formatted strings with field %v separated by commas with field %,:

ug --format='%,%v' "href=[\"'][^\"'][\"']" index.html

To output matches in CSV (comma-separated values), the same as option --csv (works with options -H, -n, -k, -b to add CSV values):

ug --format='"%[,]$%H%N%K%B%V%~%u"' 'href=' index.html

To output matches in AckMate format:

ug --format=":%f%~%n;%k %w:%O%~" 'href=' index.html

To output the sub-pattern indices 1, 2, and 3 on the left to the match for the three patterns foo, bar, and baz in file foobar.txt:

ug --format='%g: %o%~' 'foo|bar|baz' foobar.txt

Same, but using a file foos containing three lines with foo, bar, and baz, where option -F is used to match strings instead of regex:

ug -F -f foos --format='%g: %o%~' foobar.txt

To output one, two, and a word for the sub-patterns [fF]oo, [bB]ar, and any other word \w+, respectively, using argument [one|two|a word] with field %g indexed by sub-pattern (or group captures with option -P):

ug --format='%[one|two|a word]g%~' '([fF]oo)|([bB]ar)|(\w+)' foobar.txt

To output a list of group capture indices with %G separated by the word and instead of the default colons with %[ and ]$, followed by the matching line:

ug -P --format='%[ and ]$%G%$%s%O%~' '(foo)|(ba((r)|(z)))' foobar.txt

Same, but showing names instead of numbers:

ug -P --format='%[ and ]$%[foo|ba|r|z]G%$%s%O%~' '(foo)|(ba(?:(r)|(z)))' foobar.txt

Note that option -P is required for general use of group captures for sub-patterns. Named sub-pattern matches may be used with PCRE2 and shown in the output:

ug -P --format='%[ and ]$%G%$%s%O%~' '(?P<foo>foo)|(?P<ba>ba(?:(?P<r>r)|(?P<z>z)))' foobar.txt

Replacing matches with -P --replace and --format using backreferences

--replace=FORMAT
        Replace matching patterns in the output by the specified 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 option --format,
        `ugrep --help format' and `man ugrep' section FORMAT for details.
-y, --any-line
        Any line is output (passthru).  Non-matching lines are output as
        context with a `-' separator.  See also options -A, -B, and -C.
-P, --perl-regexp
        Interpret PATTERN as a Perl regular expression.
--format=FORMAT
        Output FORMAT-formatted matches.  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.

Limiting the number of matches with -1,-2...-9, -K, -m, and --max-files

--depth=[MIN,][MAX], -1, -2, -3, ... -9, -10, -11, -12, ...
        Restrict recursive searches from MIN to MAX directory levels deep,
        where -1 (--depth=1) searches the specified path without recursing
        into subdirectories.  Note that -3 -5, -3-5, and -35 search 3 to 5
        levels deep.  Enables -r if -R or -r is not specified.
-K [MIN,][MAX], --range=[MIN,][MAX], --min-line=MIN, --max-line=MAX
        Start searching at line MIN, stop at line MAX when specified.
-m [MIN,][MAX], --min-count=MIN, --max-count=MAX
        Require MIN matches, stop after MAX matches when specified.  Output
        MIN to MAX matches.  For example, -m1 outputs the first match and
        -cm1, (with a comma) counts nonzero matches.  If -u is specified,
        each individual match counts.  See also option -K.
--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, the number of threads spawned is limited to NUM.
--sort[=KEY]
        Displays matching files in the order specified by KEY in recursive
        searches.  Normally the ug command sorts by name whereas the ugrep
        batch command displays matches in no particular order to improve
        performance.  The sort KEY can be `name' to sort by pathname
        (default), `best' to sort by best match with option -Z (sort by
        best match requires two passes over files, which is expensive),
        `size' to sort by file size, `used' to sort by last access time,
        `changed' to sort by last modification time and `created' to sort
        by creation time.  Sorting is reversed with `rname', `rbest',
        `rsize', `rused', `rchanged', or `rcreated'.  Archive contents are
        not sorted.  Subdirectories are sorted and displayed after matching
        files.  FILE arguments are searched in the same order as specified.

To show only up to the first 10 matching lines with FIXME in C++ files in the working directory and all subdirectories below:

ug -r -m10 -tc++ FIXME

Same, but recursively search up to two directory levels, meaning that ./ and ./sub/ are visited but not deeper:

ug -2 -m10 -tc++ FIXME

To show only the first two files that have one or more matches of FIXME in the list of files sorted by pathname, using --max-files=2:

ug --sort -r --max-files=2 -tc++ FIXME

To search file install.sh for the occurrences of the word make after the first line, we use -K with line number 2 to start searching, where -n shows the line numbers in the output:

ug -n -K2 -w make install.sh

Same, but restricting the search to lines 2 to 40 (inclusive):

ug -n -K2,40 -w make install.sh

Same, but showing all lines 2 to 40 with -y:

ug -y -n -K2,40 -w make install.sh

Same, but showing only the first four matching lines after line 2, with one line of context:

ug -n -C1 -K2 -m4 -w make install.sh

Matching empty patterns with -Y

-Y, --empty
        Permits empty matches.  By default, empty matches are disabled,
        unless a pattern begins with `^' or ends with `$'.  Note that -Y
        when specified with an empty-matching pattern, such as x? and x*,
        match all input, not only lines containing the character `x'.

Option -Y permits empty pattern matches, like GNU/BSD grep. This option is introduced by ugrep to prevent accidental matching with empty patterns: empty-matching patterns such as x? and x* match all input, not only lines with x. By default, without -Y, patterns match lines with at least one x as intended.

This option is automatically enabled when a pattern starts with ^ or ends with $ is specified. For example, ^\h*$ matches blank lines, including empty lines.

To recursively list files in the working directory with blank lines, i.e. lines with white space only, including empty lines (note that option -Y is implicitly enabled since the pattern starts with ^ and ends with $):

ug -l '^\h*$'

Case-insentitive matching with -i and -j

-i, --ignore-case
        Perform case insensitive matching.  By default, ugrep is case
        sensitive.  By default, this option applies to ASCII letters only.
        Use options -P and -i for Unicode case insensitive matching.
-j, --smart-case
        Perform case insensitive matching like option -i, unless a pattern
        is specified with a literal ASCII upper case letter.

To match todo in myfile.cpp regardless of case:

 ug -i 'todo' myfile.txt

To match todo XXX with todo in any case but XXX as given, with pattern (?i:todo) to match todo ignoring case:

 ug '(?i:todo) XXX' myfile.cpp

Sort files by name, best match, size, and time

--sort[=KEY]
        Displays matching files in the order specified by KEY in recursive
        searches.  Normally the ug command sorts by name whereas the ugrep
        batch command displays matches in no particular order to improve
        performance.  The sort KEY can be `name' to sort by pathname
        (default), `best' to sort by best match with option -Z (sort by
        best match requires two passes over files, which is expensive),
        `size' to sort by file size, `used' to sort by last access time,
        `changed' to sort by last modification time and `created' to sort
        by creation time.  Sorting is reversed with `rname', `rbest',
        `rsize', `rused', `rchanged', or `rcreated'.  Archive contents are
        not sorted.  Subdirectories are sorted and displayed after matching
        files.  FILE arguments are searched in the same order as specified.

Matching files are displayed in the order specified by --sort per directory searched. By default, the ug command sorts by name whereas the output of the ugrep command is not sorted to improve performance, unless option -Q is used which sorts files by name. An optimized sorting method and strategy are implemented in the asynchronous output class to keep the overhead of sorting very low. Directories are displayed after files are displayed first, when recursing, which visually aids the user in finding the "closest" matching files first at the top of the displayed results.

To recursively search for C++ files that match main and sort them by date created:

ug --sort=created -tc++ 'main'

Same, but sorted by time changed from most recent to oldest:

ug --sort=rchanged -tc++ 'main'

Tips for advanced users

When searching non-binary files only, the binary content check is disabled with option -a (--text) to speed up searching and displaying pattern matches. For example, searching for lines with int in C++ source code:

ug -r -a -Ocpp -w 'int'

If a file has potentially many pattern matches, but each match is only one a single line, then option -u (--ungroup) can speed this up:

ug -r -a -u -Opython -w 'def'

Even greater speeds can be achieved with --format when searching files with many matches. For example, --format='%O%~' displays matching lines for each match on that line, while --format='%o%~' displays the matching part only. Note that the --format option does not check for binary matches, so the output is always "as is". To match text and binary, you can use --format='%C%~' to display matches formatted as quoted C++ strings with escapes. To display a line at most once (unless option -u is used), add the %u (unique) field to the format string, e.g. --format='%u%O%~'.

For example, to match all words recursively in the working directory with line and column numbers, where %n is the line number, %k is the column number, %o is the match (only matching), and %~ is a newline:

ug -r --format='%n,%k:%o%~' '\w+'

More examples

To search for pattern -o in script.sh using -e to explicitly specify a pattern to prevent pattern -o from being interpreted as an option:

ug -n -e '-o' script.sh

Alternatively, using -- to end the list of command arguments:

ug -n -- '-o' script.sh

To recursively list all text files (.txt and .md) that do not properly end with a \n (-o is required to match \n or \z):

ug -L -o -Otext '\n\z'

To list all markdown sections in text files (.text, .txt, .TXT, and .md):

ug -o -ttext -e '^.*(?=\r?\n(===|---))' -e '^#{1,6}\h+.*'

To display multi-line backtick and indented code blocks in markdown files with their line numbers, using a lazy quantifier *? to make the pattern compact:

ug -n -ttext -e '^```(.|\n)*?\n```' -e '^(\t|[ ]{4}).*'

To find mismatched code (a backtick without matching backtick on the same line) in markdown:

ug -n -ttext -e '`[^`]+' -N '`[^`]*`'

Man page

UGREP(1)                          User Commands                         UGREP(1)

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
       The ugrep utility searches any given input files, selecting files and
       lines that match one or more patterns specified as regular expressions or
       as fixed strings.  A pattern matches multiple input lines when the
       pattern's regular expression matches one or more newlines.  An empty
       pattern matches every line.  Each input line that matches at least one of
       the patterns is written to the standard output.

       The ug command is intended for interactive searching, using a `.ugrep'
       configuration file located in the working directory or, if not found, in
       the home directory, see CONFIGURATION.  ug is equivalent to ugrep
       --config --pretty --sort to load a configuration file, enhance the
       terminal output, and to sort files by name.

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

       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, counts the total number of matches.  When
       combined with option -m1, (--min-count=1), skips files with zero matches.

       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.

       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.

       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.

       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.

       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
              Output NUM lines of trailing context after matching lines.  Places
              a --group-separator between contiguous groups of matches.  If -o
              is specified, output the match with context to fit NUM columns
              after the match or shortens the match.  See also options -B, -C
              and -y.

       -a, --text
              Process 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.

       --all, -@
              Search all files except hidden: cancel previous file and directory
              search restrictions and cancel --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.

       --and [-e] PATTERN
              Specify 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.

       --andnot [-e] PATTERN
              Combines --and --not.  See also options --and, --not and --bool.

       -B NUM, --before-context=NUM
              Output NUM lines of leading context before matching lines.  Places
              a --group-separator between contiguous groups of matches.  If -o
              is specified, output the match with context to fit NUM columns
              before the match or shortens the match.  See also options -A, -C
              and -y.

       -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,
              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.

       --bool, -%, -%%
              Specifies Boolean query patterns.  A Boolean query pattern is
              composed of `AND', `OR', `NOT' operators and grouping with `('
              `)'.  Spacing between subpatterns is the same as `AND', `|' is the
              same as `OR' and a `-' is the same as `NOT'.  The `OR' operator
              binds more tightly than `AND'.  For example, --bool 'A|B C|D'
              matches lines with (`A' or `B') and (`C' or `D'), --bool 'A -B'
              matches lines with `A' and not `B'.  Operators `AND', `OR', `NOT'
              require proper spacing.  For example, --bool 'A OR B AND C OR D'
              matches lines with (`A' or `B') and (`C' or `D'), --bool 'A AND
              NOT B' matches lines with `A' without `B'.  Quoted subpatterns are
              matched literally as strings.  For example, --bool 'A "AND"|"OR"'
              matches lines with `A' and also either `AND' or `OR'.  Parentheses
              are used for grouping.  For example, --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
              Output NUM lines of leading and trailing context surrounding each
              matching line.  Places a --group-separator between contiguous
              groups of matches.  If -o is specified, output 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 is written to standard output.
              When -o or -u is specified, counts the number of patterns matched.
              When -v is specified, counts the number of non-matching lines.
              When -m1, (with a comma or --min-count=1) is specified, counts
              only matching files without outputting zero matches.

       --color[=WHEN], --colour[=WHEN]
              Mark 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
              matche