ugrep Documentation

ugrep provides several command aliases for different workflows:

• ugrep: The full command.
• ug: An interactive-optimized alias. It is equivalent to ugrep --config --pretty --sort. It loads a configuration file (from the working directory or home directory), enhances terminal output, and sorts files by name.
• ugrep+ / ug+: Same as ugrep/ug, but includes filters to search PDFs, documents, e-books, and image metadata (requires corresponding filter tools to be installed).

ugrep provides different command binaries depending on your use case:

• ug: Designed for interactive use. It automatically loads an optional .ugrep configuration file from your current working directory or home directory to apply your preferences.
• ug+: An enhanced version of ug that also searches through PDFs, documents, e-books, and image metadata using built-in filters.
• ugrep: Designed for batch use (similar to GNU grep). It does not load a .ugrep configuration file.
• ugrep+: An enhanced version of ugrep that also searches through PDFs, documents, e-books, and image metadata.

ugrep is a drop-in replacement for grep, egrep, and fgrep and is compatible with GNU/BSD grep syntax.

Use the - (short) or --bool (long) options to perform complex logical searches. Boolean queries allow for AND, OR, and NOT operations using operators like space (AND), | (OR), and - (NOT).

Key modes:

• Line matching (default): Matches lines that satisfy the Boolean expression.
• File matching (--files or -%%): Matches a file if the Boolean conditions are satisfied across its content (e.g., some lines match A, some match B, and no lines match C).

Precedence (highest to lowest):

1. Quoted strings "x" (literal match)
2. Grouping ( )
3. NOT (-x)
4. OR (x|y)
5. AND (x y)

Note: All subpatterns are regular expressions by default unless -F is specified. You can combine with -E, -F, -G, -P, or -Z.

To build the standard version of ugrep using MSVC++ 2019 or greater:

1. Open ugrep.sln in Visual Studio 2019 or later.
2. If prompted, upgrade the projects to your installed Visual Studio version.
3. Select your desired platform (x86 or x64).
4. Select a configuration: Base-Debug or Base-Release.
5. Build the Solution.

The resulting binary is located at: ...\ugrep\msvc\bin\Base-(configuration)\ugrep.exe.

ugrep supports advanced query patterns including fuzzy searching, Boolean logic, and regex group captures.

Fuzzy Search: Use -Z<N> to allow up to N spelling errors.

Boolean Queries:

• AND: Use a space between terms or the --and flag.
• NOT: Use a minus sign - before a term or the --andnot flag.
• Boolean Pattern: Use -% 'PATTERN' to treat the string as a Boolean query.

Regex Groups: Requires -P. Use %1, %2, etc., or %[NAME]# for named captures.

You can perform standard searches or recursive searches using ugrep (or the ug alias which loads configuration files).

• Standard search: ug PATTERN FILE...
• Recursive search: Use -r to search directories recursively. Note that -r follows symlinks by default if no file arguments are provided.
• Depth control: Use -2 (or other numbers) to limit the recursion depth.
• Search specific file types: Use -t followed by the file type (e.g., -tc++ for C++ files) to restrict the search to specific extensions or predefined types.

Instead of using the GREP_OPTIONS environment variable (which ugrep ignores for portability), use a .ugrep configuration file.

• The ug command is an alias for ugrep --config, which automatically loads a .ugrep file from the current working directory or the home directory.
• You can generate a template configuration file in your working directory using --save-config and then move/edit it in your home directory to set permanent defaults.

You can install ugrep using Homebrew or MacPorts.

Using Homebrew:

brew install ugrep

Using MacPorts:

sudo port install ugrep

This installation provides both the ugrep and ug commands. The ug command is identical to ugrep but automatically loads configuration settings from a .ugrep file if one exists in your home directory or the current working directory.