{"id":23441935,"url":"https://github.com/genivia/ugrep","last_synced_at":"2025-05-14T01:03:34.030Z","repository":{"id":37850389,"uuid":"183980799","full_name":"Genivia/ugrep","owner":"Genivia","description":"🔍 ugrep 7.3 file pattern searcher -- a more powerful, ultra fast, user-friendly, compatible grep replacement. Includes a TUI, Google-like Boolean search with AND/OR/NOT, fuzzy search, hexdumps, searches (nested) archives (zip, 7z, tar, pax, cpio), compressed files (gz, Z, bz2, lzma, xz, lz4, zstd, brotli), pdfs, docs, and more","archived":false,"fork":false,"pushed_at":"2025-03-28T19:10:27.000Z","size":145549,"stargazers_count":2795,"open_issues_count":3,"forks_count":116,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-04-01T16:15:25.937Z","etag":null,"topics":["code-search","file-indexing","file-search","fuzzy-search","grep","hexdump","interactive","recursively-search","regex","ripgrep","search","silver-searcher","tar","tui","unicode","zip"],"latest_commit_sha":null,"homepage":"https://ugrep.com","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Genivia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-29T01:42:38.000Z","updated_at":"2025-04-01T12:06:37.000Z","dependencies_parsed_at":"2023-02-16T22:45:52.800Z","dependency_job_id":"35ad1ddf-08d0-47f7-84e4-82d062646657","html_url":"https://github.com/Genivia/ugrep","commit_stats":{"total_commits":764,"total_committers":45,"mean_commits":"16.977777777777778","dds":0.4515706806282722,"last_synced_commit":"09afeb5a3450a6e014f808be6b53f26bb92fc89a"},"previous_names":[],"tags_count":196,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Genivia%2Fugrep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Genivia%2Fugrep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Genivia%2Fugrep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Genivia%2Fugrep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Genivia","download_url":"https://codeload.github.com/Genivia/ugrep/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247888559,"owners_count":21013001,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-search","file-indexing","file-search","fuzzy-search","grep","hexdump","interactive","recursively-search","regex","ripgrep","search","silver-searcher","tar","tui","unicode","zip"],"created_at":"2024-12-23T17:19:34.120Z","updated_at":"2025-05-14T01:03:34.013Z","avatar_url":"https://github.com/Genivia.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/Genivia/ugrep/actions/workflows/c-cpp.yml\"\u003e\u003cimg src=\"https://github.com/Genivia/ugrep/actions/workflows/c-cpp.yml/badge.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opensource.org/licenses/BSD-3-Clause\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-BSD%203--Clause-blue.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003ch1 align=\"center\"\u003eThe ugrep file pattern searcher\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n[ \u003cb\u003eREADME\u003c/b\u003e | \u003ca href=\"https://ugrep.com\"\u003eUser\u0026nbsp;Guide\u003c/a\u003e | \u003ca href=\"https://github.com/Genivia/ugrep-indexer\"\u003eIndexing\u003c/a\u003e | \u003ca href=\"https://github.com/Genivia/ugrep-benchmarks\"\u003eBenchmarks\u003c/a\u003e | \u003ca href=\"https://github.com/Genivia/ugrep/discussions/categories/q-a\"\u003eQ\u0026amp;A\u003c/a\u003e ]\n\u003cbr\u003e\n\u003cbr\u003e\n\u003cimg src=\"https://www.genivia.com/images/scranim.gif\" width=\"438\" alt=\"\"\u003e\n\u003cbr\u003e\n\u003ci\u003eoption -Q opens a query TUI to search files as you type!\u003c/i\u003e\n\u003c/p\u003e\n\nWhy use ugrep?\n--------------\n\n- ugrep is fast, user-friendly, and equipped with a ton of new features that users wanted\n\n- includes an interactive TUI with built-in help, Google-like search with AND/OR/NOT patterns, fuzzy search, search (nested) zip/7z/tar/pax/cpio archives, tarballs and compressed files gz/Z/bz/bz2/lzma/xz/lz4/zstd/brotli, search and hexdump binary files, search documents such as PDF, doc, docx, and output in JSON, XML, CSV or your own customized format\n\n- Unicode extended regex pattern syntax with multi-line pattern matching without requiring special command-line options\n\n- includes a file indexer to speed up searching slow and cold file systems\n\n- a true drop-in replacement for GNU grep (assuming you [copy or symlink `ug` to `grep`, and to `egrep` and to `fgrep`](#grep)), unlike other popular grep claiming to be \"grep alternatives\" or \"replacements\" when those actually implement incompatible command-line options and use an incompatible regex matcher, i.e. Perl regex only versus POSIX BRE (grep) and ERE (egrep) when ugrep supports all regex modes\n\n- benchmarks show that [ugrep is (one of) the fastest grep](https://github.com/Genivia/ugrep-benchmarks) using the high-performance DFA-based regex matcher [RE/flex](https://github.com/Genivia/RE-flex)\n\nDevelopment roadmap\n-------------------\n\n*if something should be improved or added to ugrep, then let me know!*\n\n- #1 priority is quality assurance to continue to make sure ugrep has no bugs and is reliable\n\n- make ugrep run even faster, see for example [#432](https://github.com/Genivia/ugrep/issues/432), [#421](https://github.com/Genivia/ugrep/issues/421)\n\n- share [reproducible performance results](https://github.com/Genivia/ugrep-benchmarks)\n\nOverview\n--------\n\n### Commands\n\n- `ug` is for interactive use, which loads an optional .ugrep configuration file with your preferences located in the working directory or home directory, `ug+` also searches pdfs, documents, e-books, image metadata\n\n- `ugrep` for batch use like GNU grep without a .ugrep configuration file, `ugrep+` also searches pdfs, documents, e-books, image metadata\n\n### What does ugrep add that GNU grep does not support?\n\n- Matches Unicode patterns by default and automatically searches UTF-8, UTF-16 and UTF-32 encoded files\n\n- Matches multiple lines with `\\n` or `\\R` in regex patterns, *no special options are required to do so!*\n\n- Built-in help: `ug --help`, where `ug --help WHAT` displays options related to `WHAT` you are looking for\n\n  💡 `ug --help regex`, `ug --help globs`, `ug --help fuzzy`, `ug --help format`.\n\n- User-friendly with customizable [configuration files](#config) used by the `ug` command intended for interactive use that loads a .ugrep configuration file with your preferences\n\n      ug PATTERN ...                         ugrep --config PATTERN ...\n\n  💡 `ug --save-config ...options-you-want-to-save...` saves a .ugrep config file in the working directory so that the next time you run `ug` there it uses these options.  Do this in your home directory to save a .ugrep config file with options you generally want to use.\n\n- Interactive [query TUI](#query), press F1 or CTRL-Z for help and TAB/SHIFT-TAB to navigate to dirs and files\n\n      ug -Q                                  ug -Q -e PATTERN\n\n  💡 `-Q` replaces `PATTERN` on the command line to let you enter patterns interactively in the TUI.  In the TUI use ALT+letter keys to toggle short \"letter options\" on/off, for example ALT-n (option `-n`) to show/hide line numbers.\n\n- Search the contents of [archives](#archives) (zip, tar, pax, jar, cpio, 7z) and [compressed files](#archives) (gz, Z, bz, bz2, lzma, xz, lz4, zstd, brotli)\n\n      ug -z PATTERN ...                      ug -z --zmax=2 PATTERN ...\n\n  💡 specify `-z --zmax=2` to search compressed files and archives nested within archives.  The `--zmax` argument may range from 1 (default) to 99 for up to 99 decompression and de-archiving steps to search nested archives\n\n- Search with Google-like [Boolean query patterns](#bool) using `-%` patterns with `AND` (or just space), `OR` (or a bar `|`), `NOT` (or a dash `-`), using quotes to match exactly, and grouping with `( )` (shown on the left side below); or with options `-e` (as an \"or\"), `--and`, `--andnot`, and `--not` regex patterns (shown on the right side below):\n\n      ug -% 'A B C' ...                      ug -e 'A' --and 'B' --and 'C' ...\n      ug -% 'A|B C' ...                      ug -e 'A' -e 'B' --and 'C' ...\n      ug -% 'A -B -C' ...                    ug -e 'A' --andnot 'B' --andnot 'C' ...\n      ug -% 'A -(B|C)'...                    ug -e 'A' --andnot 'B' --andnot 'C' ...\n      ug -% '\"abc\" \"def\"' ...                ug -e '\\Qabc\\E' --and '\\Qdef\\E' ...\n\n  where `A`, `B` and `C` are arbitrary regex patterns (use option `-F` to search strings)\n\n  💡 specify option `-%%` (`--bool --files`) to apply the Boolean query to files as a whole: a file matches if all Boolean conditions are satisfied by matching patterns file-wide.  Otherwise, Boolean conditions apply to single lines by default, since grep utilities are generally line-based pattern matchers.  Option `--stats` displays the query in human-readable form after the search completes.\n\n- Search pdf, doc, docx, e-book, and more with `ug+` [using filters](#filter) associated with filename extensions:\n\n      ug+ PATTERN ...\n\n  or specify `--filter` with a file type to use a filter utility:\n\n      ug --filter='pdf:pdftotext % -' PATTERN ...\n      ug --filter='doc:antiword %' PATTERN ...\n      ug --filter='odt,docx,epub,rtf:pandoc --wrap=preserve -t plain % -o -' PATTERN ...\n      ug --filter='odt,doc,docx,rtf,xls,xlsx,ppt,pptx:soffice --headless --cat %' PATTERN ...\n      ug --filter='pem:openssl x509 -text,cer,crt,der:openssl x509 -text -inform der' PATTERN ...\n      ug --filter='latin1:iconv -f LATIN1 -t UTF-8' PATTERN ...\n\n  💡 the `ug+` command is the same as the `ug` command, but also uses filters to search PDFs, documents, and image metadata\n\n- Display horizontal context with option `-o` (`--only-matching`) and context options `-ABC`, e.g. to find matches in very long lines, such as Javascript and JSON sources:\n\n      ug -o -C20 -nk PATTERN longlines.js\n\n  💡 `-o -C20` fits all matches with context in 20 characters before and 20 charactess after a match (i.e. 40 Unicode characters total), `-nk` outputs line and column numbers.\n\n- Find approximate pattern matches with [fuzzy search](#fuzzy), within the specified Levenshtein distance\n\n      ug -Z PATTERN ...                      ug -Z3 PATTTERN ...\n\n  💡 `-Zn` matches up to `n` extra, missing or replaced characters, `-Z+n` matches up to `n` extra characters, `-Z-n` matches with up to `n` missing characters and `-Z~n` matches up to `n` replaced characters.  `-Z` defaults to `-Z1`.\n\n- Fzf-like search with regex (or fixed strings with `-F`), fuzzy matching with up to 4 extra characters with `-Z+4` and words only with `-w`, using `-%%` for file-wide Boolean searches\n\n      ug -Q -%% -l -w -Z+4 --sort=best\n\n  💡 `-l` lists the matching files in the TUI, press `TAB` then `ALT-y` to view a file, `SHIFT-TAB` and `Alt-l` to go back to view the list of matching files ordered by best match\n\n- Search [binary files](#binary) and display hexdumps with binary pattern matches (Unicode text or `-U` for byte patterns)\n\n      ug --hexdump -U BYTEPATTERN ...        ug --hexdump TEXTPATTERN ...\n      ug -X -U BYTEPATTERN ...               ug -X TEXTPATTERN ...\n      ug -W -U BYTEPATTERN ...               ug -W TEXTPATTERN ...\n\n  💡 `--hexdump=4chC1` displays `4` columns of hex without a character column `c`, no hex spacing `h`, and with one extra hex line `C1` before and after a match.\n\n- Include files to search by [file types or file \"magic bytes\"](#magic) or exclude them with `^`\n\n      ug -t TYPE PATTERN ...                 ug -t ^TYPE PATTERN ...\n      ug -M 'MAGIC' PATTERN ...              ug -M '^MAGIC' PATTERN ...\n\n- Include files and directories to search that match [gitignore-style globs](#globs) or exclude them with `^`\n\n      ug -g 'FILEGLOB' PATTERN ...           ug -g '^FILEGLOB' PATTERN ...\n      ug -g 'DIRGLOB/' PATTERN ...           ug -g '^DIRGLOB/' PATTERN ...\n      ug -g 'PATH/FILEGLOB' PATTERN ...      ug -g '^PATH/FILEGLOB' PATTERN ...\n      ug -g 'PATH/DIRGLOB/' PATTERN ...      ug -g '^PATH/DIRGLOB/' PATTERN ...\n\n- Include files to search by [filename extensions](#magic) (suffix) or exclude them with `^`, a shorthand for `-g\"*.EXT\"`\n\n      ug -O EXT PATTERN ...                  ug -O ^EXT PATTERN ...\n\n- Include [hidden files (dotfiles) and directories](#hidden) to search (omitted by default)\n\n      ug -. PATTERN ...                      ug -g'.*,.*/' PATTERN ...\n\n  💡 specify `hidden` in your .ugrep to always search hidden files with `ug`.\n\n- Exclude files specified by [.gitignore](#ignore) etc.\n\n      ug --ignore-files PATTERN ...          ug --ignore-files=.ignore PATTERN ...\n\n  💡 specify `ignore-files` in your .ugrep to always ignore them with `ug`.  Add additional `ignore-files=...` as desired.\n\n- Search patterns excluding [negative patterns](#not) (\"match this but not that\")\n\n      ug -e PATTERN -N NOTPATTERN ...        ug -e '[0-9]+' -N 123 ...\n\n- Use [predefined regex patterns](#source) to search source code, javascript, XML, JSON, HTML, PHP, markdown, etc.\n\n      ug PATTERN -f c++/zap_comments -f c++/zap_strings ...\n      ug PATTERN -f php/zap_html ...\n      ug -f js/functions ... | ug PATTERN ...\n\n- Sort matching files by [name, best match, size, and time](#sort)\n\n      ug --sort PATTERN ...                  ug --sort=size PATTERN ...\n      ug --sort=changed PATTERN ...          ug --sort=created PATTERN ...\n      ug -Z --sort=best PATTERN ...          ug --no-sort PATTERN ...\n\n- Output results in [CSV, JSON, XML](#json), and [user-specified formats](#format)\n\n      ug --csv PATTERN ...                   ug --json PATTERN ...\n      ug --xml PATTERN ...                   ug --format='file=%f line=%n match=%O%~' PATTERN ...\n\n  💡 `ug --help format` displays help on format `%` fields for customized output.\n\n- Search with PCRE's Perl-compatible regex patterns and display or replace [subpattern matches](#replace)\n\n      ug -P PATTERN ...                      ug -P --format='%1 and %2%~' 'PATTERN(SUB1)(SUB2)' ...\n\n- Replace patterns in the output with [-P and --replace](#replace) replacement text, optionally containing `%` [formatting fields](#format), using `-y` to pass the rest of the file through:\n\n      ug --replace='TEXT' PATTERN ...        ug -y --replace='TEXT' PATTERN ...\n      ug --replace='(%m:%o)' PATTERN ...     ug -y --replace='(%m:%o)' PATTERN ...\n      ug -P --replace='%1' PATTERN ...       ug -y -P --replace='%1' PATTERN ...\n\n  💡 `ug --help format` displays help on format `%` fields to optionally use with `--replace`.\n\n- Search files with a specific [encoding](#encoding) format such as ISO-8859-1 thru 16, CP 437, CP 850, MACROMAN, KOI8, etc.\n\n      ug --encoding=LATIN1 PATTERN ...\n\n\u003ca name=\"toc\"/\u003e\n\nTable of contents\n-----------------\n\n- [How to install](#install)\n- [Performance comparisons](#speed)\n- [Using ugrep within Vim](#vim)\n- [Using ugrep within Emacs](#emacs)\n- [Using ugrep to replace GNU/BSD grep](#grep)\n  - [Equivalence to GNU/BSD grep](#equivalence)\n  - [Short and quick command aliases](#aliases)\n  - [Notable improvements over grep](#improvements)\n- [Tutorial](#tutorial)\n  - [Examples](#examples)\n  - [Advanced examples](#advanced)\n  - [Displaying helpful info](#help)\n  - [Configuration files](#config)\n  - [Interactive search with -Q](#query)\n  - [Recursively list matching files with -l, -R, -r, --depth, -g, -O, and -t](#recursion)\n  - [Boolean query patterns with -%, -%%, --and, --not](#bool)\n  - [Search this but not that with -v, -e, -N, -f, -L, -w, -x](#not)\n  - [Search non-Unicode files with --encoding](#encoding)\n  - [Matching multiple lines of text](#multiline)\n  - [Displaying match context with -A, -B, -C, and -y](#context)\n  - [Searching source code using -f, -O, and -t](#source)\n  - [Searching compressed files and archives with -z](#archives)\n  - [Find files by file signature and shebang \"magic bytes\" with -M, -O and -t](#magic)\n  - [Fuzzy search with -Z](#fuzzy)\n  - [Search hidden files with -.](#hidden)\n  - [Using filter utilities to search documents with --filter](#filter)\n  - [Searching and displaying binary files with -U, -W, and -X](#binary)\n  - [Ignore binary files with -I](#nobinary)\n  - [Ignoring .gitignore-specified files with --ignore-files](#ignore)\n  - [Using gitignore-style globs to select directories and files to search](#globs)\n  - [Including or excluding mounted file systems from searches](#fs)\n  - [Counting the number of matches with -c and -co](#count)\n  - [Displaying file, line, column, and byte offset info with -H, -n, -k, -b, and -T](#fields)\n  - [Displaying colors with --color and paging the output with --pager](#color)\n  - [Output matches in JSON, XML, CSV, C++](#json)\n  - [Customize output with --format](#format)\n  - [Replacing matches with -P --replace and --format using backreferences](#replace)\n  - [Limiting the number of matches with -1,-2...-9, -K, -m, and --max-files](#max)\n  - [Matching empty patterns with -Y](#empty)\n  - [Case-insensitive matching with -i and -j](#case)\n  - [Sort files by name, best match, size, and time](#sort)\n  - [Tips for advanced users](#tips)\n  - [More examples](#more)\n- [Man page](#man)\n- [Regex patterns](#patterns)\n  - [POSIX regular expression syntax](#posix-syntax)\n  - [POSIX and Unicode character classes](#posix-classes)\n  - [POSIX and Unicode character categories](#posix-categories)\n  - [Perl regular expression syntax](#perl-syntax)\n- [Troubleshooting](#bugs)\n\n\u003ca name=\"install\"/\u003e\n\nHow to install\n--------------\n\n### MacOS\n\nInstall the latest ugrep with [Homebrew](https://brew.sh):\n\n    $ brew install ugrep\n\nor install with [MacPorts](https://www.macports.org):\n\n    $ sudo port install ugrep\n\nThis installs the `ugrep` and `ug` commands, where `ug` is the same as `ugrep`\nbut also loads the configuration file .ugrep when present in the working\ndirectory or home directory.\n\n### Windows\n\nInstall with [Winget](https://learn.microsoft.com/en-us/windows/package-manager/)\n`winget install Genivia.ugrep`\n\nOr install with [Chocolatey](https://community.chocolatey.org/packages/ugrep)\n`choco install ugrep`\n\nOr install with [Scoop](https://scoop.sh) `scoop install ugrep`\n\nOr download the full-featured `ugrep.exe` executable as release artifact from\n\u003chttps://github.com/Genivia/ugrep/releases\u003e.  The zipped release contains the\nmain `ugrep.exe` binary as well as `ug.exe`. The `ug` command, intended for\ninteractive use, loads and reads in settings from the _`.ugrep`_ configuration\nfile (when present in the working directory or home directory).\n\nAdd `ugrep.exe` and `ug.exe` to your execution path: go to *Settings* and\nsearch for \"Path\" in *Find a Setting*.  Select *environment variables* -\u003e\n*Path* -\u003e *New* and add the directory where you placed the `ugrep.exe` and\n`ug.exe` executables.\n\n\n\u003e[!TIP]\n\u003e _Practical hints on using `ugrep.exe` and `ug.exe` on the Windows command line:_\n\u003e\n\u003e- when quoting patterns and arguments on the command line, do not use single\n\u003e`'` quotes but use `\"` instead; most Windows command utilities consider\n\u003ethe single `'` quotes part of the command-line argument!\n\u003e- file and directory globs are best specified with option `-g/GLOB` instead of\n\u003ethe usual `GLOB` command line arguments to select files and directories to\n\u003esearch, especially for recursive searches;\n\u003e- when specifying an empty pattern `\"\"` to match all input, this may be ignored\n\u003eby some Windows command interpreters such as Powershell, in that case you\n\u003emust specify option `--match` instead;\n\u003e- to match newlines in patterns, you may want to use `\\R` instead of `\\n` to\n\u003ematch any Unicode newlines, such as `\\r\\n` pairs and single `\\r` and `\\n`.\n\n### Alpine Linux\n\n    $ apk add ugrep ugrep-doc\n\nCheck \u003chttps://pkgs.alpinelinux.org/packages?name=ugrep\u003e for version info.\n\n### Arch Linux\n\n    $ pacman -S ugrep\n\nCheck \u003chttps://archlinux.org/packages/extra/x86_64/ugrep\u003e for version info.\n\n### CentOS\n\nFirst enable the [EPEL repository](https://docs.fedoraproject.org/en-US/epel/),\nthen you can install ugrep.\n\n    $ dnf install ugrep\n\nCheck \u003chttps://packages.fedoraproject.org/pkgs/ugrep/ugrep/\u003e for version info.\n\n### Debian\n\n    $ apt-get install ugrep\n\nCheck \u003chttps://packages.debian.org/ugrep\u003e for version info.  To build and try\n`ugrep` locally, see \"All platforms\" build steps further below.\n\n### Fedora\n\n    $ dnf install ugrep\n\nCheck \u003chttps://packages.fedoraproject.org/pkgs/ugrep/ugrep/\u003e for version info.\n\n### FreeBSD\n\n    $ pkg install ugrep\n\nCheck \u003chttps://www.freshports.org/textproc/ugrep\u003e for version info.\n\n### Haiku\n\n    $ pkgman install cmd:ugrep\n\nCheck \u003chttps://github.com/haikuports/haikuports/tree/master/app-text/ugrep\u003e for\nversion info.  To build and try `ugrep` locally, see \"All platforms\" build\nsteps further below.\n\n### NetBSD\n\nYou can use the standard NetBSD package installer (pkgsrc):\n\u003chttp://cdn.netbsd.org/pub/pkgsrc/current/pkgsrc/textproc/ugrep/README.html\u003e\n\n### OpenBSD\n\n    $ pkg_add ugrep\n\nCheck \u003chttps://openports.pl/path/sysutils/ugrep\u003e for version info.\n\n### OpenSUSE\n\n    $ zypper install ugrep\n\nCheck \u003chttps://build.opensuse.org/package/show/utilities/ugrep\u003e for version info.\n\n### RHEL\n\nFirst enable the [EPEL repository](https://docs.fedoraproject.org/en-US/epel/),\nthen you can install ugrep.\n\n    $ dnf install ugrep\n\nCheck \u003chttps://packages.fedoraproject.org/pkgs/ugrep/ugrep/\u003e for version info.\n\n### Other platforms: step 1 download\n\nClone `ugrep` with\n\n    $ git clone https://github.com/Genivia/ugrep\n\nOr visit \u003chttps://github.com/Genivia/ugrep/releases\u003e to download a specific release.\n\n### Other platforms: step 2 consider optional dependencies\n\nYou can always add these later, when you need these features:\n\n- Option `-P` (Perl regular expressions) requires either the PCRE2 library\n  (recommended) or the Boost.Regex library (optional fallback).  If PCRE2 is\n  not installed, install PCRE2 with e.g. `sudo apt-get install -y libpcre2-dev`\n  or [download PCRE2](https://www.pcre.org) and follow the installation\n  instructions.  Alternatively,\n  [download Boost.Regex](https://www.boost.org/users/download) and run\n  `./bootstrap.sh` and `sudo ./b2 --with-regex install`.  See\n  [Boost: getting started](https://www.boost.org/doc/libs/1_72_0/more/getting_started/unix-variants.html).\n\n- Option `-z` (compressed files and archives search) requires the\n  [zlib](https://www.zlib.net) library installed.  It is installed on most\n  systems.  If not, install it, e.g. with `sudo apt-get install -y libz-dev`.\n  To search `.bz` and `.bz2` files, install the\n  [bzip2](https://www.sourceware.org/bzip2) library (recommended), e.g. with\n  `sudo apt-get install -y libbz2-dev`.  To search `.lzma` and `.xz` files,\n  install the [lzma](https://tukaani.org/xz) library (recommended), e.g. with\n  `sudo apt-get install -y liblzma-dev`.  To search `.lz4` files, install the\n  [lz4](https://github.com/lz4/lz4) library (optional, not required), e.g.\n  with `sudo apt-get install -y liblz4-dev`.  To search `.zst` files, install\n  the [zstd](http://facebook.github.io/zstd) library (optional, not required),\n  e.g. with `sudo apt-get install -y libzstd-dev`.  To search `.br` files,\n  install the [brotli](https://github.com/google/brotli) library (optional, not\n  required), e.g. with `sudo apt-get install -y libbrotli-dev`.  To search\n  `.bz3` files, install the [bzip3](https://github.com/kspalaiologos/bzip3)\n  library (optional, not required), e.g. with `sudo apt-get install -y bzip3`.\n\n\u003e[!TIP]\n\u003eEven if your system has command line utilities, such as `bzip2`, that\n\u003edoes not necessarily mean that the development libraries such as `libbz2` are\n\u003einstalled.  The *development libraries* should be installed.\n\u003e\n\u003eSome Linux systems may not be configured to load dynamic libraries from\n\u003e`/usr/local/lib`, causing a library load error when running `ugrep`.  To\n\u003ecorrect this, add `export LD_LIBRARY_PATH=\"$LD_LIBRARY_PATH:/usr/local/lib\"`\n\u003eto your `~/.bashrc` file.  Or run `sudo ldconfig /usr/local/lib`.\n\n### Other platforms: step 3 build\n\nExecute the `./build.sh` script to build `ugrep`:\n\n    $ cd ugrep\n    $ ./build.sh\n\nThis builds the `ugrep` executable in the `ugrep/src` directory with\n`./configure` and `make -j`, verified with `make test`.  When all tests pass,\nthe `ugrep` executable is copied to `ugrep/bin/ugrep` and the symlink\n`ugrep/bin/ug -\u003e ugrep/bin/ugrep` is added for the `ug` command.\n\nNote that `ug` is the same as `ugrep` but also loads the configuration file\n.ugrep when present in the working directory or home directory.  This means\nthat you can define your default options for `ug` in .ugrep.\n\nAlternative paths to installed or local libraries may be specified with\n`./build.sh`.  To get help on the available build options:\n\n    $ ./build.sh --help\n\nYou can build static executables by specifying:\n\n    $ ./build.sh --enable-static\n\nThis may fail if libraries don't link statically, such as brotli.  In that case\ntry `./build.sh --enable-static --without-brotli`.\n\nYou can build `ugrep` with customized defaults enabled, such as a pager:\n\n    $ ./build.sh --enable-pager\n\nOptions to select defaults for builds include:\n\n- `--help` display build options\n- `--enable-static` build static executables, if possible\n- `--enable-hidden` always search hidden files and directories\n- `--enable-pager` always use a pager to display output on terminals\n- `--enable-pretty` colorize output to terminals and add filename headings\n- `--disable-auto-color` disable automatic colors, requires ugrep option `--color=auto` to show colors\n- `--disable-mmap` disable memory mapped files\n- `--disable-sse2` disable SSE2 and AVX optimizations\n- `--disable-avx2` disable AVX2 and AVX512BW optimizations, but compile with SSE2 when supported\n- `--disable-neon` disable ARM NEON/AArch64 optimizations\n- `--with-grep-path` the default `-f` path if `GREP_PATH` is not defined\n- `--with-grep-colors` the default colors if `GREP_COLORS` is not defined\n\nAfter the build completes, copy `ugrep/bin/ugrep` and `ugrep/bin/ug` to a\nconvenient location, for example in your `~/bin` directory. Or, if you may want\nto install the `ugrep` and `ug` commands and man pages:\n\n    $ sudo make install\n\nThis also installs the pattern files with predefined patterns for option `-f`\nat `/usr/local/share/ugrep/patterns/`.  Option `-f` first checks the working\ndirectory for the presence of pattern files, if not found checks environment\nvariable `GREP_PATH` to load the pattern files, and if not found reads the\ninstalled predefined pattern files.\n\n### Troubleshooting\n\n#### Git and timestamps\n\nUnfortunately, git clones do not preserve timestamps which means that you may\nrun into \"WARNING: 'aclocal-1.15' is missing on your system.\" or that\nautoheader was not found when running `make`.\n\nTo work around this problem, run:\n\n    $ autoreconf -fi\n    $ ./build.sh\n\n#### Compiler warnings\n\nGCC 8 and greater may produce warnings of the sort *\"note: parameter passing\nfor argument ... changed in GCC 7.1\"*.  These warnings should be ignored.\n\n### Dockerfile for developers\n\nA Dockerfile is included to build `ugrep` in a Ubuntu container.\n\nDevelopers may want to use sanitizers to verify the **ugrep** code when making\nsignificant changes, for example to detect data races with the\n[ThreadSanitizer](https://clang.llvm.org/docs/ThreadSanitizer.html):\n\n    $ ./build.sh CXXFLAGS='-fsanitize=thread -O1 -g'\n\nWe checked `ugrep` with the clang AddressSanitizer, MemorySanitizer,\nThreadSanitizer, and UndefinedBehaviorSanitizer.  These options incur\nsignificant runtime overhead and should not be used for the final build.\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"speed\"/\u003e\n\nPerformance comparisons\n-----------------------\n\nPlease note that the **ugrep** and **ug** commands search binary files by\ndefault and do not ignore .gitignore specified files, which will not make\nrecursive search performance comparisons meaningful unless options `-I` and\n`--ignore-files` are used.  To make these options the default for **ug**,\nsimply add `ignore-binary` and `ignore-files` to your .ugrep configuration\nfile.\n\nFor an up-to-date performance comparison of the latest ugrep, please see the\n[ugrep performance benchmarks](https://github.com/Genivia/ugrep-benchmarks).\nUgrep is faster than GNU grep, Silver Searcher, ack, sift.  Ugrep's speed beats\nripgrep in most benchmarks.\n\n\u003ca name=\"vim\"/\u003e\n\nUsing ugrep within Vim\n----------------------\n\nFirst, let's define the `:grep` command in Vim to search files recursively.  To\ndo so, add the following lines to your `.vimrc` located in the root directory:\n\n    if executable('ugrep')\n        set grepprg=ugrep\\ -RInk\\ -j\\ -u\\ --tabs=1\\ --ignore-files\n        set grepformat=%f:%l:%c:%m,%f+%l+%c+%m,%-G%f\\\\\\|%l\\\\\\|%c\\\\\\|%m\n    endif\n\nThis specifies `-j` [case insensitive searches](#case) with the Vim `:grep`\ncommand.  For case sensitive searches, remove `\\ -j` from `grepprg`.  Multiple\nmatches on the same line are listed in the quickfix window separately.  If this\nis not desired, remove `\\ -u` from `grepprg`.  With this change, only the first\nmatch on a line is shown.  Option `--ignore-files` skips files specified in\n`.gitignore` files, when present.  To limit the depth of recursive searches to\nthe current directory only, append `\\ -1` to `grepprg`.\n\nYou can now invoke the Vim `:grep` command in Vim to search files on a\nspecified `PATH` for `PATTERN` matches:\n\n    :grep PATTERN [PATH]\n\nIf you omit `PATH`, then the working directory is searched.  Use `%` as `PATH`\nto search only the currently opened file in Vim:\n\n    :grep PATTERN %\n\nThe `:grep` command shows the results in a\n[quickfix](http://vimdoc.sourceforge.net/htmldoc/quickfix.html#:grep) window\nthat allows you to quickly jump to the matches found.\n\nTo open a quickfix window with the latest list of matches:\n\n    :copen\n\nDouble-click on a line in this window (or select a line and press ENTER) to\njump to the file and location in the file of the match.  Enter commands `:cn`\nand `:cp` to jump to the next or previous match, respectively.  To update the\nsearch results in the quickfix window, just grep them.  For example, to\nrecursively search C++ source code marked `FIXME` in the working directory:\n\n    :grep -tc++ FIXME\n\nTo close the quickfix window:\n\n    :cclose\n\nYou can use **ugrep** options with the `:grep` command, for example to\nselect single- and multi-line comments in the current file:\n\n    :grep -f c++/comments %\n\nOnly the first line of a multi-line comment is shown in quickfix, to save\nspace.  To show all lines of a multi-line match, remove `%-G` from\n`grepformat`.\n\nA popular Vim tool is [ctrlp.vim](http://kien.github.io/ctrlp.vim), which is\ninstalled with:\n\n    $ cd ~/.vim\n    $ git clone https://github.com/kien/ctrlp.vim.git bundle/ctrlp.vim\n\nCtrlP uses **ugrep** by adding the following lines to your `.vimrc`:\n\n    if executable('ugrep')\n        set runtimepath^=~/.vim/bundle/ctrlp.vim\n        let g:ctrlp_match_window='bottom,order:ttb'\n        let g:ctrlp_user_command='ugrep \"\" %s -Rl -I --ignore-files -3'\n    endif\n\nwhere `-I` skips binary files, option `--ignore-files` skips files specified in\n`.gitignore` files, when present, and option `-3` restricts searching\ndirectories to three levels (the working directory and up to two levels below).\n\nStart Vim then enter the command:\n\n    :helptags ~/.vim/bundle/ctrlp.vim/doc\n\nTo view the CtrlP documentation in Vim, enter the command:\n\n    :help ctrlp.txt\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"emacs\"/\u003e\n\nUsing ugrep within Emacs\n------------------------\n\nThanks to [Manuel Uberti](https://github.com/emacs-mirror/emacs/commits?author=manuel-uberti),\nyou can now use **ugrep** in Emacs.  To use **ugrep** instead of GNU grep\nwithin Emacs, add the following line to your `.emacs.d/init.el` file:\n\n    (setq-default xref-search-program ‘ugrep)\n\nThis means that Emacs commands such as `project-find-regexp` that rely on\n[Xref](https://www.gnu.org/software/emacs/manual/html_node/emacs/Xref.html) can\nnow leverage the power of **ugrep**.\n\nFurthermore, it is possible to use `grep` in the [Emacs grep\ncommands](https://www.gnu.org/software/emacs/manual/html_node/emacs/Grep-Searching.html).\nFor instance, you can run `lgrep` with `ugrep` by customizing `grep-template`\nto something like the following:\n\n    (setq-default grep-template \"ugrep --color=always -0Iinr -e \u003cR\u003e\")\n\nIf you do not have Emacs version 29 (or greater) you can download and build\nEmacs from the [Emacs master branch](https://github.com/emacs-mirror/emacs),\nor enable Xref integration with **ugrep** manually:\n\n    (with-eval-after-load 'xref\n     (push '(ugrep . \"xargs -0 ugrep \u003cC\u003e --null -ns -e \u003cR\u003e\")\n           xref-search-program-alist)\n     (setq-default xref-search-program 'ugrep))\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"grep\"/\u003e\n\nUsing ugrep to replace GNU/BSD grep\n-----------------------------------\n\n**ugrep** supports all standard GNU/BSD grep command-line options and improves\nmany of them too.  See [notable improvements over grep](#improvements).\n\nIn fact, executing `ugrep` with options `-U`, `-Y`, `-.` and `--sort` makes it\nbehave like `egrep`, permitting empty patterns to match and search hidden files\ninstead of ignoring them.  See [grep equivalence](#equivalence).\n\n- You can create [convenient grep aliases](#aliases) with or without options\n  `-Y`, `-.` and `--sort` or include other options as desired.  If you really\n  must stick exactly to GNU/BSD grep ASCII/LATIN1 patterns, use options `-U`\n  and `--grep` to disable Unicode pattern matching and to reassign options `-z`\n  and `-Z` to `--null-data` and `--null`, respectively.\n\n- You can also create `grep`, `egrep` and `fgrep` executables by symlinking or\n  copying `ugrep` to those names.  When the `ugrep` (or `ugrep.exe`) executable\n  is copied as `grep` (`grep.exe`), `egrep` (`egrep.exe`), `fgrep`\n  (`fgrep.exe`), then options `-Y` and `-.` are automatically enabled together\n  with either `-G` for `grep`, `-E` for `egrep` and `-F` for `fgrep`.  In\n  addition, when copied as `zgrep`, `zegrep` and `zfgrep`, option\n  `--decompress` is enabled.  For example, when `ugrep` is copied as `zegrep`,\n  options `--decompress`, `-E`, `-Y`, `-.` and `--sort` are enabled.\n\n- Likewise, symlinks and hard links can be used to create `grep`, `egrep` and\n  `fgrep` replacements in the usual installation directories.  For example:\n\n      sudo ln -s `which ugrep` /opt/local/bin/grep\n      sudo ln -s `which ugrep` /opt/local/bin/egrep\n      sudo ln -s `which ugrep` /opt/local/bin/fgrep\n      sudo ln -s `which ugrep` /opt/local/bin/zgrep\n      sudo ln -s `which ugrep` /opt/local/bin/zegrep\n      sudo ln -s `which ugrep` /opt/local/bin/zfgrep\n\n  The `/opt/local/bin` here is an example and may or may not be in your `$path`\n  and may or may not be found, so please adjust as necessary.  **Caution:**\n  *bash does not obey the linked name when executing the program, reverting to\n  the name `ugrep` instead, which negates all internal compatibility settings.\n  To avoid this, copy the executables instead of linking!*\n\nWhen linking or copying `ugrep` to `grep`, `egrep`, `fgrep`, `zgrep`, `zegrep`,\n`zfgrep`, options `-z` and `-Z` are reassigned for compatibility to GNU/BSD\ngrep options `--null-data` and `--null`, respectively.\n\n\u003ca name=\"equivalence\"/\u003e\n\n### Equivalence to GNU/BSD grep\n\nWhen the `ugrep` executable file is symlinked or copied to `grep`, `egrep`,\n`fgrep`, `zgrep`, `zegrep` and `zfgrep` executables, then those executables\nwill behave as GNU grep equivalents.  This behavior is implicit and automatic,\nessentially using the following translations:\n\n    grep   = ugrep -G -Y -. --sort\n    egrep  = ugrep -E -Y -. --sort\n    fgrep  = ugrep -F -Y -. --sort\n\n    zgrep  = ugrep -z -G -Y -. --sort\n    zegrep = ugrep -z -E -Y -. --sort\n    zfgrep = ugrep -z -F -Y -. --sort\n\nplease note that:\n\n- `-Y` enables empty matches, so for example the pattern `a*` matches every\n  line instead of a sequence of `a`'s.  By default in ugrep, the pattern `a*`\n  matches a sequence of `a`'s.  Moreover, in ugrep the pattern `a*b*c*` matches\n  what it is supposed to match by default.  See [improvements](#improvements).\n- `-.` searches hidden files (dotfiles).  By default, hidden files are ignored,\n  like most Unix utilities.\n- `--sort` specifies output sorted by pathname, showing sorted matching files\n  first followed by sorted recursive matches in subdirectories.  Otherwise,\n  matching files are reported in no particular order to improve performance;\n- options `-z` and `-Z` are reassigned to `--null-data` and `--null` and no\n  longer enable `--decompress` and `--fuzzy` searching modes.\n\nThere is one minor difference with GNU/BSD grep:\n\n- GNU/BSD grep defaults to `-Dread` and `-dread` which are not recommended, see\n  [improvements](#improvements) for an explanation.\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"aliases\"/\u003e\n\n### Short and quick command aliases\n\nCommonly-used aliases to add to `.bashrc` to increase productivity:\n\n    alias uq     = 'ug -Q'                # interactive TUI search (uses .ugrep config)\n    alias uz     = 'ug -z'                # compressed files and archives search (uses .ugrep config)\n    alias ux     = 'ug -U --hexdump'      # binary pattern search (uses .ugrep config)\n\n    alias ugit   = 'ug -R --ignore-files' # works like git-grep \u0026 define your preferences in .ugrep config\n\n    alias grep   = 'ug -G'                # search with basic regular expressions (BRE) like grep\n    alias egrep  = 'ug -E'                # search with extended regular expressions (ERE) like egrep\n    alias fgrep  = 'ug -F'                # find string(s) like fgrep\n    alias zgrep  = 'ug -zG'               # search compressed files and archives with BRE\n    alias zegrep = 'ug -zE'               # search compressed files and archives with ERE\n    alias zfgrep = 'ug -zF'               # find string(s) in compressed files and/or archives\n\n    alias xdump  = 'ugrep -X \"\"'                 # hexdump files without searching (don't use .ugrep config)\n    alias zmore  = 'ugrep+ -z -I -+ --pager \"\"'  # view compressed, archived and regular files (don't use .ugrep config)\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"improvements\"/\u003e\n\n### Notable improvements over grep\n\n- **ugrep** starts an interactive query TUI with option `-Q`.\n- **ugrep** matches patterns across multiple lines when patterns match `\\n`.\n- **ugrep** matches full Unicode by default (disabled with option `-U`).\n- **ugrep** supports Boolean patterns with AND, OR and NOT (option `--bool`).\n- **ugrep** supports gitignore with option `--ignore-files`.\n- **ugrep** supports fuzzy (approximate) matching with option `-Z`.\n- **ugrep** supports user-defined global and local configuration files.\n- **ugrep** searches compressed files and archives with option `-z`.\n- **ugrep** searches cpio, jar, pax, tar, zip and 7z archives with option `-z`.\n- **ugrep** searches cpio, jar, pax, tar, zip and 7z archives recursively\n  stored within archives with `-z` and `--zmax=NUM` for up to `NUM` levels deep.\n- **ugrep** searches pdf, doc, docx, xls, xlsx, epub, and more with `--filter`\n  using third-party format conversion utilities as plugins.\n- **ugrep** searches a directory when the FILE argument is a directory, like\n  most Unix/Linux utilities; use option `-r` to search directories recursively.\n- **ugrep** does not match hidden files by default like most Unix/Linux\n  utilities (hidden dotfile file matching is enabled with `-.`).\n- **ugrep** regular expression patterns are more expressive than GNU grep and\n  BSD grep POSIX ERE and support Unicode pattern matching.  Extended regular\n  expression (ERE) syntax is the default (i.e. option `-E` as egrep, whereas\n  `-G` enables BRE).\n- **ugrep** spawns threads to search files concurrently to improve search\n  speed (disabled with option `-J1`).\n- **ugrep** produces hexdumps with `-W` (output binary matches in hex with text\n  matches output as usual) and `-X` (output all matches in hex).\n- **ugrep** can output matches in JSON, XML, CSV and user-defined formats (with\n  option `--format`).\n- **ugrep** option `-f` uses `GREP_PATH` environment variable or the predefined\n  patterns installed in `/usr/local/share/ugrep/patterns`.  If `-f` is\n  specified and also one or more `-e` patterns are specified, then options\n  `-F`, `-x`, and `-w` do not apply to `-f` patterns.  This is to avoid\n  confusion when `-f` is used with predefined patterns that may no longer work\n  properly with these options.\n- **ugrep** options `-O`, `-M`, and `-t` specify file extensions, file\n  signature magic byte patterns, and predefined file types, respectively.  This\n  allows searching for certain types of files in directory trees, for example\n  with recursive search options `-R` and `-r`.  Options `-O`, `-M`, and `-t`\n  also applies to archived files in cpio, jar, pax, tar, zip and 7z files.\n- **ugrep** option `-k`, `--column-number` to display the column number, taking\n  tab spacing into account by expanding tabs, as specified by option `--tabs`.\n- **ugrep** option `-P` (Perl regular expressions) supports backreferences\n  (with `--format`) and lookbehinds, which uses the PCRE2 or Boost.Regex\n  library for fast Perl regex matching with a PCRE-like syntax.\n- **ugrep** option `-b` with option `-o` or with option `-u`, ugrep displays\n  the exact byte offset of the pattern match instead of the byte offset of the\n  start of the matched line reported by GNU/BSD grep.\n- **ugrep** option `-u`, `--ungroup` to not group multiple matches per line.\n  This option displays a matched input line again for each additional pattern\n  match on the line.  This option is particularly useful with option `-c` to\n  report the total number of pattern matches per file instead of the number of\n  lines matched per file.\n- **ugrep** option `-Y` enables matching empty patterns.  Grepping with\n  empty-matching patterns is weird and gives different results with GNU grep\n  versus BSD grep.  Empty matches are not output by **ugrep** by default, which\n  avoids making mistakes that may produce \"random\" results.  For example, with\n  GNU/BSD grep, pattern `a*` matches every line in the input, and actually\n  matches `xyz` three times (the empty transitions before and between the `x`,\n  `y`, and `z`).  Allowing empty matches requires **ugrep** option `-Y`.\n  Patterns that start with `^` or end with `$`, such as `^\\h*$`, match empty.\n  These patterns automatically enable option `-Y`.\n- **ugrep** option `-D, --devices=ACTION` is `skip` by default, instead of\n  `read`.  This prevents unexpectedly hanging on named pipes in directories\n  that are recursively searched, as may happen with GNU/BSD grep that `read`\n  devices by default.\n- **ugrep** option `-d, --directories=ACTION` is `skip` by default, instead of\n  `read`.  By default, directories specified on the command line are searched,\n  but not recursively deeper into subdirectories.\n- **ugrep** offers *negative patterns* `-N PATTERN`, which are patterns of the\n  form `(?^X)` that skip all `X` input, thus removing `X` from the search.\n  For example, negative patterns can be used to skip strings and comments when\n  searching for identifiers in source code and find matches that aren't in\n  strings and comments.  Predefined `zap` patterns use negative patterns, for\n  example, use `-f cpp/zap_comments` to ignore pattern matches in C++ comments.\n- **ugrep** ignores the `GREP_OPTIONS` environment variable, because the\n  behavior of **ugrep** must be portable and predictable on every system.  Also\n  GNU grep abandoned `GREP_OPTIONS` for this reason.  Please use the `ug`\n  command that loads the .ugrep configuration file located in the working\n  directory or in the home directory when present, or use shell aliases to\n  create new commands with specific search options.\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"tutorial\"/\u003e\n\nTutorial\n--------\n\n\u003ca name=\"examples\"/\u003e\n\n### Examples\n\nTo perform a search using a configuration file `.ugrep` placed in the working\ndirectory or home directory (note that `ug` is the same as `ugrep --config`):\n\n    ug PATTERN FILE...\n\nTo save a `.ugrep` configuration file to the working directory, then edit this\nfile in your home directory to customize your preferences for `ug` defaults:\n\n    ug --save-config\n\nTo search the working directory and recursively deeper for `main` (note that\n`-r` recurse symlinks is enabled by default if no file arguments are\nspecified):\n\n    ug main\n\nSame, but only search C++ source code files recursively, ignoring all other\nfiles:\n\n    ug -tc++ main\n\nSame, using the interactive query TUI, starting with the initial search pattern\n`main` (note that `-Q` with an initial pattern requires option `-e` because\npatterns are normally specified interactively and all command line arguments\nare considered files/directories):\n\n    ug -Q -tc++ -e main\n\nTo search for `#define` (and `# define` etc) using a regex pattern in C++ files\n(note that patterns should be quoted to prevent shell globbing of `*` and `?`):\n\n    ug -tc++ '#[\\t ]*define'\n\nTo search for `main` as a word (`-w`) recursively without following symlinks\n(`-r`) in directory `myproject`, showing the matching line (`-n`) and column\n(`-k`) numbers next to the lines matched:\n\n    ug -r -nkw main myproject\n\nSame, but only search `myproject` without recursing deeper (note that directory\narguments are searched at one level by default):\n\n    ug -nkw main myproject\n\nSame, but search `myproject` and one subdirectory level deeper (two levels)\nwith `-2`:\n\n    ug -2 -nkw main myproject\n\nSame, but only search C++ files in `myproject` and its subdirectories with\n`-tc++`:\n\n    ug -tc++ -2 -nkw main myproject\n\nSame, but also search inside archives (e.g. zip and tar files) and compressed\nfiles with `-z`:\n\n    ug -z -tc++ -2 -nkw main myproject\n\nSearch recursively the working directory for `main` while ignoring gitignored\nfiles (e.g.  assuming `.gitignore` is in the working directory or below):\n\n    ug --ignore-files -tc++ -nkw main\n\nTo list all files in the working directory and deeper that are not ignored by\n`.gitignore` file(s):\n\n    ug --ignore-files -l ''\n\nTo display the list of file name extensions and \"magic bytes\" (shebangs)\nthat are searched corresponding to `-t` arguments:\n\n    ug -tlist\n\nTo list all shell files recursively, based on extensions and shebangs with `-l`\n(note that `''` matches any non-empty file):\n\n    ug -l -tShell ''\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"advanced\"/\u003e\n\n### Advanced examples\n\nTo search for `main` in source code while ignoring strings and comment blocks\nyou can use *negative patterns* with option `-N` to skip unwanted matches in\nC/C++ quoted strings and comment blocks:\n\n    ug -r -nkw -e 'main' -N '\"(\\\\.|\\\\\\r?\\n|[^\\\\\\n\"])*\"|//.*|/\\*(.*\\n)*?.*\\*+\\/' myproject\n\nThis is a lot of work to type in correctly!  If you are like me, I don't want\nto spend time fiddling with regex patterns when I am working on something more\nimportant.  There is an easier way by using **ugrep**'s predefined patterns\n(`-f`) that are installed with the `ugrep` tool:\n\n    ug -r -nkw 'main' -f c/zap_strings -f c/zap_comments myproject\n\nThis query also searches through other files than C/C++ source code, like\nREADMEs, Makefiles, and so on.  We're also skipping symlinks with `-r`.  So\nlet's refine this query by selecting C/C++ files only using option `-tc,c++`\nand include symlinks to files and directories with `-R`:\n\n    ug -R -tc,c++ -nkw 'main' -f c/zap_strings -f c/zap_comments myproject\n\nWhat if you only want to look for the identifier `main` but not as a function\n`main(`?  In this case, use a negative pattern for this to skip unwanted\n`main\\h*(` pattern matches:\n\n    ug -R -tc,c++ -nkw -e 'main' -N 'main\\h*\\(' -f c/zap_strings -f c/zap_comments myproject\n\nThis uses the `-e` and `-N` options to explicitly specify a pattern and a\nnegative pattern, respectively, which is essentially forming the pattern\n`main|(?^main\\h*\\()`, where `\\h` matches space and tab.  In general, negative\npatterns are useful to filter out pattern matches that we are not interested\nin.\n\nAs another example, let's say we may want to search for the word `FIXME` in\nC/C++ comment blocks.  To do so we can first select the comment blocks with\n**ugrep**'s predefined `c/comments` pattern AND THEN select lines with `FIXME`\nusing a pipe:\n\n    ug -R -tc,c++ -nk -f c/comments myproject | ug -w 'FIXME'\n\nFiltering results with pipes is generally easier than using AND-OR logic that\nsome search tools use.  This approach follows the Unix spirit to keep utilities\nsimple and use them in combination for more complex tasks.\n\nLet's produce a sorted list of all identifiers found in Java source code while\nskipping strings and comments:\n\n    ug -R -tjava -f java/names myproject | sort -u\n\nThis matches Java Unicode identifiers using the regex\n`\\p{JavaIdentifierStart}\\p{JavaIdentifierPart}*` defined in\n`patterns/java/names`.\n\nWith traditional grep and grep-like tools it takes great effort to recursively\nsearch for the C/C++ source file that defines function `qsort`, requiring\nsomething like this:\n\n    ug -R --include='*.c' --include='*.cpp' '^([ \\t]*[[:word:]:*\u0026]+)+[ \\t]+qsort[ \\t]*\\([^;\\n]+$' myproject\n\nFortunately, with **ugrep** we can simply select all function definitions in\nfiles with extension `.c` or `.cpp` by using option `-Oc,cpp` and by using a\npredefined pattern `functions` that is installed with the tool to produce\nall function definitions.  Then we select the one we want:\n\n    ug -R -Oc,cpp -nk -f c/functions | ug 'qsort'\n\nNote that we could have used `-tc,c++` to select C/C++ files, but this also\nincludes header files when we want to only search `.c` and `.cpp` files.\n\nWe can also skip files and directories from being searched that are defined in\n`.gitignore`.  To do so we use `--ignore-files` to exclude any files and\ndirectories from recursive searches that match the globs in `.gitignore`, when\none or more `.gitignore` files are found:\n\n    ug -R -tc++ --ignore-files -f c++/defines\n\nThis searches C++ files (`-tc++`) in the working directory for `#define`\nlines (`-f c++/defines`), while skipping files and directories declared in\n`.gitignore`.  If you find this too long to type then define an alias to search\nGitHub directories:\n\n    alias ugit='ugrep -R --ignore-files'\n    ugit -tc++ -f c++/defines\n\nTo highlight matches when pushed through a chain of pipes we should use\n`--color=always`:\n\n    ugit --color=always -tc++ -f c++/defines | ugrep -w 'FOO.*'\n\nThis returns a color-highlighted list of all `#define FOO...` macros in C/C++\nsource code files, skipping files defined in `.gitignore`.\n\nNote that the complement of `--exclude` is not `--include`, because exclusions\nalways take precedence over inclusions, so we cannot reliably list the files\nthat are ignored with `--include-from='.gitignore'`.  Only files explicitly\nspecified with `--include` and directories explicitly specified with\n`--include-dir` are visited.  The `--include-from` from lists globs that are\nconsidered both files and directories to add to `--include` and\n`--include-dir`, respectively.  This means that when directory names and\ndirectory paths are not explicitly listed in this file then it will not be\nvisited using `--include-from`.\n\nBecause ugrep checks if the input is valid UTF-encoded Unicode (unless `-U` is\nused), it is possible to use it as a filter to ignore non-UTF output produced\nby a program:\n\n    program | ugrep -I ''\n\nIf the program produces valid output then the output is passed through,\notherwise the output is filtered out option `-I`.  If the output is initially\nvalid for a very large portion but is followed by invalid output, then ugrep\nmay initially show the output up to but excluding the invalid output after\nwhich further output is blocked.\n\nTo filter lines that are valid ASCII or UTF-encoded, while removing lines that\nare not:\n\n    program | ugrep '[\\p{Unicode}--[\\n]]+'\n\nNote that `\\p{Unicode}` matches `\\n` but we don't want to matche the whole\nfile!  Just lines with `[\\p{Unicode}--[\\n]]+`.\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"help\"/\u003e\n\n### Displaying helpful info\n\nThe ugrep man page:\n\n    man ugrep\n\nTo show a help page:\n\n    ug --help\n\nTo show options that mention `WHAT`:\n\n    ug --help WHAT\n\nTo show a list of `-t TYPES` option values:\n\n    ug -tlist\n\nIn the interactive query TUI, press F1 or CTRL-Z for help and options:\n\n    ug -Q\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"config\"/\u003e\n\n### Configuration files\n\n    --config[=FILE], ---[FILE]\n            Use configuration FILE.  The default FILE is `.ugrep'.  The working\n            directory is checked first for FILE, then the home directory.  The\n            options specified in the configuration FILE are parsed first,\n            followed by the remaining options specified on the command line.\n            The ug command automatically loads a `.ugrep' configuration file,\n            unless --config=FILE or --no-config is specified.\n    --no-config\n            Do not load the default .ugrep configuration file.\n    --save-config[=FILE] [OPTIONS]\n            Save configuration FILE to include OPTIONS.  Update FILE when\n            first loaded with --config=FILE.  The default FILE is `.ugrep',\n            which is automatically loaded by the ug command.  When FILE is a\n            `-', writes the configuration to standard output.  Only part of the\n            OPTIONS are saved that do not cause searches to fail when combined\n            with other options.  Additional options may be specified by editing\n            the saved configuration file.  A configuration file may be modified\n            manually to specify one or more config[=FILE] to indirectly load\n            the specified FILEs, but recursive config loading is not allowed.\n\n#### The ug command versus the ugrep command\n\nThe `ug` command is intended for context-dependent interactive searching and is\nequivalent to the `ugrep --config` command to load the configuration file\n`.ugrep` when present in the working directory or, when not found, in the home\ndirectory:\n\n    ug PATTERN ...\n    ugrep --config PATTERN ...\n\nThe `ug` command also sorts files by name per directory searched.  A\nconfiguration file contains `NAME=VALUE` pairs per line, where `NAME` is the\nname of a long option (without `--`) and `=VALUE` is an argument, which is\noptional and may be omitted depending on the option.  Empty lines and lines\nstarting with a `#` are ignored:\n\n    # Color scheme\n    colors=cx=hb:ms=hiy:mc=hic:fn=hi+y+K:ln=hg:cn=hg:bn=hg:se=\n    # Disable searching hidden files and directories\n    no-hidden\n    # ignore files specified in .ignore and .gitignore in recursive searches\n    ignore-files=.ignore\n    ignore-files=.gitignore\n\nCommand line options are parsed in the following order: first the (default or\nnamed) configuration file is loaded, then the remaining options and\narguments on the command line are parsed.\n\nOption `--stats` displays the configuration file used after searching.\n\n#### Named configuration files\n\nNamed configuration files are intended to streamline custom search tasks, by\nreducing the number of command line options to just one `---FILE` to use the\ncollection of options specified in `FILE`.  The `--config=FILE` option and its\nabbreviated form `---FILE` load the specified configuration file located in the\nworking directory or, when not found, located in the home directory:\n\n    ug ---FILE PATTERN ...\n    ugrep ---FILE PATTERN ...\n\nAn error is produced when `FILE` is not found or cannot be read.\n\nNamed configuration files can be used to define a collection of options that\nare specific to the requirements of a task in the development workflow of a\nproject.  For example to report unresolved issues by checking the source code\nand documentation for comments with FIXME and TODO items.  Such named\nconfiguration file can be localized to a project by placing it in the project\ndirectory, or it can be made global by placing it in the home directory.  For\nvisual feedback, a color scheme specific to this task can be specified with\noption `colors` in the configuration `FILE` to help identify the output\nproduced by a named configuration as opposed to the default configuration.\n\n#### Saving a configuration file\n\nThe `--save-config` option saves a `.ugrep` configuration file to the working\ndirectory using the current configuration loaded with `--config`.  This saves\nthe current configuration combined with additional options when specified also.\nOnly those options that cannot conflict with other options and options that\ncannot negatively impact search results will be saved.\n\nThe `--save-config=FILE` option saves the configuration to the specified `FILE`.\nThe configuration is written to standard output when `FILE` is a `-`.\n\nAlternatively, a configuration file may be manually created or modified.  A\nconfiguration file may include one or more `config[=FILE]` to indirectly load\nthe specfified `FILE`, but recursive config loading is prohibited.  The\nsimplest way to manuall create a configuration file is to specify `config` at\nthe top of the file, followed by the long options to override the defaults.\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"query\"/\u003e\n\n### Interactive search with -Q\n\n    -Q[=DELAY], --query[=DELAY]\n            Query mode: start a TUI to perform interactive searches.  This mode\n            requires an ANSI capable terminal.  An optional DELAY argument may\n            be specified to reduce or increase the response time to execute\n            searches after the last key press, in increments of 100ms, where\n            the default is 3 (300ms delay).  No whitespace may be given between\n            -Q and its argument DELAY.  Initial patterns may be specified with\n            -e PATTERN, i.e. a PATTERN argument requires option -e.  Press F1\n            or CTRL-Z to view the help screen.  Press F2 or CTRL-Y to invoke a\n            command to view or edit the file shown at the top of the screen.\n            The command can be specified with option --view, or defaults to\n            environment variable PAGER when defined, or EDITOR.  Press Tab and\n            Shift-Tab to navigate directories and to select a file to search.\n            Press Enter to select lines to output.  Press ALT-l for option -l\n            to list files, ALT-n for -n, etc.  Non-option commands include\n            ALT-] to increase context.  See also options --no-confirm, --delay,\n            --split and --view.\n    --no-confirm\n            Do not confirm actions in -Q query TUI.  The default is confirm.\n    --delay=DELAY\n            Set the default -Q key response delay.  Default is 3 for 300ms.\n    --split\n            Split the -Q query TUI screen on startup.\n    --view[=COMMAND]\n            Use COMMAND to view/edit a file in -Q query TUI by pressing CTRL-Y.\n\nThis option starts a user interface to enter search patterns interactively:\n- Press F1 or CTRL-Z to view a help screen and to enable or disable options.\n- Press Alt with a key corresponding to a ugrep option letter or digit to\n  enable or disable the ugrep option.  For example, pressing Alt-c enables\n  option `-c` to count matches.  Pressing Alt-c again disables `-c`.  Options\n  can be toggled with the Alt key while searching or when viewing the help\n  screen.  If Alt/Meta keys are not working (e.g. X11 xterm), then press\n  CTRL-O followed by the key corresponding to the option.  Alt keys may work\n  in xterm by adding `xterm*metaSendsEscape: true` to ~/.Xdefaults`.\n- Press Alt-g to enter or edit option `-g` file and directory matching globs, a\n  comma-separated list of gitignore-style glob patterns.  Presssing ESC returns\n  control to the query pattern prompt (the globs are saved).  When a glob is\n  preceded by a `!` or a `^`, skips files whose name matches the glob When a\n  glob contains a `/`, full pathnames are matched.  Otherwise basenames are\n  matched.  When a glob ends with a `/`, directories are matched.\n- The query TUI prompt switches between `Q\u003e` (normal), `F\u003e` (fixed strings),\n  `G\u003e` (basic regex), `P\u003e` (Perl matching), and `Z\u003e` (fuzzy matching).\n  When the `--glob=` prompt is shown, a comma-separated list of gitignore-style\n  glob patterns may be entered.  Presssing ESC returns control to the pattern\n  prompt.\n- Press CTRL-T to split the TUI screen to preview a file in the bottom pane.\n- Press CTRL-Y to view a file with a pager specified with `--view`.\n- Press Enter to switch to selection mode to select lines to output when ugrep\n  exits.  Normally, ugrep in query mode does not output any results unless\n  results are selected.  While in selection mode, select or deselect lines with\n  Enter or Del, or press A to select all results.\n- The file listed or shown at the top of the screen, or beneath the cursor in\n  selection mode, is edited by pressing F2 or CTRL-Y.  A file viewer or editor\n  may be specified with `--view=COMMAND`.  Otherwise, the `PAGER` or `EDITOR`\n  environment variables are used to invoke the command with CTRL-Y.  Filenames\n  must be enabled and visible in the output to use this feature.\n- Press TAB to chdir one level down into the directory of the file listed\n  or viewed at the top of the screen.  If no directory exists, the file itself\n  is selected to search.  Press Shift-TAB to go back up one level.\n- Press CTRL-] to toggle colors on and off.  Normally ugrep in query mode uses\n  colors and other markup to highlight results.  When colors are turned off,\n  selected results are also not colored in the output produced by ugrep when\n  ugrep exits.  When colors are turned on (the default), selected results are\n  colored depending on the `--color` option.\n- The query engine is optimized to limit system load by performing on-demand\n  searches to produce results only for the visible parts shown in the\n  interface.  That is, results are shown on demand, when scrolling down and\n  when exiting when all results are selected.  When the search pattern is\n  modified, the previous search query is cancelled when incomplete.  This\n  effectively limits the load on the system to maintain a high degree of\n  responsiveness of the query engine to user input.  Because the search results\n  are produced on demand, occasionally you may notice a flashing \"Searching...\"\n  message when searching files.\n- To display results faster, specify a low `DELAY` value such as 1.  However,\n  lower values may increase system load as a result of repeatedly initiating\n  and cancelling searches by each key pressed.\n- To avoid long pathnames to obscure the view, `--heading` is enabled by\n  default.  Press Alt-+ to switch headings off.\n\nQuery TUI key mapping:\n\nkey(s)           | function\n---------------- | -------------------------------------------------\n`Alt-key`        | toggle ugrep command-line option corresponding to `key`\n`Alt-/`xxxx`/`   | insert Unicode hex code point U+xxxx\n`Esc` `Ctrl-C`   | go back or exit\n`Ctrl-Q`         | quick exit and output the results selected in selection mode\n`Tab`            | chdir to the directory of the file shown at the top of the screen or select file\n`Shift-Tab`      | chdir one level up or deselect file\n`Enter`          | enter selection mode and toggle selected lines to output on exit\n`Up` `Ctrl-P`    | move up\n`Down` `Ctrl-N`  | move down\n`Left` `Ctrl-B`  | move left\n`Right` `Ctrl-F` | move right\n`PgUp` `Ctrl-G`  | move display up by a page\n`PgDn` `Ctrl-D`  | move display down by a page\n`Alt-Up`         | move display up by 1/2 page (MacOS `Shift-Up`)\n`Alt-Down`       | move display down by 1/2 page (MacOS `Shift-Down`)\n`Alt-Left`       | move display left by 1/2 page (MacOS `Shift-Left`)\n`Alt-Right`      | move display right by 1/2 page (MacOS `Shift-Right`)\n`Home` `Ctrl-A`  | move cursor to the beginning of the line\n`End` `Ctrl-E`   | move cursor to the end of the line\n`Ctrl-K`         | delete after cursor\n`Ctrl-L`         | refresh screen\n`Ctrl-O`+`key`   | toggle ugrep command-line option corresponding to `key`, same as `Alt-key`\n`Ctrl-R` `F4`    | jump to bookmark\n`Ctrl-S`         | jump to the next dir/file/context\n`Ctrl-T` `F5`    | toggle split screen (`--split` starts a split-screen TUI)\n`Ctrl-U`         | delete before cursor\n`Ctrl-V`         | verbatim character\n`Ctrl-W`         | jump back one dir/file/context\n`Ctrl-X` `F3`    | set bookmark\n`Ctrl-Y` `F2`    | view or edit the file shown at the top of the screen\n`Ctrl-Z` `F1`    | view help and options\n`Ctrl-^`         | chdir back to the starting working directory\n`Ctrl-]`         | toggle color/mono\n`Ctrl-\\`         | terminate process\n\nTo interactively search the files in the working directory and below:\n\n    ug -Q\n\nSame, but restricted to C++ files only and ignoring `.gitignore` files:\n\n    ug -Q -tc++ --ignore-files\n\nTo interactively search all makefiles in the working directory and below:\n\n    ug -Q -g 'Makefile*' -g 'makefile*'\n\nSame, but for up to 2 directory levels (working and one subdirectory level):\n\n    ug -Q -2 -g 'Makefile*' -g 'makefile*'\n\nTo interactively view the contents of `main.cpp` and search it, where `-y`\nshows any nonmatching lines as context:\n\n    ug -Q -y main.cpp\n\nTo interactively search `main.cpp`, starting with the search pattern `TODO` and\na match context of 5 lines (context can be interactively enabled and disabled,\nthis also overrides the default context size of 2 lines):\n\n    ug -Q -C5 -e TODO main.cpp\n\nTo view and search the contents of an archive (e.g. zip, tarball):\n\n    ug -Q -z archive.tar.gz\n\nTo interactively select files from `project.zip` to decompress with `unzip`,\nusing ugrep query selection mode (press Enter to select lines):\n\n    unzip project.zip `zipinfo -1 project.zip | ugrep -Q`\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"recursion\"/\u003e\n\n### Recursively list matching files with -l, -R, -r, -S, --depth, -g, -O, and -t\n\n    -L, --files-without-match\n            Only the names of files not containing selected lines are written\n            to standard output.  Pathnames are listed once per file searched.\n            If the standard input is searched, the string ``(standard input)''\n            is written.\n    -l, --files-with-matches\n            Only the names of files containing selected lines are written to\n            standard output.  ugrep will only search a file until a match has\n            been found, making searches potentially less expensive.  Pathnames\n            are listed once per file searched.  If the standard input is\n            searched, the string ``(standard input)'' is written.\n    -R, --dereference-recursive\n            Recursively read all files under each directory.  Follow all\n            symbolic links to files and directories, unlike -r.\n    -r, --recursive\n            Recursively read all files under each directory, following symbolic\n            links only if they are on the command line.  Note that when no FILE\n            arguments are specified and input is read from a terminal,\n            recursive searches are performed as if -r is specified.\n    -S, --dereference-files\n            When -r is specified, symbolic links to files are followed, but not\n            to directories.  The default is not to follow symbolic links.\n    --depth=[MIN,][MAX], -1, -2, -3, ... -9, -10, -11, -12, ...\n            Restrict recursive searches from MIN to MAX directory levels deep,\n            where -1 (--depth=1) searches the specified path without recursing\n            into subdirectories.  Note that -3 -5, -3-5, and -35 search 3 to 5\n            levels deep.  Enables -r if -R or -r is not specified.\n    -g GLOBS, --glob=GLOBS\n            Search only files whose name matches the specified comma-separated\n            list of GLOBS, same as --include='glob' for each `glob' in GLOBS.\n            When a `glob' is preceded by a `!' or a `^', skip files whose name\n            matches `glob', same as --exclude='glob'.  When `glob' contains a\n            `/', full pathnames are matched.  Otherwise basenames are matched.\n            When `glob' ends with a `/', directories are matched, same as\n            --include-dir='glob' and --exclude-dir='glob'.  A leading `/'\n            matches the working directory.  This option may be repeated and may\n            be combined with options -M, -O and -t to expand searches.  See\n            `ugrep --help globs' and `man ugrep' section GLOBBING for details.\n    -O EXTENSIONS, --file-extension=EXTENSIONS\n            Search only files whose filename extensions match the specified\n            comma-separated list of EXTENSIONS, same as --include='*.ext' for\n            each `ext' in EXTENSIONS.  When `ext' is preceded by a `!' or a\n            `^', skip files whose filename extensions matches `ext', same as\n            --exclude='*.ext'.  This option may be repeated and may be combined\n            with options -g, -M and -t to expand the recursive search.\n    -t TYPES, --file-type=TYPES\n            Search only files associated with TYPES, a comma-separated list of\n            file types.  Each file type corresponds to a set of filename\n            extensions passed to option -O and filenames passed to option -g.\n            For capitalized file types, the search is expanded to include files\n            with matching file signature magic bytes, as if passed to option\n            -M.  When a type is preceded by a `!' or a `^', excludes files of\n            the specified type.  This option may be repeated.\n    --stats\n            Output statistics on the number of files and directories searched,\n            and the inclusion and exclusion constraints applied.\n\nIf no FILE arguments are specified and input is read from a terminal, recursive\nsearches are performed as if `-r` is specified.  To force reading from standard\ninput, specify `-` as the FILE argument.\n\nTo recursively list all non-empty files in the working directory:\n\n    ug -r -l ''\n\nTo list all non-empty files in the working directory but not deeper (since a\nFILE argument is given, in this case `.` for the working directory):\n\n    ug -l '' .\n\nTo list all non-empty files in directory `mydir` but not deeper (since a FILE\nargument is given):\n\n    ug -l '' mydir\n\nTo list all non-empty files in directory `mydir` and deeper while following\nsymlinks:\n\n    ug -R -l '' mydir\n\nTo recursively list all non-empty files on the path specified, while visiting\nsubdirectories only, i.e. directories `mydir/` and subdirectories at one\nlevel deeper `mydir/*/` are visited (note that `-2 -l` can be abbreviated to\n`-l2`):\n\n    ug -2 -l '' mydir\n\nTo recursively list all non-empty files in directory `mydir`, not following any\nsymbolic links (except when on the command line such as `mydir`):\n\n    ug -rl '' mydir\n\nTo recursively list all Makefiles matching the text `CPP`:\n\n    ug -l -tmake 'CPP'\n\nTo recursively list all `Makefile.*` matching `bin_PROGRAMS`:\n\n    ug -l -g'Makefile.*' 'bin_PROGRAMS'\n\nTo recursively list all non-empty files with extension .sh, with `-Osh`:\n\n    ug -l -Osh ''\n\nTo recursively list all shell scripts based on extensions and shebangs with\n`-tShell`:\n\n    ug -l -tShell ''\n\nTo recursively list all shell scripts based on extensions only with `-tshell`:\n\n    ug -l -tshell ''\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"bool\"/\u003e\n\n### Boolean query patterns with -%, -%%, --and, --not\n\n    --bool, -%, -%%\n            Specifies Boolean query patterns.  A Boolean query pattern is\n            composed of `AND', `OR', `NOT' operators and grouping with `(' `)'.\n            Spacing between subpatterns is the same as `AND', `|' is the same\n            as `OR' and a `-' is the same as `NOT'.  The `OR' operator binds\n            more tightly than `AND'.  For example, --bool 'A|B C|D' matches\n            lines with (`A' or `B') and (`C' or `D'), --bool 'A -B' matches\n            lines with `A' and not `B'.  Operators `AND', `OR', `NOT' require\n            proper spacing.  For example, --bool 'A OR B AND C OR D' matches\n            lines with (`A' or `B') and (`C' or `D'), --bool 'A AND NOT B'\n            matches lines with `A' without `B'.  Quoted subpatterns are matched\n            literally as strings.  For example, --bool 'A \"AND\"|\"OR\"' matches\n            lines with `A' and also either `AND' or `OR'.  Parentheses are used\n            for grouping.  For example, --bool '(A B)|C' matches lines with `A'\n            and `B', or lines with `C'.  Note that all subpatterns in a Boolean\n            query pattern are regular expressions, unless -F is specified.\n            Options -E, -F, -G, -P and -Z can be combined with --bool to match\n            subpatterns as strings or regular expressions (-E is the default.)\n            This option does not apply to -f FILE patterns.  The double short\n            option -%% enables options --bool --files.  Option --stats displays\n            the Boolean search patterns applied.  See also options --and,\n            --andnot, --not, --files and --lines.\n    --files\n            Boolean file matching mode, the opposite of --lines.  When combined\n            with option --bool, matches a file if all Boolean conditions are\n            satisfied.  For example, --bool --files 'A B|C -D' matches a file\n            if some lines match `A', and some lines match either `B' or `C',\n            and no line matches `D'.  See also options --and, --andnot, --not,\n            --bool and --lines.  The double short option -%% enables options\n            --bool --files.\n    --lines\n            Boolean line matching mode for option --bool, the default mode.\n    --and [[-e] PATTERN] ... -e PATTERN\n            Specify additional patterns to match.  Patterns must be specified\n            with -e.  Each -e PATTERN following this option is considered an\n            alternative pattern to match, i.e. each -e is interpreted as an OR\n            pattern.  For example, -e A -e B --and -e C -e D matches lines with\n            (`A' or `B') and (`C' or `D').  Note that multiple -e PATTERN are\n            alternations that bind more tightly together than --and.  Option\n            --stats displays the search patterns applied.  See also options\n            --not, --andnot, and --bool.\n    --andnot [[-e] PATTERN] ...\n            Combines --and --not.  See also options --and, --not, and --bool.\n    --not [-e] PATTERN\n            Specifies that PATTERN should not match.  Note that -e A --not -e B\n            matches lines with `A' or lines without a `B'.  To match lines with\n            `A' that have no `B', specify -e A --andnot -e B.  Option --stats\n            displays the search patterns applied.  See also options --and,\n            --andnot, and --bool.\n    --stats\n            Output statistics on the number of files and directories searched,\n            and the inclusion and exclusion constraints applied.\n\nNote that the `--and`, `--not`, and `--andnot` options require `-e PATTERN`.\n\nThe `-%` option makes all patterns Boolean-based, supporting the following\nlogical operations listed from the highest level of precedence to the lowest:\n\noperator | alternative | result\n-------- | ----------- | -------\n`\"x\"`    |             | match `x` literally and exactly as specified (using the standard regex escapes `\\Q` and `\\E`)\n`( )`    |             | Boolean expression grouping\n`-x`     | `NOT x`     | inverted match, i.e. matches if `x` does not match\n`x\\|y`   | `x OR y`    | matches lines with `x` or `y`\n`x y`    | `x AND y`   | matches lines with both `x` and `y`\n\n- `x` and `y` are subpatterns that do not start with the special symbols `|`,\n  `-`, and `(` (use quotes or a `\\` escape to match these);\n\n- `-` and `NOT` are the same and take precedence over `OR`, which means that\n  `-x|y` == `(-x)|y` for example.\n\n- `|` and `OR` are the same and take precedence over `AND`, which means that\n  `x y|z` == `x (y|z)` for example;\n\nThe `--stats` option displays the Boolean queries in human-readable form\nconverted to CNF (Conjunctive Normal Form), after the search is completed.\nTo show the CNF without a search, read from standard input terminated by an\nEOF, like `echo | ugrep -% '...' --stats`.\n\nSubpatterns are color-highlighted in the output, except those negated with\n`NOT` (a `NOT` subpattern may still show up in a matching line when using an\nOR-NOT pattern like `x|-y`).  Note that subpatterns may overlap.  In that\ncase only the first matching subpattern is color-highlighted.\n\nMultiple lines may be matched when subpatterns match newlines.  There is one\nexception however: subpatterns ending with `(?=X)` lookaheads may not match\nwhen `X` spans multiple lines.\n\nEmpty patterns match any line (grep standard).  Therefore, `-% 'x|\"\"|y'`\nmatches everything and `x` and `y` are not color-highlighted.  Option `-y`\nshould be used to show every line as context, for example `-y 'x|y'`.\n\nFzf-like interactive querying (Boolean search with fixed strings with fuzzy\nmatching to allow e.g. up to 4 extra characters matched with `-Z+4` in words\nwith `-w`), press TAB and ALT-y to view a file with matches.  Press SHIFT-TAB\nand ALT-l to go back to the list of matching files:\n\n    ug -Q -%% -l -w -F -Z+4 --sort=best\n\nTo recursively find all files containing both `hot` and `dog` anywhere in the\nfile with option `--files`:\n\n    ug -%% 'hot dog'\n    ug --files -e hot --and dog\n\nTo find lines containing both `hot` and `dog` in `myfile.txt`:\n\n    ug -% 'hot dog' myfile.txt\n    ug -e hot --and dog myfile.txt\n\nTo find lines containing `place` and then also `hotdog` or `taco` (or both) in\n`myfile.txt`:\n\n    ug -% 'hotdog|taco place' myfile.txt\n    ug -e hotdog -e taco --and place myfile.txt\n\nSame, but exclude lines matching `diner`:\n\n    ug -% 'hotdog|taco place -diner' myfile.txt\n    ug -e hotdog -e taco --and place --andnot diner myfile.txt\n\nTo find lines with `diner` or lines that match both `fast` and `food` but not `bad` in `myfile.txt`:\n\n    ug -% 'diner|(fast food -bad)' myfile.txt\n\nTo find lines with `fast food` (exactly) or lines with `diner` but not `bad` or `old` in `myfile.txt`:\n\n    ug -% '\"fast food\"|diner -bad -old' myfile.txt\n\nSame, but using a different Boolean expression that has the same meaning:\n\n    ug -% '\"fast food\"|diner -(bad|old)' myfile.txt\n\nTo find lines with `diner` implying `good` in `myfile.txt` (that is, show lines\nwith `good` without `diner` and show lines with `diner` but only those with\n`good`, which is logically implied!):\n\n    ug -% 'good|-diner' myfile.txt\n    ug -e good --not diner myfile.txt\n\nTo find lines with `foo` and `-bar` and `\"baz\"` in `myfile.txt` (not that `-`\nand `\"` should be matched using `\\` escapes and with `--and -e -bar`):\n\n    ug -% 'foo \\-bar \\\"baz\\\"' myfile.txt\n    ug -e foo --and -e -bar --and '\"baz\"' myfile.txt\n\nTo search `myfile.cpp` for lines with `TODO` or `FIXME` but not both on the\nsame line, like XOR:\n\n    ug -% 'TODO|FIXME -(TODO FIXME)' myfile.cpp\n    ug -e TODO -e FIXME --and --not TODO --not FIXME myfile.cpp\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"not\"/\u003e\n\n### Search this but not that with -v, -e, -N, -f, -L, -w, -x\n\n    -e PATTERN, --regexp=PATTERN\n            Specify a PATTERN to search the input.  An input line is selected\n            if it matches any of the specified patterns.  This option is useful\n            when multiple -e options are used to specify multiple patterns, or\n            when a pattern begins with a dash (`-'), or to specify a pattern\n            after option -f or after the FILE arguments.\n    -f FILE, --file=FILE\n            Read newline-separated patterns from FILE.  White space in patterns\n            is significant.  Empty lines in FILE are ignored.  If FILE does not\n            exist, the GREP_PATH environment variable is used as path to FILE.\n            If that fails, looks for FILE in /usr/local/share/ugrep/pattern.\n            When FILE is a `-', standard input is read.  This option may be\n            repeated.\n    -L, --files-without-match\n            Only the names of files not containing selected lines are written\n            to standard output.  Pathnames are listed once per file searched.\n            If the standard input is searched, the string ``(standard input)''\n            is written.\n    -N PATTERN, --neg-regexp=PATTERN\n            Specify a negative PATTERN to reject specific -e PATTERN matches\n            with a counter pattern.  Note that longer patterns take precedence\n            over shorter patterns, i.e. a negative pattern must be of the same\n            length or longer to reject matching patterns.  Option -N cannot be\n            specified with -P.  This option may be repeated.\n    -v, --invert-match\n            Selected lines are those not matching any of the specified\n            patterns.\n    -w, --word-regexp\n            The PATTERN is searched for as a word, such that the matching text\n            is preceded by a non-word character and is followed by a non-word\n            character.  Word-like characters are Unicode letters, digits and\n            connector punctuations such as underscore.\n    -x, --line-regexp\n            Select only those matches that exactly match the whole line, as if\n            the patterns are surrounded by ^ and $.\n\nSee also [Boolean query patterns with -%, -%%, --and, --not](#bool) for\nmore powerful Boolean query options than the traditional GNU/BSD grep options.\n\nTo display lines in file `myfile.sh` but not lines matching `^[ \\t]*#`:\n\n    ug -v '^[ \\t]*#' myfile.sh\n\nTo search `myfile.cpp` for lines with `FIXME` and `urgent`, but not `Scotty`:\n\n    ugrep FIXME myfile.cpp | ugrep urgent | ugrep -v Scotty\n\nSame, but using `-%` for Boolean queries:\n\n    ug -% 'FIXME urgent -Scotty' myfile.cpp\n\nTo search for decimals using pattern `\\d+` that do not start with `0` using\nnegative pattern `0\\d+` and excluding `555`:\n\n    ug -e '\\d+' -N '0\\d+' -N 555 myfile.cpp\n\nTo search for words starting with `disp` without matching `display` in file\n`myfile.py` by using a \"negative pattern\" `-N '/\u003cdisplay\\\u003e'` where `-N`\nspecifies an additional negative pattern to skip matches:\n\n    ug -e '\\\u003cdisp' -N '\\\u003cdisplay\\\u003e' myfile.py\n\nTo search for lines with the word `display` in file `myfile.py` skipping this\nword in strings and comments, where `-f` specifies patterns in files which are\npredefined patterns in this case:\n\n    ug -n -w 'display' -f python/zap_strings -f python/zap_comments myfile.py\n\nTo display lines that are not blank lines:\n\n    ug -x -e '.*' -N '\\h*' myfile.py\n\nSame, but using `-v` and `-x` with `\\h*`, i.e. pattern `^\\h*$`:\n\n    ug -v -x '\\h*' myfile.py\n\nTo recursively list all Python files that do not contain the word `display`,\nallowing the word to occur in strings and comments:\n\n    ug -RL -tPython -w 'display' -f python/zap_strings -f python/zap_comments\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"encoding\"/\u003e\n\n### Search non-Unicode files with --encoding\n\n    --encoding=ENCODING\n            The encoding format of the input.  The default ENCODING is binary\n            and UTF-8 which are the same.  Note that option -U specifies binary\n            PATTERN matching (text matching is the default.)\n\nBinary, ASCII and UTF-8 files do not require this option to search them.  Also\nUTF-16 and UTF-32 files do not require this option to search them, assuming\nthat UTF-16 and UTF-32 files start with a UTF BOM\n([byte order mark](https://en.wikipedia.org/wiki/Byte_order_mark)) as usual.\nOther file encodings require option `--encoding=ENCODING`:\n\nencoding               | parameter\n---------------------- | --------------\nASCII                  | *n/a*\nUTF-8                  | *n/a*\nUTF-16 with BOM        | *n/a*\nUTF-32 with BOM        | *n/a*\nUTF-16 BE w/o BOM      | `UTF-16` or `UTF-16BE`\nUTF-16 LE w/o BOM      | `UTF-16LE`\nUTF-32 w/o BOM         | `UTF-32` or `UTF-32BE`\nUTF-32 w/o BOM         | `UTF-32LE`\nLatin-1                | `LATIN1` or `ISO-8859-1`\nISO-8859-1             | `ISO-8859-1`\nISO-8859-2             | `ISO-8859-2`\nISO-8859-3             | `ISO-8859-3`\nISO-8859-4             | `ISO-8859-4`\nISO-8859-5             | `ISO-8859-5`\nISO-8859-6             | `ISO-8859-6`\nISO-8859-7             | `ISO-8859-7`\nISO-8859-8             | `ISO-8859-8`\nISO-8859-9             | `ISO-8859-9`\nISO-8859-10            | `ISO-8859-10`\nISO-8859-11            | `ISO-8859-11`\nISO-8859-13            | `ISO-8859-13`\nISO-8859-14            | `ISO-8859-14`\nISO-8859-15            | `ISO-8859-15`\nISO-8859-16            | `ISO-8859-16`\nMAC (CR=newline)       | `MAC`\nMacRoman (CR=newline)  | `MACROMAN`\nEBCDIC                 | `EBCDIC`\nDOS code page 437      | `CP437`\nDOS code page 850      | `CP850`\nDOS code page 858      | `CP858`\nWindows code page 1250 | `CP1250`\nWindows code page 1251 | `CP1251`\nWindows code page 1252 | `CP1252`\nWindows code page 1253 | `CP1253`\nWindows code page 1254 | `CP1254`\nWindows code page 1255 | `CP1255`\nWindows code page 1256 | `CP1256`\nWindows code page 1257 | `CP1257`\nWindows code page 1258 | `CP1258`\nKOI8-R                 | `KOI8-R`\nKOI8-U                 | `KOI8-U`\nKOI8-RU                | `KOI8-RU`\n\nNote that regex patterns are always specified in UTF-8 (includes ASCII).  To\nsearch binary files with binary patterns, see\n[searching and displaying binary files with -U, -W, and -X](#binary).\n\nTo recursively list all files that are ASCII (i.e. 7-bit):\n\n    ug -L '[^[:ascii:]]'\n\nTo recursively list all files that are non-ASCII, i.e. UTF-8, UTF-16, and\nUTF-32 files with non-ASCII Unicode characters (U+0080 and up):\n\n    ug -l '[^[:ascii:]]'\n\nTo check if a file contains non-ASCII Unicode (U+0080 and up):\n\n    ug -q '[^[:ascii:]]' myfile \u0026\u0026 echo \"contains Unicode\"\n\nTo remove invalid Unicode characters from a file (note that `-o` may not work\nbecause binary data is detected and rejected and newlines are added, but\n`--format=\"%o%` does not check for binary and copies the match \"as is\"):\n\n    ug \"[\\p{Unicode}\\n]\" --format=\"%o\" badfile.txt\n\nTo recursively list files with invalid UTF content (i.e. invalid UTF-8 byte\nsequences or files that contain any UTF-8/16/32 code points that are outside\nthe valid Unicode range) by matching any code point with `.` and by using a\nnegative pattern `-N '\\p{Unicode}'` to ignore each valid Unicode character:\n\n    ug -l -e '.' -N '\\p{Unicode}'\n\nTo display lines containing laughing face emojis:\n\n    ug '[😀-😏]' emojis.txt\n\nThe same results are obtained using `\\x{hhhh}` to select a Unicode character\nrange:\n\n    ug '[\\x{1F600}-\\x{1F60F}]' emojis.txt\n\nTo display lines containing the names Gödel (or Goedel), Escher, or Bach:\n\n    ug 'G(ö|oe)del|Escher|Bach' GEB.txt wiki.txt\n\nTo search for `lorem` in lower or upper case in a UTF-16 file that is marked\nwith a UTF-16 BOM:\n\n    ug -iw 'lorem' utf16lorem.txt\n\nTo search utf16lorem.txt when this file has no UTF-16 BOM, using `--encoding`:\n\n    ug --encoding=UTF-16 -iw 'lorem' utf16lorem.txt\n\nTo search file `spanish-iso.txt` encoded in ISO-8859-1:\n\n    ug --encoding=ISO-8859-1 -w 'año' spanish-iso.txt\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"multiline\"/\u003e\n\n### Matching multiple lines of text\n\n    -o, --only-matching\n            Output only the matching part of lines.  If -A, -B or -C is\n            specified, fits the match and its context on a line within the\n            specified number of columns.\n\nMultiple lines may be matched by patterns that match newline characters.  Use\noption `-o` to output the match only, not the full lines(s) that match.\n\nTo match a `\\n` line break, include `\\n` in the pattern to match the LF\ncharacter.  If you want to match `\\r\\n` and `\\n` line breaks, use `\\r?\\n` or\nsimply use `\\R` to match any Unicode line break `\\r\\n`, `\\r`, `\\v`, `\\f`, `\\n`,\nU+0085, U+2028 and U+2029.\n\nTo match C/C++ `/*...*/` multi-line comments:\n\n    ug '/\\*(.*\\n)*?.*\\*+\\/' myfile.cpp\n\nTo match C/C++ comments using the predefined `c/comments` patterns with\n`-f c/comments`, restricted to the matching part only with option `-o`:\n\n    ug -of c/comments myfile.cpp\n\nSame as `sed -n '/begin/,/end/p'`: to match all lines between a line containing\n`begin` and the first line after that containing `end`, using lazy repetition:\n\n    ug -o '.*begin(.|\\n)*?end.*' myfile.txt\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"context\"/\u003e\n\n### Displaying match context with -A, -B, -C, -y, and --width\n\n    -A NUM, --after-context=NUM\n            Output NUM lines of trailing context after matching lines.  Places\n            a --group-separator between contiguous groups of matches.  If -o is\n            specified, output the match with context to fit NUM columns after\n            the match or shortens the match.  See also options -B, -C and -y.\n    -B NUM, --before-context=NUM\n            Output NUM lines of leading context before matching lines.  Places\n            a --group-separator between contiguous groups of matches.  If -o is\n            specified, output the match with context to fit NUM columns before\n            the match or shortens the match.  See also options -A, -C and -y.\n    -C NUM, --context=NUM\n            Output NUM lines of leading and trailing context surrounding each\n            matching line.  Places a --group-separator between contiguous\n            groups of matches.  If -o is specified, output the match with\n            context to fit NUM columns before and after the match or shortens\n            the match.  See also options -A, -B and -y.\n    -y, --any-line\n            Any line is output (passthru).  Non-matching lines are output as\n            context with a `-' separator.  See also options -A, -B, and -C.\n    --width[=NUM]\n            Truncate the output to NUM visible characters per line.  The width\n            of the terminal window is used if NUM is not specified.  Note that\n            double wide characters in the output may result in wider lines.\n    -o, --only-matching\n            Output only the matching part of lines.  If -A, -B or -C is\n            specified, fits the match and its context on a line within the\n            specified number of columns.\n\nTo display two lines of context before and after a matching line:\n\n    ug -C2 'FIXME' myfile.cpp\n\nTo show three lines of context after a matched line:\n\n    ug -A3 'FIXME.*' myfile.cpp:\n\nTo display one line of context before each matching line with a C function\ndefinition (C names are non-Unicode):\n\n    ug -B1 -f c/functions myfile.c\n\nTo display one line of context before each matching line with a C++ function\ndefinition (C++ names may be Unicode):\n\n    ug -B1 -f c++/functions myfile.cpp\n\nTo display any non-matching lines as context for matching lines with `-y`:\n\n    ug -y -f c++/functions myfile.cpp\n\nTo display a hexdump of a matching line with one line of hexdump context:\n\n    ug -C1 -UX '\\xaa\\xbb\\xcc' a.out\n\nContext within a line is displayed with option `-o` with a context option:\n\n    ug -o -C20 'pattern' myfile.cpp\n\nSame, but with pretty output with headings, line numbers and column numbers\n(`-k`) and showing context:\n\n    ug --pretty -oC20 'pattern' myfile.cpp\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"source\"/\u003e\n\n### Searching source code using -f, -g, -O, and -t\n\n    -f FILE, --file=FILE\n            Read newline-separated patterns from FILE.  White space in patterns\n            is significant.  Empty lines in FILE are ignored.  If FILE does not\n            exist, the GREP_PATH environment variable is used as path to FILE.\n            If that fails, looks for FILE in /usr/local/share/ugrep/pattern.\n            When FILE is a `-', standard input is read.  This option may be\n            repeated.\n    --ignore-files[=FILE]\n            Ignore files and directories matching the globs in each FILE that\n            is encountered in recursive searches.  The default FILE is\n            `.gitignore'.  Matching files and directories located in the\n            directory of the FILE and in subdirectories below are ignored.\n            Globbing syntax is the same as the --exclude-from=FILE gitignore\n            syntax, but files and directories are excluded instead of only\n            files.  Directories are specifically excluded when the glob ends in\n            a `/'.  Files and directories explicitly specified as command line\n            arguments are never ignored.  This option may be repeated to\n            specify additional files.\n    -g GLOBS, --glob=GLOBS\n            Search only files whose name matches the specified comma-separated\n            list of GLOBS, same as --include='glob' for each `glob' in GLOBS.\n            When a `glob' is preceded by a `!' or a `^', skip files whose name\n            matches `glob', same as --exclude='glob'.  When `glob' contains a\n            `/', full pathnames are matched.  Otherwise basenames are matched.\n            When `glob' ends with a `/', directories are matched, same as\n            --include-dir='glob' and --exclude-dir='glob'.  A leading `/'\n            matches the working directory.  This option may be repeated and may\n            be combined with options -M, -O and -t to expand searches.  See\n            `ugrep --help globs' and `man ugrep' section GLOBBING for details.\n    -O EXTENSIONS, --file-extension=EXTENSIONS\n            Search only files whose filename extensions match the specified\n            comma-separated list of EXTENSIONS, same as --include='*.ext' for\n            each `ext' in EXTENSIONS.  When `ext' is preceded by a `!' or a\n            `^', skip files whose filename extensions matches `ext', same as\n            --exclude='*.ext'.  This option may be repeated and may be combined\n            with options -g, -M and -t to expand the recursive search.\n    -t TYPES, --file-type=TYPES\n            Search only files associated with TYPES, a comma-separated list of\n            file types.  Each file type corresponds to a set of filename\n            extensions passed to option -O and filenames passed to option -g.\n            For capitalized file types, the search is expanded to include files\n            with matching file signature magic bytes, as if passed to option\n            -M.  When a type is preceded by a `!' or a `^', excludes files of\n            the specified type.  This option may be repeated.\n    --stats\n            Output statistics on the number of files and directories searched,\n            and the inclusion and exclusion constraints applied.\n\nThe file types are listed with `ugrep -tlist`.  The list is based on\nestablished filename extensions and \"magic bytes\".  If you have a file type\nthat is not listed, use options `-O` and/or `-M`.  You may want to define an\nalias, e.g. `alias ugft='ugrep -Oft'` as a shorthand to search files with\nfilename suffix `.ft`.\n\nTo recursively display function definitions in C/C++ files (`.h`, `.hpp`, `.c`,\n`.cpp` etc.) with line numbers with `-tc++`, `-o`, `-n`, and `-f c++/functions`:\n\n    ug -on -tc++ -f c++/functions\n\nTo recursively display function definitions in `.c` and `.cpp` files with line\nnumbers with `-Oc,cpp`, `-o`, `-n`, and `-f c++/functions`:\n\n    ug -on -Oc,cpp -f c++/functions\n\nTo recursively list all shell files with `-tShell` to match filename extensions\nand files with shell shebangs, except files with suffix `.sh`:\n\n    ug -l -tShell -O^sh ''\n\nTo recursively list all non-shell files with `-t^Shell`:\n\n    ug -l -t^Shell ''\n\nTo recursively list all shell files with shell shebangs that have no shell\nfilename extensions:\n\n    ug -l -tShell -t^shell ''\n\nTo search for lines with `FIXME` in C/C++ comments, excluding `FIXME` in\nmulti-line strings:\n\n    ug -n 'FIXME' -f c++/zap_strings myfile.cpp\n\nTo read patterns `TODO` and `FIXME` from standard input to match lines in the\ninput, while excluding matches in C++ strings:\n\n    ug -on -f - -f c++/zap_strings myfile.cpp \u003c\u003cEND\n    TODO\n    FIXME\n    END\n\nTo display XML element and attribute tags in an XML file, restricted to the\nmatching part with `-o`, excluding tags that are placed in (multi-line)\ncomments:\n\n    ug -o -f xml/tags -f xml/zap_comments myfile.xml\n\n🔝 [Back to table of contents](#toc)\n\n\u003ca name=\"archives\"/\u003e\n\n### Searching compressed files and archives with -z\n\n    -z, --decompress\n            Search compressed files and archives.  Archives (.cpio, .pax, .tar)\n            and compressed archives (e.g. .zip, .7z, .taz, .tgz, .tpz, .tbz,\n            .tbz2, .tb2, .tz2, .tlz, .txz, .tzst) are searched and matching\n            pathnames of files in archives are output in braces.  When used\n            with option --zmax=NUM, searches the contents of compressed files\n            and archives stored within archives up to NUM levels.  When -g, -O,\n            -M, or -t is specified, searches archives for files that match the\n            specified globs, filename extensions, file signature magic bytes,\n            or file types, respectively; a side-effect of these options is that\n            the compressed files and archives searched are only those with\n            filename extensions that match known compression and archive types.\n            Supported compression formats: gzip (.gz), compress (.Z), zip, 7z,\n            bzip2 (.bz, .bz2, .bzip2, .tbz, .tbz2, .tb2, .tz2),\n            xz (.xz, .txz) and lzma (requires suffix .lzma, .tlz),\n            zstd (.zst, .zstd, .tzst),\n            lz4 (requires suffix .lz4),\n            brotli (requires suffix .br).\n    --zmax=NUM\n            When used with option -z (--decompress), searches the contents of\n            compressed files and archives stored within archives by up to NUM\n            expansion stages.  The default --zmax=1 only permits searching\n            uncompressed files stored in cpio, pax, tar, zip and 7z archives;\n            compressed files and archives are detected as binary files and are\n            effectively ignored.  Specify --zmax=2 to search compressed files\n            and archives stored in cpio, pax, tar, zip and 7z archives.  NUM\n            may range from 1 to 99 for up to 99 decompression and de-archiving\n            steps.  Increasing NUM values gradually degrades performance.\n\nFiles compressed with gzip (`.gz`), compress (`.Z`), bzip2 (`.bz`, `.bz2`,\n`.bzip2`), lzma (`.lzma`), xz (`.xz`), lz4 (`.lz4`), zstd (`.zst`, `.zstd`),\nbrotli (`.br`) and bzip3 (`.bz3`) are searched with option `-z` when the\ncorresponding libraries are installed and compiled with ugrep.  This option\ndoes not require files to be compressed.  Uncompressed files are searched also,\nalthough slower.\n\nOther compression formats can be searched with **ugrep** [filters](#filter).\n\nArchives (cpio, jar, pax, tar, zip and 7z) are searched with option `-z`.\nRegular files in an archive that match are output with the archive pathnames\nenclosed in `{` and `}` braces.  Supported tar formats are v7, ustar, gnu,\noldgnu, and pax.  Supported cpio formats are odc, newc, and crc.  Not supported\nis the obsolete non-portable old binary cpio format.  Archive formats cpio,\ntar, and pax are automatically recognized with option `-z` based on their\ncontent, independent of their filename suffix.\n\nBy default, uncompressed archives stored within zip archives are also searched:\nall cpio, pax, and tar files stored in zip and 7z archives are automatically\nrecognized and searched.  However, by default, compressed files stored within\narchives are not recognized, e.g. zip files stored within tar files are not\nsearched but rather all compressed files and archives are searched as if they\nare binary files without decompressing them.\n\nSpecify `--zmax=NUM` to search archives that contain compressed files and\narchives for up to `NUM` levels deep.  The value of `NUM` may range from 1 to\n99 for up to 99 decompression and de-archiving steps to expand up to 99 nested\narchives.  Larger `--zmax=NUM` values degrade performance.  It is unlikely you\nwill ever need 99 as `--zmax=2` suffices for most practical use cases, such as\nsearching zip files stored in tar files.\n\nWhen option `-z` is used with options `-g`, `-O`, `-M`, or `-t`, archives and\ncompressed and uncompressed files that match the filename selection criteria\n(glob, extension, magic bytes, or file type) are searched only.  For example,\n`ugrep -r -z -tc++` searches C++ files such as `main.cpp` and zip and tar\narchives that contain C++ files such as `main.cpp`.  Also included in the\nsearch are compressed C++ files such as `main.cpp.gz` and `main.cpp.xz` when\npresent.  Also any cpio, pax, tar, zip and 7z archives when present are\nsearched for C++ files that they contain, such as `main.cpp`.  Use option\n`--stats` to see a list of the glob patterns applied to filter file pathnames\nin the recursive search and when searching archive contents.\n\nWhen option `-z` is used with options `-g`, `-O`, `-M`, or `-t` to search cpio,\njar, pax, tar, zip and 7z archives, archived files that match the filename\nselection criteria are searched only.\n\nThe gzip, compress, zip, bzip2, xz, and zstd formats are automatically\ndetected, which is useful when reading compressed data from standard input,\ne.g. input redirected from a pipe.  Other compression formats require a\nfilename suffix: `.lzma` for lzma, `.lz4` for lz4, `.br` for brotli and `.bz3`\nfor bzip3.  Also the compressed tar archive shorthands `.taz`, `.tgz` and\n`.tpz` for gzip, `.tbz`, `.tbz2`, `.tb2`, and `.tz2` for bzip2, `.tlz` for\nlzma, `.txz` for xz, and `.tzst` for zstd are recognized.  To search these\nformats with ugrep from standard input, use option `--label='stdin.bz2'` for\nbzip2, `--label='stdin.lzma'` for lzma, `--label='stdin.lz4` for lz4 and so on.\nThe name `stdin` is arbitrary and may be omitted:\n\nformat    | filename suffix         | tar/pax archive short suffix    | suffix required? | detect on stdin  | library      |\n--------- | ----------------------- | ------------------------------- | ---------------- | ---------------- | ------------ |\ngzip      | `.gz`                   | `.taz`, `.tgz`, `.tpz`          | no               | automatic        | libz         |\ncompress  | `.Z`                    | `.taZ`, `.tZ`                   | no               | automatic        | *built-in*   |\nzip       | `.zip`, `.zipx`, `.ZIP` |                                 | no               | automatic        | libz         |\nbzip2     | `.bz`, `.bz2`, `.bzip2` | `.tb2`, `.tbz`, `.tbz2`, `.tz2` | no               | automatic        | libbz2       |\nxz        | `.xz`                   | `.txz`                          | no               | automatic        | liblzma      |\nzstd      | `.zst`, `.zstd`         | `.tzst`                         | no               | automatic        | libzstd      |\n7zip      | `.7z`                   |                                 | yes              | `--label=.7z`    | *built-in*   |\nbrotli    | `.br`                   |                                 | yes              | `--label=.br`    | libbrotlidec |\nbzip3     | `.bz3`                  |                                 | yes              | `--label=.bz3`   | libbzip3     |\nlzma      | `.lzma`                 | `.tlz`                          | yes              | `--label=.lzma`  | liblzma      |\nlz4       | `.l","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenivia%2Fugrep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgenivia%2Fugrep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenivia%2Fugrep/lists"}