ugrep
v7.1.1
[自述文件|用户指南 |索引 |基准 |问答]
选项 -Q 打开查询 TUI 以在您键入时搜索文件！
ugrep 速度快、用户友好，并且配备了大量用户想要的新功能
包括带有内置帮助的交互式 TUI、带有 AND/OR/NOT 模式的类似 Google 搜索、模糊搜索、搜索（嵌套）zip/7z/tar/pax/cpio 档案、tarball 和压缩文件 gz/Z/bz/ bz2/lzma/xz/lz4/zstd/brotli，搜索和hexdump二进制文件，搜索PDF、doc、docx等文档，并以JSON、XML、CSV格式输出或您自己定制的格式
Unicode 扩展正则表达式模式语法，具有多行模式匹配，无需特殊命令行选项
包括文件索引器，以加快搜索慢速和冷文件系统的速度
GNU grep 的真正直接替代品（假设您将ug复制或符号链接到grep 、 egrep和fgrep ），不像其他流行的 grep 声称是“grep 替代品”或“替代品”，而实际上它们实现了不兼容的命令行选项并使用不兼容的正则表达式匹配器，即当 ugrep 支持所有正则表达式时，Perl 正则表达式仅与 POSIX BRE (grep) 和 ERE (egrep) 相对模式
基准测试表明 ugrep 是使用基于 DFA 的高性能正则表达式匹配器 RE/flex 最快的 grep 之一
如果需要改进或添加到 ugrep 中，请告诉我！
#1 优先事项是质量保证，以继续确保 ugrep 没有错误并且可靠
使 ugrep 运行得更快，例如参见#432、#421
分享可重复的性能结果
ug用于交互式使用，它根据您的首选项加载位于工作目录或主目录中的可选 .ugrep 配置文件， ug+还搜索 pdf、文档、电子书、图像元数据
ugrep用于批量使用，如没有 .ugrep 配置文件的 GNU grep， ugrep+还可以搜索 pdf、文档、电子书、图像元数据
默认匹配 Unicode 模式并自动搜索 UTF-8、UTF-16 和 UTF-32 编码文件
与正则表达式模式中的n或R匹配多行，不需要特殊选项即可执行此操作！
内置帮助： ug --help ，其中ug --help WHAT显示与您要查找的WHAT相关的选项
ug --help regex 、 ug --help globs 、 ug --help fuzzy 、 ug --help format 。
用户友好，可自定义配置文件，由ug命令使用，用于交互式使用，根据您的首选项加载 .ugrep 配置文件
ug PATTERN ... ugrep --config PATTERN ...
ug --save-config ...options-you-want-to-save...将 .ugrep 配置文件保存在工作目录中，以便下次运行ug时它会使用这些选项。在您的主目录中执行此操作，以保存包含您通常想要使用的选项的 .ugrep 配置文件。
交互式查询 TUI，按 F1 或 CTRL-Z 获取帮助，按 TAB/SHIFT-TAB 导航到目录和文件
ug -Q ug -Q -e PATTERN
-Q替换命令行上的PATTERN ，以便您在 TUI 中以交互方式输入模式。在 TUI 中，使用 ALT+字母键打开/关闭短“字母选项”，例如 ALT-n（选项-n ）显示/隐藏行号。
搜索档案（zip、tar、pax、jar、cpio、7z）和压缩文件（gz、Z、bz、bz2、lzma、xz、lz4、zstd、brotli）的内容
ug -z PATTERN ... ug -z --zmax=2 PATTERN ...
指定-z --zmax=2搜索压缩文件和嵌套在存档中的存档。 --zmax参数的范围可以从 1（默认）到 99，最多可进行 99 个解压缩和解存档步骤来搜索嵌套存档
使用与 Google 类似的布尔查询模式进行搜索，使用-%模式与AND （或仅空格）、 OR （或条| ）、 NOT （或破折号- ），使用引号精确匹配，并使用( )分组（显示在下面的左侧）；或使用选项-e （作为“或”）、 --and 、 --andnot和--not正则表达式模式（如下右侧所示）：
ug -% 'A B C' ... ug -e 'A' --and 'B' --and 'C' ...
ug -% 'A|B C' ... ug -e 'A' -e 'B' --and 'C' ...
ug -% 'A -B -C' ... ug -e 'A' --andnot 'B' --andnot 'C' ...
ug -% 'A -(B|C)'... ug -e 'A' --andnot 'B' --andnot 'C' ...
ug -% '"abc" "def"' ... ug -e 'QabcE' --and 'QdefE' ...
其中A 、 B和C是任意正则表达式模式（使用选项-F搜索字符串）
指定选项-%% ( --bool --files ) 将布尔查询应用于整个文件：如果通过文件范围内的匹配模式满足所有布尔条件，则文件匹配。否则，布尔条件默认应用于单行，因为 grep 实用程序通常是基于行的模式匹配器。选项--stats在搜索完成后以人类可读的形式显示查询。
使用与文件扩展名关联的过滤器，通过ug+搜索 pdf、doc、docx、电子书等：
ug+ PATTERN ...
或指定--filter与文件类型以使用过滤器实用程序：
ug --filter='pdf:pdftotext % -' PATTERN ...
ug --filter='doc:antiword %' PATTERN ...
ug --filter='odt,docx,epub,rtf:pandoc --wrap=preserve -t plain % -o -' PATTERN ...
ug --filter='odt,doc,docx,rtf,xls,xlsx,ppt,pptx:soffice --headless --cat %' PATTERN ...
ug --filter='pem:openssl x509 -text,cer,crt,der:openssl x509 -text -inform der' PATTERN ...
ug --filter='latin1:iconv -f LATIN1 -t UTF-8' PATTERN ...
ug+命令与ug命令相同，但也使用过滤器来搜索 PDF、文档和图像元数据
使用选项-o ( --only-matching ) 和上下文选项-ABC显示水平上下文，例如在很长的行中查找匹配项，例如 Javascript 和 JSON 源：
ug -o -C20 -nk PATTERN longlines.js
-o -C20适合所有与上下文匹配的前 20 个字符和后 20 个字符（即总共 40 个 Unicode 字符）， -nk输出行号和列号。
在指定的编辑距离内通过模糊搜索查找近似模式匹配
ug -Z PATTERN ... ug -Z3 PATTTERN ...
-Zn最多匹配n额外、缺失或替换的字符， -Z+n最多匹配n额外字符， -Zn最多匹配n缺失字符， -Z~n最多匹配n替换字符。 -Z默认为-Z1 。
使用正则表达式（或使用-F的固定字符串）进行类似 Fzf 的搜索，使用-Z+4进行最多 4 个额外字符的模糊匹配，仅使用-w进行单词匹配，使用-%%进行文件范围的布尔搜索
ug -Q -%% -l -w -Z+4 --sort=best
-l列出 TUI 中的匹配文件，按TAB然后按ALT-y查看文件， SHIFT-TAB和Alt-l返回查看按最佳匹配排序的匹配文件列表
搜索二进制文件并显示具有二进制模式匹配的十六进制转储（Unicode 文本或-U表示字节模式）
ug --hexdump -U BYTEPATTERN ... ug --hexdump TEXTPATTERN ...
ug -X -U BYTEPATTERN ... ug -X TEXTPATTERN ...
ug -W -U BYTEPATTERN ... ug -W TEXTPATTERN ...
--hexdump=4chC1显示4列十六进制，没有字符列c ，没有十六进制间距h ，并且在匹配之前和之后有一个额外的十六进制行C1 。
包含要按文件类型或文件“魔字节”搜索的文件，或使用^排除它们
ug -t TYPE PATTERN ... ug -t ^TYPE PATTERN ...
ug -M 'MAGIC' PATTERN ... ug -M '^MAGIC' PATTERN ...
包含要搜索的与 gitignore 风格的 glob 匹配的文件和目录，或使用^排除它们
ug -g 'FILEGLOB' PATTERN ... ug -g '^FILEGLOB' PATTERN ...
ug -g 'DIRGLOB/' PATTERN ... ug -g '^DIRGLOB/' PATTERN ...
ug -g 'PATH/FILEGLOB' PATTERN ... ug -g '^PATH/FILEGLOB' PATTERN ...
ug -g 'PATH/DIRGLOB/' PATTERN ... ug -g '^PATH/DIRGLOB/' PATTERN ...
包含要按文件扩展名（后缀）搜索的文件，或使用^ （ -g"*.EXT"的简写）排除它们
ug -O EXT PATTERN ... ug -O ^EXT PATTERN ...
包括要搜索的隐藏文件（点文件）和目录（默认情况下省略）
ug -. PATTERN ... ug -g'.*,.*/' PATTERN ...
在 .ugrep 中指定hidden始终使用ug搜索隐藏文件。
排除 .gitignore 等指定的文件。
ug --ignore-files PATTERN ... ug --ignore-files=.ignore PATTERN ...
在 .ugrep 中指定ignore-files以便始终使用ug忽略它们。根据需要添加额外的ignore-files=...
排除否定模式的搜索模式（“匹配这个但不匹配那个”）
ug -e PATTERN -N NOTPATTERN ... ug -e '[0-9]+' -N 123 ...
使用预定义的正则表达式模式来搜索源代码、javascript、XML、JSON、HTML、PHP、markdown 等。
ug PATTERN -f c++/zap_comments -f c++/zap_strings ...
ug PATTERN -f php/zap_html ...
ug -f js/functions ... | ug PATTERN ...
按名称、最佳匹配、大小和时间对匹配文件进行排序
ug --sort PATTERN ... ug --sort=size PATTERN ...
ug --sort=changed PATTERN ... ug --sort=created PATTERN ...
ug -Z --sort=best PATTERN ... ug --no-sort PATTERN ...
以 CSV、JSON、XML 和用户指定格式输出结果
ug --csv PATTERN ... ug --json PATTERN ...
ug --xml PATTERN ... ug --format='file=%f line=%n match=%O%~' PATTERN ...
ug --help format显示有关自定义输出的格式%字段的帮助。
使用 PCRE 的 Perl 兼容正则表达式模式进行搜索并显示或替换子模式匹配
ug -P PATTERN ... ug -P --format='%1 and %2%~' 'PATTERN(SUB1)(SUB2)' ...
使用 -P 和 --replace 替换文本替换输出中的模式，可选地包含%格式字段，使用-y传递文件的其余部分：
ug --replace='TEXT' PATTERN ... ug -y --replace='TEXT' PATTERN ...
ug --replace='(%m:%o)' PATTERN ... ug -y --replace='(%m:%o)' PATTERN ...
ug -P --replace='%1' PATTERN ... ug -y -P --replace='%1' PATTERN ...
ug --help format显示有关 format %字段的帮助，可以选择与--replace一起使用。
搜索具有特定编码格式的文件，例如 ISO-8859-1 至 16、CP 437、CP 850、MACROMAN、KOI8 等。
ug --encoding=LATIN1 PATTERN ...
使用 Homebrew 安装最新的 ugrep：
$ brew install ugrep
或使用 MacPorts 安装：
$ sudo port install ugrep
这将安装ugrep和ug命令，其中ug与ugrep相同，但还会加载工作目录或主目录中存在的配置文件 .ugrep。
使用 Winget 安装winget install Genivia.ugrep
或者使用 Chocolatey choco install ugrep安装
或者使用 Scoop scoop install ugrep安装
或者从 https://github.com/Genivia/ugrep/releases 下载全功能的ugrep.exe可执行文件作为发布工件。压缩版本包含主要的ugrep.exe二进制文件以及ug.exe 。 ug命令用于交互式使用，从.ugrep配置文件（当存在于工作目录或主目录中时）加载和读取设置。
将ugrep.exe和ug.exe添加到您的执行路径：转到“设置”并在“查找设置”中搜索“路径”。选择环境变量->路径->新建，然后添加放置ugrep.exe和ug.exe可执行文件的目录。
提示
在 Windows 命令行上使用ugrep.exe和ug.exe的实用提示：
'引号，而是使用" ；大多数 Windows 命令实用程序将单'引号视为命令行参数的一部分！-g/GLOB指定，而不是使用通常的GLOB命令行参数来选择要搜索的文件和目录，特别是对于递归搜索；""来匹配所有输入时，某些Windows命令解释器（例如Powershell）可能会忽略它，在这种情况下，您必须指定选项--match ；R而不是n来匹配任何 Unicode 换行符，例如rn对以及单个r和n 。 $ apk add ugrep ugrep-doc
检查 https://pkgs.alpinelinux.org/packages?name=ugrep 了解版本信息。
$ pacman -S ugrep
检查 https://archlinux.org/packages/extra/x86_64/ugrep 了解版本信息。
首先启用 EPEL 存储库，然后就可以安装 ugrep。
$ dnf install ugrep
检查 https://packages.fedoraproject.org/pkgs/ugrep/ugrep/ 以获取版本信息。
$ apt-get install ugrep
检查 https://packages.debian.org/ugrep 了解版本信息。要在本地构建并尝试ugrep ，请参阅下面的“所有平台”构建步骤。
$ dnf install ugrep
检查 https://packages.fedoraproject.org/pkgs/ugrep/ugrep/ 以获取版本信息。
$ pkg install ugrep
检查 https://www.freshports.org/textproc/ugrep 了解版本信息。
$ pkgman install cmd:ugrep
检查 https://github.com/haikuports/haikuports/tree/master/app-text/ugrep 了解版本信息。要在本地构建并尝试ugrep ，请参阅下面的“所有平台”构建步骤。
您可以使用标准 NetBSD 软件包安装程序 (pkgsrc)：http://cdn.netbsd.org/pub/pkgsrc/current/pkgsrc/textproc/ugrep/README.html
$ pkg_add ugrep
检查 https://openports.pl/path/sysutils/ugrep 以获取版本信息。
$ zypper install ugrep
检查 https://build.opensuse.org/package/show/utilities/ugrep 了解版本信息。
首先启用 EPEL 存储库，然后就可以安装 ugrep。
$ dnf install ugrep
检查 https://packages.fedoraproject.org/pkgs/ugrep/ugrep/ 以获取版本信息。
克隆ugrep
$ git clone https://github.com/Genivia/ugrep
或者访问 https://github.com/Genivia/ugrep/releases 下载特定版本。
当您需要这些功能时，您可以随时添加这些功能：
选项-P （Perl 正则表达式）需要 PCRE2 库（推荐）或 Boost.Regex 库（可选后备）。如果未安装 PCRE2，请使用sudo apt-get install -y libpcre2-dev安装 PCRE2 或下载 PCRE2 并按照安装说明进行操作。或者，下载 Boost.Regex 并运行./bootstrap.sh和sudo ./b2 --with-regex install 。请参阅Boost：入门。
选项-z （压缩文件和档案搜索）需要安装 zlib 库。它安装在大多数系统上。如果没有，请安装它，例如使用sudo apt-get install -y libz-dev 。要搜索.bz和.bz2文件，请安装 bzip2 库（推荐），例如使用sudo apt-get install -y libbz2-dev 。要搜索.lzma和.xz文件，请安装 lzma 库（推荐），例如使用sudo apt-get install -y liblzma-dev 。要搜索.lz4文件，请安装 lz4 库（可选，不是必需），例如使用sudo apt-get install -y liblz4-dev 。要搜索.zst文件，请安装 zstd 库（可选，不是必需的），例如使用sudo apt-get install -y libzstd-dev 。要搜索.br文件，请安装 brotli 库（可选，不是必需的），例如使用sudo apt-get install -y libbrotli-dev 。要搜索.bz3文件，请安装 bzip3 库（可选，不是必需），例如使用sudo apt-get install -y bzip3 。
提示
即使您的系统具有命令行实用程序（例如bzip2 ，也并不一定意味着安装了libbz2等开发库。应安装开发库。
某些 Linux 系统可能未配置为从/usr/local/lib加载动态库，从而导致运行ugrep时出现库加载错误。要更正此问题，请将export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/usr/local/lib"添加到~/.bashrc文件中。或者运行sudo ldconfig /usr/local/lib 。
执行./build.sh脚本来构建ugrep ：
$ cd ugrep
$ ./build.sh
这会使用./configure和make -j在ugrep/src目录中构建ugrep可执行文件，并使用make test进行验证。当所有测试通过后， ugrep可执行文件将复制到ugrep/bin/ugrep ，并为ug命令添加符号链接ugrep/bin/ug -> ugrep/bin/ugrep 。
请注意， ug与ugrep相同，但也会加载工作目录或主目录中存在的配置文件 .ugrep。这意味着您可以在 .ugrep 中定义ug的默认选项。
可以使用./build.sh指定已安装或本地库的替代路径。要获取有关可用构建选项的帮助：
$ ./build.sh --help
您可以通过指定来构建静态可执行文件：
$ ./build.sh --enable-static
如果库不静态链接（例如 brotli），这可能会失败。在这种情况下，请尝试./build.sh --enable-static --without-brotli 。
您可以构建启用自定义默认值的ugrep ，例如寻呼机：
$ ./build.sh --enable-pager
选择构建默认值的选项包括：
--help显示构建选项--enable-static构建静态可执行文件（如果可能）--enable-hidden始终搜索隐藏文件和目录--enable-pager始终使用寻呼机在终端上显示输出--enable-pretty对终端的输出进行着色并添加文件名标题--disable-auto-color禁用自动颜色，需要 ugrep 选项--color=auto显示颜色--disable-mmap禁用内存映射文件--disable-sse2禁用 SSE2 和 AVX 优化--disable-avx2禁用 AVX2 和 AVX512BW 优化，但在支持时使用 SSE2 进行编译--disable-neon禁用 ARM NEON/AArch64 优化--with-grep-path如果未定义GREP_PATH则为默认-f路径--with-grep-colors如果未定义GREP_COLORS则为默认颜色构建完成后，将ugrep/bin/ugrep和ugrep/bin/ug复制到一个方便的位置，例如~/bin目录中。或者，如果您可能想安装ugrep和ug命令和手册页：
$ sudo make install
这还会在/usr/local/share/ugrep/patterns/处安装带有选项-f的预定义模式的模式文件。选项-f首先检查工作目录是否存在模式文件，如果没有找到，则检查环境变量GREP_PATH以加载模式文件，如果没有找到，则读取已安装的预定义模式文件。
不幸的是，git 克隆不保留时间戳，这意味着您可能会遇到“警告：系统上缺少‘aclocal-1.15’”。或者运行make时未找到自动标头。
要解决此问题，请运行：
$ autoreconf -fi
$ ./build.sh
GCC 8 及更高版本可能会产生类似“注意：参数传递的参数...在 GCC 7.1 中已更改”的警告。应忽略这些警告。
包含一个 Dockerfile，用于在 Ubuntu 容器中构建ugrep 。
开发人员可能希望在进行重大更改时使用 sanitizer 来验证ugrep代码，例如使用 ThreadSanitizer 检测数据争用：
$ ./build.sh CXXFLAGS='-fsanitize=thread -O1 -g'
我们使用 clang AddressSanitizer、MemorySanitizer、ThreadSanitizer 和 UndefinedBehaviorSanitizer 检查了ugrep 。这些选项会产生大量的运行时开销，不应用于最终构建。
？返回目录
请注意， ugrep和ug命令默认搜索二进制文件，并且不会忽略 .gitignore 指定的文件，这不会使递归搜索性能比较有意义，除非使用选项-I和--ignore-files 。要使这些选项成为ug的默认选项，只需将ignore-binary和ignore-files添加到您的 .ugrep 配置文件中。
有关最新 ugrep 的最新性能比较，请参阅 ugrep 性能基准。 Ugrep 比 GNU grep、Silver Searcher、ack、sift 更快。 Ugrep 的速度在大多数基准测试中都优于 ripgrep。
首先，我们在 Vim 中定义:grep命令来递归搜索文件。为此，请将以下行添加到位于根目录中的.vimrc中：
if executable('ugrep')
set grepprg=ugrep -RInk -j -u --tabs=1 --ignore-files
set grepformat=%f:%l:%c:%m,%f+%l+%c+%m,%-G%f\|%l\|%c\|%m
endif
这使用 Vim :grep命令指定-j不区分大小写的搜索。对于区分大小写的搜索，请从grepprg中删除 -j 。同一行上的多个匹配项会分别在快速修复窗口中列出。如果不需要，请从grepprg中删除 -u 。通过此更改，仅显示一行中的第一个匹配项。选项--ignore-files会跳过.gitignore文件中指定的文件（如果存在）。要将递归搜索的深度限制为仅当前目录，请将 -1附加到grepprg 。
现在，您可以在 Vim 中调用 Vim :grep命令来搜索指定PATH上的文件以查找PATTERN匹配项：
:grep PATTERN [PATH]
如果省略PATH ，则会搜索工作目录。使用%作为PATH仅搜索 Vim 中当前打开的文件：
:grep PATTERN %
:grep命令在快速修复窗口中显示结果，使您可以快速跳转到找到的匹配项。
要打开包含最新匹配列表的快速修复窗口：
:copen
双击该窗口中的一行（或选择一行并按 ENTER）可跳转到匹配的文件和文件中的位置。输入命令:cn和:cp分别跳转到下一个或上一个匹配项。要更新快速修复窗口中的搜索结果，只需 grep 即可。例如，要在工作目录中递归搜索标记为FIXME C++ 源代码：
:grep -tc++ FIXME
要关闭快速修复窗口：
:cclose
您可以将ugrep选项与:grep命令一起使用，例如选择当前文件中的单行和多行注释：
:grep -f c++/comments %
Quickfix 中仅显示多行注释的第一行，以节省空间。要显示多行匹配的所有行，请从grepformat中删除%-G 。
一个流行的 Vim 工具是 ctrlp.vim，它是通过以下命令安装的：
$ cd ~/.vim
$ git clone https://github.com/kien/ctrlp.vim.git bundle/ctrlp.vim
CtrlP 通过将以下行添加到.vimrc来使用ugrep ：
if executable('ugrep')
set runtimepath^=~/.vim/bundle/ctrlp.vim
let g:ctrlp_match_window='bottom,order:ttb'
let g:ctrlp_user_command='ugrep "" %s -Rl -I --ignore-files -3'
endif
其中-I跳过二进制文件，选项--ignore-files跳过.gitignore文件中指定的文件（如果存在），选项-3将搜索目录限制为三个级别（工作目录以及下面最多两个级别）。
启动 Vim 然后输入命令：
:helptags ~/.vim/bundle/ctrlp.vim/doc
要在 Vim 中查看 CtrlP 文档，请输入命令：
:help ctrlp.txt
？返回目录
感谢 Manuel Uberti，您现在可以在 Emacs 中使用ugrep 。要在 Emacs 中使用ugrep而不是 GNU grep，请将以下行添加到.emacs.d/init.el文件中：
(setq-default xref-search-program ‘ugrep)
这意味着依赖 Xref 的 Emacs 命令（例如project-find-regexp现在可以利用ugrep的强大功能。
此外，可以在 Emacs grep 命令中使用grep 。例如，您可以通过将grep-template自定义为如下所示，使用ugrep运行lgrep ：
(setq-default grep-template "ugrep --color=always -0Iinr -e <R>")
如果您没有 Emacs 版本 29（或更高版本），您可以从 Emacs master 分支下载并构建 Emacs，或者手动启用 Xref 与ugrep集成：
(with-eval-after-load 'xref
(push '(ugrep . "xargs -0 ugrep <C> --null -ns -e <R>")
xref-search-program-alist)
(setq-default xref-search-program 'ugrep))
？返回目录
开箱即用的ugrep支持所有标准 GNU/BSD grep 命令行选项，并改进了其中的许多选项。有关详细信息，请参阅相对于 grep 的显着改进。
如果您想完全遵循 GNU/BSD grep ASCII/LATIN1 非 UTF Unicode 模式，请使用选项-U禁用完整的 Unicode 模式匹配。
事实上，使用选项-U 、 -Y 、 -.执行ugrep 。和--sort使其行为与egrep完全相同，仅匹配 ASCII/LATIN1 非 UTF Unicode 模式，允许空模式匹配和搜索隐藏文件而不是忽略它们。请参阅 grep 等效项。
您可以使用或不使用选项-U 、 -Y 、 -.和 -- 根据需要--sort或包含其他选项。
或者，您可以通过将ugrep复制到这些名称来创建grep 、 egrep和fgrep可执行文件。当ugrep （或ugrep.exe ）可执行文件被复制为grep ( grep.exe )、 egrep ( egrep.exe )、 fgrep ( fgrep.exe ) 时，然后是选项-U 、 -Y和-.与grep的-G 、 egrep的-E和fgrep的-F一起自动启用。此外，当复制为zgrep 、 zegrep和zfgrep时，会启用选项-z 。例如，当ugrep复制为zegrep时，选项-z 、 -E 、 -Y 、 -.和--sort已启用。
同样，到ugrep的符号链接和硬链接也可以很好地创建grep 、 egrep和fgrep替代品。例如，要创建符号链接egrep ：
sudo ln -s `which ugrep` /opt/local/bin/egrep
/opt/local/bin只是一个示例，可能会或可能不会在您的$path中，并且在执行egrep时可能会或可能不会找到，具体取决于您的$path 。
当使用以下选项时， ugrep相当于 GNU/BSD grep：
grep = ugrep -G -U -Y -. --sort -Dread -dread
egrep = ugrep -E -U -Y -. --sort -Dread -dread
fgrep = ugrep -F -U -Y -. --sort -Dread -dread
zgrep = ugrep -z -G -U -Y -. --sort -Dread -dread
zegrep = ugrep -z -E -U -Y -. --sort -Dread -dread
zfgrep = ugrep -z -F -U -Y -. --sort -Dread -dread
在哪里：
-U禁用 Unicode 宽字符模式匹配，因此例如模式xa3匹配字节 A3，而不是 UTF-8 序列 C2 A3 表示的 Unicode 代码点 U+00A3。默认情况下，在 ugrep 中， xa3匹配 U+00A3。我们不建议使用-U进行文本模式搜索，仅用于二进制搜索或搜索 latin-1 (iso-8859-1) 文件而不将这些文件报告为二进制文件（自 ugrep v3.5.0 起）。-Y启用空匹配，因此例如模式a*匹配每一行而不是a序列。默认情况下，在 ugrep 中，模式a*与a的序列匹配。此外，在 ugrep 中，模式a*b*c*与默认情况下应该匹配的内容相匹配。查看改进。-.搜索隐藏文件（点文件）。默认情况下，隐藏文件会被忽略，就像大多数 Unix 实用程序一样。--sort指定按路径名排序的输出，首先显示排序的匹配文件，然后显示子目录中排序的递归匹配项。否则，将不按特定顺序报告匹配文件以提高性能；-Dread和-dread是 GNU/BSD grep 默认值，但不推荐，请参阅改进以获取解释。？返回目录
添加到.bashrc以提高工作效率的常用别名：
alias uq = 'ug -Q' # interactive TUI search (uses .ugrep config)
alias uz = 'ug -z' # compressed files and archives search (uses .ugrep config)
alias ux = 'ug -U --hexdump' # binary pattern search (uses .ugrep config)
alias ugit = 'ug -R --ignore-files' # works like git-grep & define your preferences in .ugrep config
alias grep = 'ug -G' # search with basic regular expressions (BRE) like grep
alias egrep = 'ug -E' # search with extended regular expressions (ERE) like egrep
alias fgrep = 'ug -F' # find string(s) like fgrep
alias zgrep = 'ug -zG' # search compressed files and archives with BRE
alias zegrep = 'ug -zE' # search compressed files and archives with ERE
alias zfgrep = 'ug -zF' # find string(s) in compressed files and/or archives
alias xdump = 'ugrep -X ""' # hexdump files without searching (don't use .ugrep config)
alias zmore = 'ugrep+ -z -I -+ --pager ""' # view compressed, archived and regular files (don't use .ugrep config)
？返回目录
-Q启动交互式查询 TUI。n时， ugrep会跨多行匹配模式。-U禁用）。--bool ）。--ignore-files支持 gitignore 。-Z进行模糊（近似）匹配。-z搜索压缩文件和档案。-z搜索 cpio、jar、pax、tar、zip 和 7z 档案。-z和--zmax=NUM方式递归存储在档案中，深度可达NUM层。--filter搜索 pdf、doc、docx、xls、xlsx、epub 等。-r递归搜索目录。-.启用）。-E作为egrep，而-G启用 BRE）。-J1禁用）。-W （以十六进制输出二进制匹配，并像往常一样输出文本匹配）和-X （以十六进制输出所有匹配）生成十六进制转储。--format ）。-f使用GREP_PATH环境变量或/usr/local/share/ugrep/patterns中安装的预定义模式。如果指定了-f并指定了一个或多个-e模式，则选项-F 、 -x和-w不适用于-f模式。这是为了避免当-f与可能无法再与这些选项一起正常工作的预定义模式一起使用时产生混淆。-O 、 -M和-t分别指定文件扩展名、文件签名魔术字节模式和预定义文件类型。这允许在目录树中搜索某些类型的文件，例如使用递归搜索选项-R和-r 。选项-O 、 -M和-t也适用于 cpio、jar、pax、tar、zip 和 7z 文件中的存档文件。-k , --column-number显示列号，通过扩展制表符考虑制表符间距，如选项--tabs指定。-P （Perl 正则表达式）支持反向引用（使用--format ）和lookbehinds，它使用 PCRE2 或 Boost.Regex 库通过类似 PCRE 的语法进行快速 Perl 正则表达式匹配。-b与选项-o或选项-u一起使用，ugrep 显示模式匹配的确切字节偏移量，而不是 GNU/BSD grep 报告的匹配行开头的字节偏移量。-u , --ungroup不将每行的多个匹配项分组。此选项会针对行上的每个附加模式匹配再次显示匹配的输入行。此选项与选项-c一起特别有用，可以报告每个文件的模式匹配总数，而不是每个文件匹配的行数。-Y允许匹配空模式。使用空匹配模式进行 grep 很奇怪，并且使用 GNU grep 与 BSD grep 会给出不同的结果。默认情况下， ugrep不输出空匹配，这避免了可能产生“随机”结果的错误。例如，使用 GNU/BSD grep，模式a*匹配输入中的每一行，并且实际上匹配xyz三次（ x 、 y和z之前和之间的空转换）。允许空匹配需要ugrep选项-Y 。以^开头或以$结尾的模式（例如^h*$匹配空。这些模式自动启用选项-Y 。-D, --devices=ACTION默认情况下是skip ，而不是read 。这可以防止意外挂在递归搜索的目录中的命名管道上，就像默认情况下read设备的 GNU/BSD grep 可能发生的情况一样。-d, --directories=ACTION默认情况下是skip ，而不是read 。默认情况下，会搜索命令行上指定的目录，但不会递归地深入子目录。-N PATTERN ，它们是(?^X)形式的模式，跳过所有X输入，从而从搜索中删除X例如，在源代码中搜索标识符时，可以使用否定模式跳过字符串和注释，并查找不在字符串和注释中的匹配项。预定义的zap模式使用负模式，例如，使用-f cpp/zap_comments忽略 C++ 注释中的模式匹配。GREP_OPTIONS环境变量，因为ugrep的行为必须在每个系统上都是可移植和可预测的。由于这个原因，GNU grep 也放弃了GREP_OPTIONS 。请使用ug命令加载位于工作目录或主目录（如果存在）中的 .ugrep 配置文件，或使用 shell 别名创建具有特定搜索选项的新命令。？返回目录
要使用放置在工作目录或主目录中的配置文件.ugrep执行搜索（请注意ug与ugrep --config相同）：
ug PATTERN FILE...
要将.ugrep配置文件保存到工作目录，然后在主目录中编辑此文件以自定义ug默认值的首选项：
ug --save-config
要搜索工作目录并递归地更深地查找main （请注意，如果未指定文件参数，则默认启用-r递归符号链接）：
ug main
相同，但仅递归搜索 C++ 源代码文件，忽略所有其他文件：
ug -tc++ main
同样，使用交互式查询 TUI，从初始搜索模式main开始（请注意，带有初始模式的-Q需要选项-e因为模式通常是交互式指定的，并且所有命令行参数都被视为文件/目录）：
ug -Q -tc++ -e main
要在 C++ 文件中使用正则表达式模式搜索#define （和# define等）（请注意，应引用模式以防止 shell 通配*和? ）：
ug -tc++ '#[t ]*define'
要在目录myproject中递归搜索main作为单词 ( -w )，而不遵循符号链接 ( -r )，在匹配的行旁边显示匹配的行号 ( -n ) 和列号 ( -k )：
ug -r -nkw main myproject
相同，但仅搜索myproject而不进行更深层次的递归（请注意，默认情况下在一级搜索目录参数）：
ug -nkw main myproject
相同，但使用-2搜索myproject和更深一级的子目录（两级）：
ug -2 -nkw main myproject
相同，但仅使用-tc++搜索myproject及其子目录中的 C++ 文件：
ug -tc++ -2 -nkw main myproject
相同，但还可以使用-z搜索存档（例如 zip 和 tar 文件）和压缩文件：
ug -z -tc++ -2 -nkw main myproject
在工作目录中递归搜索main ，同时忽略 gitignored 文件（例如，假设.gitignore位于工作目录或以下目录中）：
ug --ignore-files -tc++ -nkw main
列出工作目录及更深层次中未被.gitignore文件忽略的所有文件：
ug --ignore-files -l ''
显示与-t参数对应的搜索到的文件扩展名和“魔法字节”(shebangs) 的列表：
ug -tlist
要根据扩展名和带-l的 shebang 递归列出所有 shell 文件（请注意''匹配任何非空文件）：
ug -l -tShell ''
？返回目录
要在源代码中搜索main同时忽略字符串和注释块，您可以使用带有选项-N否定模式来跳过 C/C++ 引用的字符串和注释块中不需要的匹配：
ug -r -nkw -e 'main' -N '"(\.|\r?n|[^\n"])*"|//.*|/*(.*n)*?.**+/' myproject
正确输入需要大量工作！如果您像我一样，当我正在处理更重要的事情时，我不想花时间摆弄正则表达式模式。有一种更简单的方法，可以使用随ugrep工具安装的ugrep预定义模式 ( -f )：
ug -r -nkw 'main' -f c/zap_strings -f c/zap_comments myproject
此查询还会搜索 C/C++ 源代码之外的其他文件，例如 README、Makefile 等。我们还使用-r跳过符号链接。因此，让我们通过仅使用选项-tc,c++选择C/C ++文件来完善此查询，并使用-R ：符合文件和目录的符号链接：
ug -R -tc,c++ -nkw 'main' -f c/zap_strings -f c/zap_comments myproject
如果您只想查找标识符main而不是作为函数main( ？在这种情况下，使用负面模式来跳过不需要的mainh*(模式匹配：
ug -R -tc,c++ -nkw -e 'main' -N 'mainh*(' -f c/zap_strings -f c/zap_comments myproject
这使用-e和-N选项分别明确指定模式和h负模式，该模式本质上是形成模式main|(?^mainh*() ，负模式对于过滤我们不感兴趣的模式匹配非常有用。
作为另一个例子，假设我们可能需要在C/C ++注释块中搜索FIXME 。为此，我们可以首先使用UGREP的预定义c/comments模式选择评论块，然后使用管道使用FIXME选择行：
ug -R -tc,c++ -nk -f c/comments myproject | ug -w 'FIXME'
通常，使用管道过滤结果比使用某些搜索工具使用的和逻辑更容易。这种方法遵循Unix Spirit，使公用事业简单，并将其结合起来进行更复杂的任务。
让我们制作出在跳过字符串和评论时在Java源代码中找到的所有标识符的分类列表：
ug -R -tjava -f java/names myproject | sort -u
这匹配Java Unicode标识符使用REGEX p{JavaIdentifierStart}p{JavaIdentifierPart}*在patterns/java/names中定义。
借助传统的GREP和类似GREP的工具，它需要付出巨大的努力才能递归搜索定义函数qsort的C/C ++源文件，需要类似的内容：
ug -R --include='*.c' --include='*.cpp' '^([ t]*[[:word:]:*&]+)+[ t]+qsort[ t]*([^;n]+$' myproject
幸运的是，使用ugrep，我们可以通过使用选项-Oc,cpp和使用使用该工具安装的预定义模式functions来选择具有扩展.c或.cpp的文件中的所有功能定义，以生成所有功能定义。然后我们选择我们想要的一个：
ug -R -Oc,cpp -nk -f c/functions | ug 'qsort'
请注意，我们可以使用-tc,c++选择C/C ++文件，但是当我们只想搜索.c和.cpp文件时，这也包括标头文件。
我们还可以从.gitignore中定义的搜索中跳过文件和目录。为此，我们使用--ignore-files在找到一个或多个.gitignore文件时，将与.gitignore匹配的递归搜索中排除任何文件和目录：
ug -R -tc++ --ignore-files -f c++/defines
这将在工作目录中搜索#define行（ -f c++/defines ）的C ++文件（ -tc++ ），而在.gitignore中跳过文件和目录时。如果您发现此键太长而无法键入，则定义一个别名以搜索GitHub目录：
alias ugit='ugrep -R --ignore-files'
ugit -tc++ -f c++/defines
要突出显示匹配时，当我们使用的一系列管道推动时，我们应该使用--color=always ：
ugit --color=always -tc++ -f c++/defines | ugrep -w 'FOO.*'
这返回了所有#define FOO... c/c ++源代码文件中的宏，跳过.gitignore中定义的文件。
请注意， --exclude的补充不是--include ，因为排除始终优先于包含物，因此我们无法可靠地列出被--include-from='.gitignore'文件。仅访问使用--include和Directories明确指定的文件，并访问了--include-dir 。列表中--include-from列表，这些列表分别被视为要添加到--include和--include-dir的文件和目录。这意味着，当该文件中未明确列出目录名称和目录路径时，则不会使用--include-from访问它。
由于UGREP检查输入是否有效UTF编码的Unicode（除非使用-U ），因此可以将其用作滤波器来忽略程序产生的非UTF输出：
program | ugrep -I ''
如果程序产生有效的输出，则输出将通过，否则输出被过滤输出选项-I 。如果输出最初对非常大的部分有效，但随后是无效的输出，则UGREP最初可能会显示输出到达，但不包括无效的输出，此后进一步的输出被阻止。
要过滤有效的ASCII或UTF编码的线，同时删除没有：
program | ugrep '[p{Unicode}--[n]]+'
请注意， p{Unicode}匹配n但我们不想匹配整个文件！只需与[p{Unicode}--[n]]+行。
？返回目录
Ugrep Man页面：
man ugrep
显示一个帮助页：
ug --help
显示出提及WHAT的选项：
ug --help WHAT
要显示-t TYPES的列表选项值：
ug -tlist
在交互式查询TUI中，按F1或CTRL-Z以获取帮助和选项：
ug -Q
？返回目录
--config[=FILE], ---[FILE]
Use configuration FILE. The default FILE is `.ugrep'. The working
directory is checked first for FILE, then the home directory. The
options specified in the configuration FILE are parsed first,
followed by the remaining options specified on the command line.
The ug command automatically loads a `.ugrep' configuration file,
unless --config=FILE or --no-config is specified.
--no-config
Do not load the default .ugrep configuration file.
--save-config[=FILE] [OPTIONS]
Save configuration FILE to include OPTIONS. Update FILE when
first loaded with --config=FILE. The default FILE is `.ugrep',
which is automatically loaded by the ug command. When FILE is a
`-', writes the configuration to standard output. Only part of the
OPTIONS are saved that do not cause searches to fail when combined
with other options. Additional options may be specified by editing
the saved configuration file. A configuration file may be modified
manually to specify one or more config[=FILE] to indirectly load
the specified FILEs, but recursive config loading is not allowed.
ug命令旨在用于上下文依赖性交互式搜索，并且等同于ugrep --config命令，以加载配置文件.ugrep
ug PATTERN ...
ugrep --config PATTERN ...
ug命令还按名称按名称搜索的文件对文件进行分类。配置文件包含NAME=VALUE对，其中NAME是长选项的名称（无-- ）和=VALUE是一个参数，该参数是可选的，可以根据选项省略。以#开头的空线条和线条被忽略：
# Color scheme
colors=cx=hb:ms=hiy:mc=hic:fn=hi+y+K:ln=hg:cn=hg:bn=hg:se=
# Disable searching hidden files and directories
no-hidden
# ignore files specified in .ignore and .gitignore in recursive searches
ignore-files=.ignore
ignore-files=.gitignore
命令行选项按以下顺序解析：首先，加载了（默认或命名）配置文件，然后解析命令行上的剩余选项和参数。
选项--stats显示搜索后使用的配置文件。
命名的配置文件旨在通过将命令行选项的数量减少到一个---FILE来使用FILE中指定的选项集合来简化自定义搜索任务。 --config=FILE选项及其缩写表格---FILE加载位于工作目录中的指定配置文件，或者找不到时，位于主目录中：
ug ---FILE PATTERN ...
ugrep ---FILE PATTERN ...
当找不到FILE或无法读取文件时会产生错误。
命名的配置文件可用于定义项目开发工作流程中任务要求的选项集合。例如，通过检查源代码和文档以使用FixMe和ToDo项目来报告未解决的问题。该命名的配置文件可以通过将其放置在项目目录中来定位于项目，也可以通过将其放置在主目录中进行全局。对于视觉反馈，可以在配置FILE中使用选项colors指定特定于本任务的配色方案，以帮助识别由命名配置而不是默认配置所产生的输出。
--save-config选项使用带有--config的当前配置将.ugrep配置文件保存到工作目录中。当当前的配置与其他选项时，也可以保存当前的配置。只有那些无法与其他无法对搜索结果负面影响的选项冲突的选项将被保存。
--save-config=FILE选项将配置保存到指定FILE 。当FILE为-时，配置将写入标准输出。
另外，可以手动创建或修改配置文件。配置文件可以包括一个或多个config[=FILE]以间接加载规格的FILE ，但是禁止递归配置加载。制造创建配置文件的最简单方法是指定文件顶部的config ，然后是覆盖默认值的长选项。
？返回目录
-Q[=DELAY], --query[=DELAY]
Query mode: start a TUI to perform interactive searches. This mode
requires an ANSI capable terminal. An optional DELAY argument may
be specified to reduce or increase the response time to execute
searches after the last key press, in increments of 100ms, where
the default is 3 (300ms delay). No whitespace may be given between
-Q and its argument DELAY. Initial patterns may be specified with
-e PATTERN, i.e. a PATTERN argument requires option -e. Press F1
or CTRL-Z to view the help screen. Press F2 or CTRL-Y to invoke a
command to view or edit the file shown at the top of the screen.
The command can be specified with option --view, or defaults to
environment variable PAGER when defined, or EDITOR. Press Tab and
Shift-Tab to navigate directories and to select a file to search.
Press Enter to select lines to output. Press ALT-l for option -l
to list files, ALT-n for -n, etc. Non-option commands include
ALT-] to increase context. See also options --no-confirm, --delay,
--split and --view.
--no-confirm
Do not confirm actions in -Q query TUI. The default is confirm.
--delay=DELAY
Set the default -Q key response delay. Default is 3 for 300ms.
--split
Split the -Q query TUI screen on startup.
--view[=COMMAND]
Use COMMAND to view/edit a file in -Q query TUI by pressing CTRL-Y.
此选项启动了一个用户界面以交互式输入搜索模式：
-c计算匹配。按下Alt -C再次禁用-c 。在搜索时或查看帮助屏幕时，可以使用ALT键切换选项。如果不支持ALT/META键（例如X11 XTERM），则按CTRL-O，然后按与该选项相对应的键。-g文件和目录匹配的Globs，这是Gitignore风格的GLOB模式的逗号分隔列表。按下ESC返回控制到查询模式提示（保存了地球）。当地球之前是一个!或a ^ ，跳过该文件匹配a / a / pathnames时的名称匹配地球的文件。否则，Basename是匹配的。当一个地球以A /结束时，目录会匹配。Q> （正常）， F> （固定字符串）， G> （基本正则是）， P> （PERL匹配）和Z> （模糊匹配）之间切换。显示--glob=提示时，可以输入gitignore式球形图案的逗号分隔列表。按下ESC将控制权返回到模式提示。--view指定的Pager的文件。--view=COMMAND指定文件查看器或编辑器。否则，使用PAGER或EDITOR环境变量将使用CTRL-Y调用命令。必须在输出中启用和可见文件名才能使用此功能。--color选项。DELAY值，例如1。但是，由于每次按下的键反复启动和取消搜索，较低的值可能会增加系统负载。--heading 。按Alt-+关闭标题。查询TUI键映射：
| 键 | 功能 |
|---|---|
Alt-key | 切换与key相对应的ugrep命令行选项 |
Alt-/ xxxx / | 插入UNICODE六角形代码u+xxxx |
Esc Ctrl-C | 回去或退出 |
Ctrl-Q | 快速退出并输出选择模式下选择的结果 |
Tab | CHDIR到屏幕顶部显示的文件目录或选择文件的目录 |
Shift-Tab | CHDIR一个级别或取消选择文件 |
Enter | 输入选择模式并切换选定的行以输出出口 |
Up Ctrl-P | 向上移动 |
Down Ctrl-N | 向下移动 |
Left Ctrl-B | 向左移动 |
Right Ctrl-F | 向右移动 |
PgUp Ctrl-G | 通过页面移动显示 |
PgDn Ctrl-D | 通过页面向下移动显示 |
Alt-Up | 通过1/2页移动显示（MacOS Shift-Up ） |
Alt-Down | 通过1/2页向下移动显示（MacOS Shift-Down ） |
Alt-Left | 移动显示为1/2页（MacOS Shift-Left ） |
Alt-Right | 向右移动显示乘1/2页（MacOS Shift-Right ） |
Home Ctrl-A | 将光标移至线路的开头 |
End Ctrl-E | 将光标移至线路的末端 |
Ctrl-K | 在光标之后删除 |
Ctrl-L | 刷新屏幕 |
Ctrl-O + key | 切换与key相对应的ugrep命令行选项，与Alt-key相同 |
Ctrl-R F4 | 跳到书签 |
Ctrl-S | 跳到下一个dir/file/context |
Ctrl-T F5 | 切换拆分屏幕（ --split启动拆分屏幕TUI） |
Ctrl-U | 在光标之前删除 |
Ctrl-V | 逐字感 |
Ctrl-W | 跳回一个dir/file/context |
Ctrl-X F3 | 设置书签 |
Ctrl-Y F2 | 查看或编辑屏幕顶部显示的文件 |
Ctrl-Z F1 | 查看帮助和选项 |
Ctrl-^ | Chdir回到启动工作目录 |
Ctrl-] | 切换颜色/单声道 |
Ctrl- | 终止过程 |
在工作目录和以下互动搜索文件：
ug -Q
相同，但仅限于C ++文件，而忽略.gitignore文件：
ug -Q -tc++ --ignore-files
在工作目录和以下互动搜索所有makefiles：
ug -Q -g 'Makefile*' -g 'makefile*'
相同，但最多2个目录级别（工作和一个子目录级别）：
ug -Q -2 -g 'Makefile*' -g 'makefile*'
为了交互式查看main.cpp的内容并搜索它，其中-y将任何不匹配的行显示为上下文：
ug -Q -y main.cpp
要进行交互式搜索main.cpp ，从搜索模式TODO开始，并具有5行的匹配上下文（可以交互启用和禁用上下文，这也覆盖了2行的默认上下文大小）：
ug -Q -C5 -e TODO main.cpp
查看和搜索存档的内容（例如zip，tarball）：
ug -Q -z archive.tar.gz
要使用ugrep查询选择unzip进行交互式从project.zip中选择文件。
unzip project.zip `zipinfo -1 project.zip | ugrep -Q`
？返回目录
-L, --files-without-match
Only the names of files not containing selected lines are written
to standard output. Pathnames are listed once per file searched.
If the standard input is searched, the string ``(standard input)''
is written.
-l, --files-with-matches
Only the names of files containing selected lines are written to
standard output. ugrep will only search a file until a match has
been found, making searches potentially less expensive. Pathnames
are listed once per file searched. If the standard input is
searched, the string ``(standard input)'' is written.
-R, --dereference-recursive
Recursively read all files under each directory. Follow all
symbolic links to files and directories, unlike -r.
-r, --recursive
Recursively read all files under each directory, following symbolic
links only if they are on the command line. Note that when no FILE
arguments are specified and input is read from a terminal,
recursive searches are performed as if -r is specified.
-S, --dereference-files
When -r is specified, symbolic links to files are followed, but not
to directories. The default is not to follow symbolic links.
--depth=[MIN,][MAX], -1, -2, -3, ... -9, -10, -11, -12, ...
Restrict recursive searches from MIN to MAX directory levels deep,
where -1 (--depth=1) searches the specified path without recursing
into subdirectories. Note that -3 -5, -3-5, and -35 search 3 to 5
levels deep. Enables -r if -R or -r is not specified.
-g GLOBS, --glob=GLOBS
Search only files whose name matches the specified comma-separated
list of GLOBS, same as --include='glob' for each `glob' in GLOBS.
When a `glob' is preceded by a `!' or a `^', skip files whose name
matches `glob', same as --exclude='glob'. When `glob' contains a
`/', full pathnames are matched. Otherwise basenames are matched.
When `glob' ends with a `/', directories are matched, same as
--include-dir='glob' and --exclude-dir='glob'. A leading `/'
matches the working directory. This option may be repeated and may
be combined with options -M, -O and -t to expand searches. See
`ugrep --help globs' and `man ugrep' section GLOBBING for details.
-O EXTENSIONS, --file-extension=EXTENSIONS
Search only files whose filename extensions match the specified
comma-separated list of EXTENSIONS, same as --include='*.ext' for
each `ext' in EXTENSIONS. When `ext' is preceded by a `!' or a
`^', skip files whose filename extensions matches `ext', same as
--exclude='*.ext'. This option may be repeated and may be combined
with options -g, -M and -t to expand the recursive search.
-t TYPES, --file-type=TYPES
Search only files associated with TYPES, a comma-separated list of
file types. Each file type corresponds to a set of filename
extensions passed to option -O and filenames passed to option -g.
For capitalized file types, the search is expanded to include files
with matching file signature magic bytes, as if passed to option
-M. When a type is preceded by a `!' or a `^', excludes files of
the specified type. This option may be repeated.
--stats
Output statistics on the number of files and directories searched,
and the inclusion and exclusion constraints applied.
如果未指定文件参数并从终端读取输入，则将递归搜索执行，就像指定-r一样。要强制从标准输入中读取，请指定-作为文件参数。
递归列出工作目录中的所有非空文件：
ug -r -l ''
在工作目录中列出所有非空文件，但不更深入（在这种情况下给出文件参数.对于工作目录）：
ug -l '' .
在目录mydir中列出所有非空文件，但不会更深入（因为给出了文件参数）：
ug -l '' mydir
在遵循符号链接时，在mydir中列出所有非空文件，并更深入：
ug -R -l '' mydir
要递归在指定的路径上列出所有非空文件，同时仅访问子目录，即在一个级别上访问mydir/和子目录的目录更深的mydir/*/ （请注意，可以将-2 -l缩写为-l2 ）：
ug -2 -l '' mydir
递归列出目录mydir中的所有非空文件，而不是遵循任何符号链接（在命令行（例如mydir ）上除外）：
ug -rl '' mydir
递归列出所有与文本CPP匹配的makefiles：
ug -l -tmake 'CPP'
递归列出所有Makefile.*匹配bin_PROGRAMS ：
ug -l -g'Makefile.*' 'bin_PROGRAMS'
递归列出所有具有扩展名.sh的非空文件，以-Osh ：
ug -l -Osh ''
递归地列出所有基于扩展名和shebangs的shell脚本，以-tShell ：
ug -l -tShell ''
递归仅根据-tshell的扩展名列出所有shell脚本：
ug -l -tshell ''
？返回目录
--bool, -%, -%%
Specifies Boolean query patterns. A Boolean query pattern is
composed of `AND', `OR', `NOT' operators and grouping with `(' `)'.
Spacing between subpatterns is the same as `AND', `|' is the same
as `OR' and a `-' is the same as `NOT'. The `OR' operator binds
more tightly than `AND'. For example, --bool 'A|B C|D' matches
lines with (`A' or `B') and (`C' or `D'), --bool 'A -B' matches
lines with `A' and not `B'. Operators `AND', `OR', `NOT' require
proper spacing. For example, --bool 'A OR B AND C OR D' matches
lines with (`A' or `B') and (`C' or `D'), --bool 'A AND NOT B'
matches lines with `A' without `B'. Quoted subpatterns are matched
literally as strings. For example, --bool 'A "AND"|"OR"' matches
lines with `A' and also either `AND' or `OR'. Parentheses are used
for grouping. For example, --bool '(A B)|C' matches lines with `A'
and `B', or lines with `C'. Note that all subpatterns in a Boolean
query pattern are regular expressions, unless -F is specified.
Options -E, -F, -G, -P and -Z can be combined with --bool to match
subpatterns as strings or regular expressions (-E is the default.)
This option does not apply to -f FILE patterns. The double short
option -%% enables options --bool --files. Option --stats displays
the Boolean search patterns applied. See also options --and,
--andnot, --not, --files and --lines.
--files
Boolean file matching mode, the opposite of --lines. When combined
with option --bool, matches a file if all Boolean conditions are
satisfied. For example, --bool --files 'A B|C -D' matches a file
if some lines match `A', and some lines match either `B' or `C',
and no line matches `D'. See also options --and, --andnot, --not,
--bool and --lines. The double short option -%% enables options
--bool --files.
--lines
Boolean line matching mode for option --bool, the default mode.
--and [[-e] PATTERN] ... -e PATTERN
Specify additional patterns to match. Patterns must be specified
with -e. Each -e PATTERN following this option is considered an
alternative pattern to match, i.e. each -e is interpreted as an OR
pattern. For example, -e A -e B --and -e C -e D matches lines with
(`A' or `B') and (`C' or `D'). Note that multiple -e PATTERN are
alternations that bind more tightly together than --and. Option
--stats displays the search patterns applied. See also options
--not, --andnot, and --bool.
--andnot [[-e] PATTERN] ...
Combines --and --not. See also options --and, --not, and --bool.
--not [-e] PATTERN
Specifies that PATTERN should not match. Note that -e A --not -e B
matches lines with `A' or lines without a `B'. To match lines with
`A' that have no `B', specify -e A --andnot -e B. Option --stats
displays the search patterns applied. See also options --and,
--andnot, and --bool.
--stats
Output statistics on the number of files and directories searched,
and the inclusion and exclusion constraints applied.
请注意， --and --not和 - --andnot选项都需要-e PATTERN 。
-%选项使所有基于布尔值的模式都支持以下从最高级别到最低级别列出的逻辑操作：
| 操作员 | 选择 | 结果 |
|---|---|---|
"x" | 从字面上且完全按照指定的方式匹配x （使用标准正则逃脱Q和E ） | |
( ) | 布尔表达分组 | |
-x | NOT x | 倒匹配，IE匹配如果x不匹配 |
x|y | x OR y | 与x或y匹配线条 |
xy | x AND y | 将线与x和y匹配 |
x和y是不以特殊符号开头的子图案| ， -和( （使用引号或 evase匹配这些）；
-并且NOT相同的，并且优先考虑OR这意味着-x|y == (-x)|y 。
| OR是相同的，并优先考虑AND这意味着xy|z == x (y|z)
搜索完成后， --stats选项以人类可读形式显示了布尔值查询（连接正常形式）。要在不搜索的情况下显示CNF，请从EOF终止的标准输入中阅读，例如echo | ugrep -% '...' --stats 。
除了NOT的颜色（ NOT subpattern）使用x|-y ）时，subpatern在输出中是颜色高的。请注意，子图案可能重叠。在那种情况下，只有第一个匹配的子图案是颜色的。
当子图案匹配新线时，可以匹配多行。但是，有一个例外：以(?=X) lookaheads结尾的子图案在X跨越多行时可能无法匹配。
空图案与任何线路（GREP标准）匹配。因此， -% 'x|""|y'与所有内容匹配， x和y没有颜色高。选项-y应该用于将每一行作为上下文显示，例如-y 'x|y' 。
类似FZF的交互式查询（带有模糊匹配的固定字符串的布尔搜索，以允许多达4个额外的字符与-Z+4 in -w with -w ），按tab和alt -y，以查看具有匹配项的文件。按Shift-Tab和Alt-L，返回到匹配文件列表：
ug -Q -%% -l -w -F -Z+4 --sort=best
递归地找到所有包含hot和dog文件，并带有选项--files ：
ug -%% 'hot dog'
ug --files -e hot --and dog
在myfile.txt中找到包含hot和dog的线：
ug -% 'hot dog' myfile.txt
ug -e hot --and dog myfile.txt
在myfile.txt中查找包含place的线，然后在myfile.txt中找到hotdog或taco （或两者）：
ug -% 'hotdog|taco place' myfile.txt
ug -e hotdog -e taco --and place myfile.txt
相同，但排除匹配diner线条：
ug -% 'hotdog|taco place -diner' myfile.txt
ug -e hotdog -e taco --and place --andnot diner myfile.txt
找到与fast和food相匹配但在myfile.txt中bad diner或线条的线条：
ug -% 'diner|(fast food -bad)' myfile.txt
在myfile.txt中找到带有fast food的线（准确）或与diner old线条bad
ug -% '"fast food"|diner -bad -old' myfile.txt
相同，但使用具有相同含义的不同布尔表达：
ug -% '"fast food"|diner -(bad|old)' myfile.txt
找到diner的线条good在myfile.txt中（也就是说，在没有diner情况下显示出good的线条，并与diner一起展示线条，但只有逻辑上暗示good人！）：）：
ug -% 'good|-diner' myfile.txt
ug -e good --not diner myfile.txt
在myfile.txt中找到使用foo and -bar和"baz"的行（不是-和"应该使用 eScapes，以及--and -e -bar ）：
ug -% 'foo -bar "baz"' myfile.txt
ug -e foo --and -e -bar --and '"baz"' myfile.txt
搜索myfile.cpp查找使用TODO或FIXME的行，但并非在同一条线上，例如XOR：
ug -% 'TODO|FIXME -(TODO FIXME)' myfile.cpp
ug -e TODO -e FIXME --and --not TODO --not FIXME myfile.cpp
？返回目录
-e PATTERN, --regexp=PATTERN
Specify a PATTERN to search the input. An input line is selected
if it matches any of the specified patterns. This option is useful
when multiple -e options are used to specify multiple patterns, or
when a pattern begins with a dash (`-'), or to specify a pattern
after option -f or after the FILE arguments.
-f FILE, --file=FILE
Read newline-separated patterns from FILE. White space in patterns
is significant. Empty lines in FILE are ignored. If FILE does not
exist, the GREP_PATH environment variable is used as path to FILE.
If that fails, looks for FILE in /usr/local/share/ugrep/pattern.
When FILE is a `-', standard input is read. This option may be
repeated.
-L, --files-without-match
Only the names of files not containing selected lines are written
to standard output. Pathnames are listed once per file searched.
If the standard input is searched, the string ``(standard input)''
is written.
-N PATTERN, --neg-regexp=PATTERN
Specify a negative PATTERN to reject specific -e PATTERN matches
with a counter pattern. Note that longer patterns take precedence
over shorter patterns, i.e. a negative pattern must be of the same
length or longer to reject matching patterns. Option -N cannot be
specified with -P. This option may be repeated.
-v, --invert-match
Selected lines are those not matching any of the specified
patterns.
-w, --word-regexp
The PATTERN is searched for as a word, such that the matching text
is preceded by a non-word character and is followed by a non-word
character. Word-like characters are Unicode letters, digits and
connector punctuations such as underscore.
-x, --line-regexp
Select only those matches that exactly match the whole line, as if
the patterns are surrounded by ^ and $.
另请参见与传统的GNU/BSD GREP选项相比，请参见带有 -％， -％%%， - 和， - 不使用 -％， - %%， - 和， - - 不。
在文件myfile.sh中显示行，但不匹配^[ t]*# ：
ug -v '^[ t]*#' myfile.sh
搜索myfile.cpp以使用FIXME且urgent线条，但不是Scotty ：
ugrep FIXME myfile.cpp | ugrep urgent | ugrep -v Scotty
相同，但使用-%用于布尔查询：
ug -% 'FIXME urgent -Scotty' myfile.cpp
使用模式d+搜索小数 D 0使用负模式0d+并排除555 ：
ug -e 'd+' -N '0d+' -N 555 myfile.cpp
通过使用“负模式” -n' -N -N '/<display>'在不匹配myfile.py display搜索以disp开头的单词。
ug -e '<disp' -N '<display>' myfile.py
要在文件myfile.py中搜索带有字符串和注释中的单词中的单词display行，其中-f在这种情况下指定了文件中的模式，在这种情况下为预定义的模式：
ug -n -w 'display' -f python/zap_strings -f python/zap_comments myfile.py
显示不是空白行的行：
ug -x -e '.*' -N 'h*' myfile.py
相同，但使用-v和-x与h* ，ie模式^h*$ ：
ug -v -x 'h*' myfile.py
递归列出所有不包含单词display单词的Python文件，以便在字符串和评论中出现该单词：
ug -RL -tPython -w 'display' -f python/zap_strings -f python/zap_comments
？返回目录
--encoding=ENCODING
The encoding format of the input. The default ENCODING is binary
and UTF-8 which are the same. Note that option -U specifies binary
PATTERN matching (text matching is the default.)
二进制，ASCII和UTF-8文件不需要此选项搜索它们。同样，假设UTF-16和UTF-32文件像往常一样以UTF-16和UTF-32文件开头，则UTF-16和UTF-32文件不需要此选项来搜索它们。其他文件编码需要选项--encoding=ENCODING ：
| 编码 | 范围 |
|---|---|
| ASCII | 不适用 |
| UTF-8 | 不适用 |
| UTF-16与Bom | 不适用 |
| UTF-32与Bom | 不适用 |
| UTF-16是bom | UTF-16或UTF-16BE |
| utf-16 le w/o bom | UTF-16LE |
| UTF-32 W/O BOM | UTF-32或UTF-32BE |
| UTF-32 W/O BOM | UTF-32LE |
| 拉丁语1 | LATIN1或ISO-8859-1 |
| ISO-8859-1 | ISO-8859-1 |
| ISO-8859-2 | ISO-8859-2 |
| ISO-8859-3 | ISO-8859-3 |
| ISO-8859-4 | ISO-8859-4 |
| ISO-8859-5 | ISO-8859-5 |
| ISO-8859-6 | ISO-8859-6 |
| ISO-8859-7 | ISO-8859-7 |
| ISO-8859-8 | ISO-8859-8 |
| ISO-8859-9 | ISO-8859-9 |
| ISO-8859-10 | ISO-8859-10 |
| ISO-8859-11 | ISO-8859-11 |
| ISO-8859-13 | ISO-8859-13 |
| ISO-8859-14 | ISO-8859-14 |
| ISO-8859-15 | ISO-8859-15 |
| ISO-8859-16 | ISO-8859-16 |
| Mac（CR = Newline） | MAC |
| Macroman（CR = Newline） | MACROMAN |
| EBCDIC | EBCDIC |
| DOS代码页437 | CP437 |
| DOS代码第850页 | CP850 |
| DOS代码页858 | CP858 |
| Windows Code Page 1250 | CP1250 |
| Windows Code Page 1251 | CP1251 |
| Windows Code Page 1252 | CP1252 |
| Windows Code Page 1253 | CP1253 |
| Windows Code Page 1254 | CP1254 |
| Windows Code Page 1255 | CP1255 |
| Windows Code Page 1256 | CP1256 |
| Windows Code Page 1257 | CP1257 |
| Windows Code Page 1258 | CP1258 |
| KOI8-R | KOI8-R |
| KOI8-U | KOI8-U |
| koi8-ru | KOI8-RU |
请注意，REGEX模式始终在UTF-8中指定（包括ASCII）。要搜索具有二进制模式的二进制文件，请参阅使用-U，-W和-X的搜索和显示二进制文件。
递归列出ASCII（即7位）的所有文件：
ug -L '[^[:ascii:]]'
递归列出所有非ASCII的文件，即UTF-8，UTF-16和UTF-32文件，具有非ASCII UNICODE字符（U+0080及以上）：
ug -l '[^[:ascii:]]'
检查文件是否包含非ASCII UNICODE（U+0080及以上）：
ug -q '[^[:ascii:]]' myfile && echo "contains Unicode"
要从文件中删除无效-o Unicode字符（请注意，由于检测和拒绝二进制数据并添加了二进制数据，因此不起作用，但添加了新线，但是--format="%o%不检查二进制文件并将匹配项复制为“ IS” ）：
ug "[p{Unicode}n]" --format="%o" badfile.txt
递归列出具有无效的UTF内容的文件（即无效的UTF-8字节序列或包含任何UTF-8/16/32代码点的文件，这些代码点超出有效的Unicode范围），通过与任何代码点匹配.通过使用负模式-N 'p{Unicode}'忽略每个有效的Unicode字符：
ug -l -e '.' -N 'p{Unicode}'
显示包含笑脸表情符号的线：
ug '[?-?]' emojis.txt
使用x{hhhh}获得相同的结果，以选择一个Unicode字符范围：
ug '[x{1F600}-x{1F60F}]' emojis.txt
显示包含名称Gödel（或Goedel），Escher或Bach的行：
ug 'G(ö|oe)del|Escher|Bach' GEB.txt wiki.txt
在UTF-16文件中以UTF-16 BOM标记的UTF-16文件中的下层或高层搜索lorem ：
ug -iw 'lorem' utf16lorem.txt
搜索utf16lorem.txt当此文件没有utf-16 bom时，使用--encoding ：
ug --encoding=UTF-16 -iw 'lorem' utf16lorem.txt
要搜索在ISO-8859-1中编码的spanish-iso.txt ：
ug --encoding=ISO-8859-1 -w 'año' spanish-iso.txt
？返回目录
-o, --only-matching
Output only the matching part of lines. If -A, -B or -C is
specified, fits the match and its context on a line within the
specified number of columns.
多行可以与匹配newline字符的模式相匹配。使用选项-o仅输出匹配，而不是匹配的完整行。
要匹配n线断裂，请在模式中包含n以匹配LF字符。如果要匹配rn和n线路断裂，请使用r?n或简单地使用R匹配任何Unicode line Break rn ， r ， v ， v， f， f ， n ，u，U +0085，U+2028和U+2029。
匹配c/c ++ /*...*/多行注释：
ug '/*(.*n)*?.**+/' myfile.cpp
使用预定义的c/comments模式与-fc/comments匹配C/C ++注释，仅限于匹配零件，仅带有选项-o ：
ug -of c/comments myfile.cpp
与sed -n '/begin/,/end/p'相同：要匹配包含begin的线与包含end后的第一行之间的所有行，使用懒惰重复：
ug -o '.*begin(.|n)*?end.*' myfile.txt
？返回目录
-A NUM, --after-context=NUM
Output NUM lines of trailing context after matching lines. Places
a --group-separator between contiguous groups of matches. If -o is
specified, output the match with context to fit NUM columns after
the match or shortens the match. See also options -B, -C and -y.
-B NUM, --before-context=NUM
Output NUM lines of leading context before matching lines. Places
a --group-separator between contiguous groups of matches. If -o is
specified, output the match with context to fit NUM columns before
the match or shortens the match. See also options -A, -C and -y.
-C NUM, --context=NUM
Output NUM lines of leading and trailing context surrounding each
matching line. Places a --group-separator between contiguous
groups of matches. If -o is specified, output the match with
context to fit NUM columns before and after the match or shortens
the match. See also options -A, -B and -y.
-y, --any-line
Any line is output (passthru). Non-matching lines are output as
context with a `-' separator. See also options -A, -B, and -C.
--width[=NUM]
Truncate the output to NUM visible characters per line. The width
of the terminal window is used if NUM is not specified. Note that
double wide characters in the output may result in wider lines.
-o, --only-matching
Output only the matching part of lines. If -A, -B or -C is
specified, fits the match and its context on a line within the
specified number of columns.
在匹配行之前和之后显示两行上下文：
ug -C2 'FIXME' myfile.cpp
在匹配的行之后显示三行上下文：
ug -A3 'FIXME.*' myfile.cpp:
在每条匹配行之前使用C函数定义显示一行上下文（C名称是非nunicode）：
ug -B1 -f c/functions myfile.c
要在每条匹配行之前使用C ++函数定义显示一行上下文（C ++名称可能是Unicode）：
ug -B1 -f c++/functions myfile.cpp
显示任何非匹配行作为与-y ：匹配行的上下文：
ug -y -f c++/functions myfile.cpp
显示一条具有六个六角形上下文的匹配线的六角形：
ug -C1 -UX 'xaaxbbxcc' a.out
使用上下文选项显示一行中的上下文，其中包括选项-o ：
ug -o -C20 'pattern' myfile.cpp
相同，但是带有标题，行号和列号（ -k ）的漂亮输出，并显示上下文：
ug --pretty -oC20 'pattern' myfile.cpp
？返回目录
-f FILE, --file=FILE
Read newline-separated patterns from FILE. White space in patterns
is significant. Empty lines in FILE are ignored. If FILE does not
exist, the GREP_PATH environment variable is used as path to FILE.
If that fails, looks for FILE in /usr/local/share/ugrep/pattern.
When FILE is a `-', standard input is read. This option may be
repeated.
--ignore-files[=FILE]
Ignore files and directories matching the globs in each FILE that
is encountered in recursive searches. The default FILE is
`.gitignore'. Matching files and directories located in the
directory of the FILE and in subdirectories below are ignored.
Globbing syntax is the same as the --exclude-from=FILE gitignore
syntax, but files and directories are excluded instead of only
files. Directories are specifically excluded when the glob ends in
a `/'. Files and directories explicitly specified as command line
arguments are never ignored. This option may be repeated to
specify additional files.
-g GLOBS, --glob=GLOBS
Search only files whose name matches the specified comma-separated
list of GLOBS, same as --include='glob' for each `glob' in GLOBS.
When a `glob' is preceded by a `!' or a `^', skip files whose name
matches `glob', same as --exclude='glob'. When `glob' contains a
`/', full pathnames are matched. Otherwise basenames are matched.
When `glob' ends with a `/', directories are matched, same as
--include-dir='glob' and --exclude-dir='glob'. A leading `/'
matches the working directory. This option may be repeated and may
be combined with options -M, -O and -t to expand searches. See
`ugrep --help globs' and `man ugrep' section GLOBBING for details.
-O EXTENSIONS, --file-extension=EXTENSIONS
Search only files whose filename extensions match the specified
comma-separated list of EXTENSIONS, same as --include='*.ext' for
each `ext' in EXTENSIONS. When `ext' is preceded by a `!' or a
`^', skip files whose filename extensions matches `ext', same as
--exclude='*.ext'. This option may be repeated and may be combined
with options -g, -M and -t to expand the recursive search.
-t TYPES, --file-type=TYPES
Search only files associated with TYPES, a comma-separated list of
file types. Each file type corresponds to a set of filename
extensions passed to option -O and filenames passed to option -g.
For capitalized file types, the search is expanded to include files
with matching file signature magic bytes, as if passed to option
-M. When a type is preceded by a `!' or a `^', excludes files of
the specified type. This option may be repeated.
--stats
Output statistics on the number of files and directories searched,
and the inclusion and exclusion constraints applied.
文件类型用ugrep -tlist列出。该列表基于已建立的文件名扩展名和“魔术字节”。如果您有未列出的文件类型，请使用选项-O和/或-M 。您可能需要定义一个别名，例如alias ugft='ugrep -Oft'作为速记，以使用文件名后缀.ft搜索文件。
在C/C ++文件（ .h ， .hpp ， .c ， .cpp等）中递归显示功能定义，并带有-tc++ ， -o ， -n和-f c++/functions的行号。
ug -on -tc++ -f c++/functions
在.c和.cpp文件中递归显示功能定义，其中包含-Oc,cpp ， -o ， -n和-f c++/functions的行号：
ug -on -Oc,cpp -f c++/functions
递归列出所有带有-tShell的Shell文件以匹配文件名扩展名和用Shell Shebang的文件，除了带有后缀.sh的文件外，
ug -l -tShell -O^sh ''
递归用-t^Shell列出所有非壳文件：
ug -l -t^Shell ''
递归地列出所有没有外壳文件名扩展名的Shell Shebang的Shell Files：
ug -l -tShell -t^shell ''
要在C/C ++注释中搜索使用FIXME的行，请在多行字符串中排除FIXME ：
ug -n 'FIXME' -f c++/zap_strings myfile.cpp
要从标准输入中读取图案TODO和FIXME以读取输入中的线条，同时不包括C ++字符串中的匹配项：
ug -on -f - -f c++/zap_strings myfile.cpp <<END
TODO
FIXME
END
要在XML文件中显示XML元素和属性标签，仅限于-o匹配部分，不包括放置在（多行）注释中的标签：
ug -o -f xml/tags -f xml/zap_comments myfile.xml
？返回目录
-z, --decompress
Search compressed files and archives. Archives (.cpio, .pax, .tar)
and compressed archives (e.g. .zip, .7z, .taz, .tgz, .tpz, .tbz,
.tbz2, .tb2, .tz2, .tlz, .txz, .tzst) are searched and matching
pathnames of files in archives are output in braces. When used
with option --zmax=NUM, searches the contents of compressed files
and archives stored within archives up to NUM levels. If -g, -O,
-M, or -t is specified, searches files stored in archives whose
filenames match globs, match filename extensions, match file
signature magic bytes, or match file types, respectively.
Supported compression formats: gzip (.gz), compress (.Z), zip, 7z,
bzip2 (requires suffix .bz, .bz2, .bzip2, .tbz, .tbz2, .tb2, .tz2),
lzma and xz (requires suffix .lzma, .tlz, .xz, .txz),
lz4 (requires suffix .lz4),
zstd (requires suffix .zst, .zstd, .tzst),
brotli (requires suffix .br),
bzip3 (requires suffix .bz3).
--zmax=NUM
When used with option -z (--decompress), searches the contents of
compressed files and archives stored within archives by up to NUM
expansion stages. The default --zmax=1 only permits searching
uncompressed files stored in cpio, pax, tar, zip and 7z archives;
compressed files and archives are detected as binary files and are
effectively ignored. Specify --zmax=2 to search compressed files
and archives stored in cpio, pax, tar, zip and 7z archives. NUM
may range from 1 to 99 for up to 99 decompression and de-archiving
steps. Increasing NUM values gradually degrades performance.
用GZIP（ .gz ），Compress（ .Z ），BZIP2（ .bz ， .bz2 ， .bzip2 ）压缩的文件，lzma（ .lzma ），xz（ .xz ），lz4（ .lz4 ），ZSTD（.ZST，.ZST，.ZST， .zst ，， .zstd ），brotli（ .br ）和bzip3（ .bz3 ）在安装相应的库并使用UGREP编译时，使用选项-z搜索。此选项不需要压缩文件。尽管较慢，但也搜索了未压缩的文件。
可以使用UGREP过滤器搜索其他压缩格式。
使用选项-z搜索档案（CPIO，JAR，PAX，TAR，ZIP和7Z）。匹配的存档中的常规文件输出，并带有{和}括号中的存档路径名。支持的焦油格式为V7，USTAR，GNU，OLDGNU和PAX。支持的CPIO格式是ODC，NEWC和CRC。不支持的是过时的不容易出现的旧二进制CPIO格式。档案格式CPIO，TAR和PAX自动根据其内容自动识别选项-z ，独立于其文件名后缀。
默认情况下，还搜索了存储在邮政编码中的未压缩档案：所有CPIO，PAX和tar文件存储在zip中，而7Z档案将自动识别和搜索。但是，默认情况下，未识别存储在档案中的压缩文件，例如未搜索存储在TAR文件中的ZIP文件，而是搜索所有压缩文件和档案，就好像它们是二进制文件而不对其进行解压缩一样。
指定--zmax=NUM到搜索包含压缩文件和档案的档案，以深度为NUM级别。 NUM的值可能从1到99范围内，最多为99个减压和去构造的步骤，可扩展到99个嵌套档案。较大--zmax=NUM数值降解性能。对于大多数实际用例，例如搜索存储在焦油文件中的zip文件，您不太可能需要99，因为--zmax=2足够。
当选项-z与选项一起使用时-g ， -O ， -M或-t ，仅搜索与文件名选择标准（Glob，Extension，Magic Bytes或File类型）匹配的压缩和未压缩文件。例如， ugrep -r -z -tc++搜索C ++文件，例如main.cpp和zip和tar档案，其中包含c ++文件，例如main.cpp 。搜索中还包括压缩的C ++文件，例如main.cpp.gz和main.cpp.xz同样，在搜索存在的任何CPIO，PAX，TAR，ZIP和7Z档案中，都可以搜索其包含的C ++文件，例如main.cpp 。使用选项--stats查看应用于递归搜索中滤波器路径名的列表以及在搜索存档内容时。
当选项-z与选项一起使用-g ， -O ， -M或-t以搜索CPIO，JAR，PAX，PAX，TAR，ZIP和7Z Archives时，仅搜索符合文件名选择标准的存档文件。
自动检测到GZIP，压缩和拉链格式，这在从标准输入中读取GZIP压缩数据时很有用，例如从管道重定向的输入。其他压缩格式需要文件名词后缀： .bz ， .bz2或.bzip2 for Bzip2，lzma的.lzma ， .xz ，xz， .lz4 for lz4， .zst或.zstd for ZSTD，ZSTD， .br for brotli for brotli和.bz3对于BZIP3。还为.tzst的.txz ， .tbz ， .tbz2 ， .tb2和.tz2用于.taz .tgz焦油存档.tpz .tlz要使用来自标准输入的UGREP搜索这些格式，请使用选项--label='stdin.bz2'用于bzip2， --label='stdin.lzma'用于lzma， --label='stdin.xz'用于xz， --label='stdin.lz4用于lz4和--label='stdin.zst for ZSTD等。 stdin这个名字是任意的，可能会被省略：
| 格式 | 文件名后缀 | 焦油/pax档案短后缀 | 后缀需要吗？ | 来自Stdin的Ugrep | 图书馆 |
|---|---|---|---|---|---|
| 压缩包 | .gz | .taz ， .tgz ， .tpz | 不 | 自动的 | 库兹 |
| 压缩 | .Z | .taZ ， .tZ | 不 | 自动的 | 内置 |
| 拉链 | .zip ， .zipx ， .ZIP | 不 | 自动的 | 库兹 | |
| 7zip | .7z | 是的 | --label=.7z | 内置 | |
| 压缩包2 | .bz ， .bz2 ， .bzip2 | .tb2 ， .tbz ， .tbz2 ， .tz2 | 是的 | --label=.bz2 | 库2 |
| 利兹玛 | .lzma | .tlz | 是的 | --label=.lzma | 利布尔兹马 |
| xz | .xz | .txz | 是的 | --label=.xz | 利布尔兹马 |
| lz4 | .lz4 | 是的 | --label=.lz4 | liblz4 | |
| 兹标准 | .zst ， .zstd | .tzst | 是的 | --label=.zst | libzstd |
| 布罗特利 | .br | 是的 | --label=.br | libbrotlidec | |
| BZIP3 | .bz3 | 是的 | --label=.bz3 | libbzip3 |
GZIP，BZIP2，XZ，LZ4和ZSTD格式支持串联的压缩文件。串联压缩文件被搜索为一个文件。
存储支持的拉链压缩方法（0），Deflate（8），BZIP2（12），LZMA（14），XZ（95）和ZSTD（93）。 BZIP2，LZMA，XZ和ZSTD方法要求与相应的压缩库一起编译UGREP。
不支持搜索加密的邮递档案（也许在将来发行，具体取决于增强要求）。
与其他方法相比，搜索7ZIP档案需要更多的RAM和更多的时间。 7ZIP LZMA SDK实现不支持流媒体，需要物理可寻求的7Z文件。这意味着将7Z文件嵌套在档案中时无法搜索。最好的是避免7zip。可以使用./build.sh --disable-7zip禁用对7ZIP的支持以构建UGREP。
Option -z使用线程进行任务并行性，以通过对解压缩流的搜索同时运行解压缩器来加速搜索较大的文件。
要列出包含package.zip的所有非空文件。
ug --zmax=2 -z -l '' package.zip
同样，但仅列出了Python源代码文件，包括调用Python的脚本，并带有选项-tPython （ ugrep -tlist for Sotetial）：
ug --zmax=2 -z -l -tPython '' package.zip
要搜索python应用程序作为焦油文件，其依赖项包括为车轮（带有python代码的zip文件），请在app.tgz中搜索my_class词：
ug --zmax=2 -z -tPython -w my_class app.tgz
要递归搜索C ++文件，其中包括my_function一词的压缩文件，而跳过C和C ++注释：
ug -z -r -tc++ -Fw my_function -f cpp/zap_comments
要搜索标准输入上的BZIP2，LZMA，XZ，LZ4和ZSTD压缩数据，选项--label可用于指定与压缩格式相对应的扩展，以强制减压，例如，当BZIP2扩展名不可用ugrep可用时，例如：
cat myfile.bz2 | ugrep -z --label='stdin.bz2' 'xyz'
要在project.zip中搜索文件main.cpp for TODO和FIXME行：
ug -z -g main.cpp -w -e 'TODO' -e 'FIXME' project.zip
搜索TARBALL project.tar.gz使用TODO和FIXME行以搜索C ++文件：
ug -z -tc++ -w -e 'TODO' -e 'FIXME' project.tar.gz
在任何情况下，搜索匹配glob *.txt project.zip文件license -g 。
ug -z -g '*.txt' -w -i 'license' project.zip
要通过tarball project.tgz中的所有C ++文件显示和页面：
ug --pager -z -tc++ '' project.tgz
要列出匹配gitignore-style glob的文件/**/projects/project1.* in projects.tgz中，通过选择档案中包含的文件，文本December 12 ：
ug -z -l -g '/**/projects/project1.*' -F 'December 12' projects.tgz
要查看带有-Ojar和-OMF JAR文件中的META -INF/SUFTEST.MF数据以选择JAR文件和其中的MF文件（需要-Ojar ，否则将跳过JAR文件，尽管我们可以从标准输入）：
ug -z -h -OMF,jar '' my.jar
要提取包含project.tgz的FIXME的C ++文件，我们将-m1与--format="'%z '"一起使用-m1来生成位于档案中匹配fixme word FIXME的档案中的空间分隔的文件名称列表：
tar xzf project.tgz `ugrep -z -l -tc++ --format='%z ' -w FIXME project.tgz`
要使用find进行深度优先搜索，然后使用cpio和ugrep搜索文件：
find . -depth -print | cpio -o | ugrep -z 'xyz'
？返回目录
--ignore-files[=FILE]
Ignore files and directories matching the globs in each FILE that
is encountered in recursive searches. The default FILE is
`.gitignore'. Matching files and directories located in the
directory of the FILE and in subdirectories below are ignored.
Globbing syntax is the same as the --exclude-from=FILE gitignore
syntax, but files and directories are excluded instead of only
files. Directories are specifically excluded when the glob ends in
a `/'. Files and directories explicitly specified as command line
arguments are never ignored. This option may be repeated to
specify additional files.
-M MAGIC, --file-magic=MAGIC
Only files matching the signature pattern MAGIC are searched. The
signature "magic bytes" at the start of a file are compared to
the MAGIC regex pattern. When matching, the file will be searched.
When MAGIC is preceded by a `!' or a `^', skip files with matching
MAGIC signatures. This option may be repeated and may be combined
with options -O and -t to expand the search. Every file on the
search path is read, making searches potentially more expensive.
-O EXTENSIONS, --file-extension=EXTENSIONS
Search only files whose filename extensions match the specified
comma-separated list of EXTENSIONS, same as --include='*.ext' for
each `ext' in EXTENSIONS. When `ext' is preceded by a `!' or a
`^', skip files whose filename extensions matches `ext', same as
--exclude='*.ext'. This option may be repeated and may be combined
with options -g, -M and -t to expand the recursive search.
-t TYPES, --file-type=TYPES
Search only files associated with TYPES, a comma-separated list of
file types. Each file type corresponds to a set of filename
extensions passed to option -O and filenames passed to option -g.
For capitalized file types, the search is expanded to include files
with matching file signature magic bytes, as if passed to option
-M. When a type is preceded by a `!' or a `^', excludes files of
the specified type. This option may be repeated.
-g GLOBS, --glob=GLOBS
Search only files whose name matches the specified comma-separated
list of GLOBS, same as --include='glob' for each `glob' in GLOBS.
When a `glob' is preceded by a `!' or a `^', skip files whose name
matches `glob', same as --exclude='glob'. When `glob' contains a
`/', full pathnames are matched. Otherwise basenames are matched.
When `glob' ends with a `/', directories are matched, same as
--include-dir='glob' and --exclude-dir='glob'. A leading `/'
matches the working directory. This option may be repeated and may
be combined with options -M, -O and -t to expand searches. See
`ugrep --help globs' and `man ugrep' section GLOBBING for details.
--stats
Output statistics on the number of files and directories searched,
and the inclusion and exclusion constraints applied.
递归列出以#! Shebangs：
ug -l -M'#!' ''
递归列出以#开头但不是#! Shebangs：
ug -l -M'#' -M'^#!' ''
递归地列出所有Python文件（Extension .py或shebang）与-tPython ：
ug -l -tPython ''
递归用-t^Shell列出所有非壳文件：
ug -l -t^Shell ''
递归列出具有导入语句的Python文件（Extension .py或Shebang），包括带有-. :
ug -l. -tPython -f python/imports
？返回目录
-Z[best][+-~][MAX], --fuzzy=[best][+-~][MAX]
Fuzzy mode: report approximate pattern matches within MAX errors.
The default is -Z1: one deletion, insertion or substitution is
allowed. If `+`, `-' and/or `~' is specified, then `+' allows
insertions, `-' allows deletions and `~' allows substitutions. For
example, -Z+~3 allows up to three insertions or substitutions, but
no deletions. If `best' is specified, then only the best matching
lines are output with the lowest cost per file. Option -Zbest
requires two passes over a file and cannot be used with standard
input or Boolean queries. Option --sort=best orders matching files
by best match. The first character of an approximate match always
matches a character at the beginning of the pattern. To fuzzy
match the first character, replace it with a `.' or `.?'. Option
-U applies fuzzy matching to ASCII and bytes instead of Unicode
text. No whitespace may be given between -Z and its argument.
模式的开头始终匹配近似匹配的第一个字符，这是一种实用策略，以防止许多虚假的“随机”匹配的短图案。这也大大提高了搜索速度。使第一个字符可选地匹配它，例如p?attern或使用点作为图案的开始，以匹配任何宽字符（但这很慢）。
线馈（ n ）和nul（ ）字符永远不会被删除或替换，以确保模糊匹配不会将模式匹配扩展到REGEX模式指定的线数之外。
选项-U （ --ascii或--binary ）将模糊匹配限制为ASCII和二进制，并且仅在字节中测量的编辑距离。 Otherwise, fuzzy pattern matching is performed with Unicode patterns and edit distances are measured in Unicode characters.
Option --sort=best orders files by best match. Files with at least one exact match anywhere in the file are shown first, followed by files with approximate matches in increasing minimal edit distance order. That is, ordered by the minimum error (edit distance) found among all approximate matches per file.
To recursively search for approximate matches of the word foobar with -Z , ie approximate matching with one error, eg Foobar , foo_bar , foo bar , fobar and other forms with one missing, one extra or one deleted character:
ug -Z 'foobar'
Same, but matching words only with -w and ignoring case with -i :
ug -Z -wi 'foobar'
Same, but permit up to 2 insertions with -Z+2 , no deletions/substitutions (matches up to 2 extra characters, such as foos bar ), insertions-only offers the fastest fuzzy matching method:
ug -Z+3 -wi 'foobar'
Same, but sort matches from best (at least one exact match or fewest fuzzy match errors) to worst:
ug -Z+3 -wi --sort=best 'foobar'
Note: because sorting by best match requires two passes over the input files, the efficiency of concurrent searching is significantly reduced.
Same, but with customized formatting to show the edit distance "cost" of the approximate matches with format field %Z and %F to show the pathname:
ug -Z+3 -wi --format='%F%Z:%O%~' --sort=best 'foobar'
Same, but this time count the matches with option -c and display them with a custom format using %m , where %Z is the average cost per match:
ug -c -Z+3 -wi --format='%F%Z:%m%~' --sort=best 'foobar'
Note: options -c and -l do not report a meaningful %Z value in the --format output, because %Z is the edit distance cost of a single match.
？返回目录
--hidden, -.
Search hidden files and directories.
To recursively search the working directory, including hidden files and directories, for the word login in shell scripts:
ug -. -tShell 'login'
？返回目录
--filter=COMMANDS
Filter files through the specified COMMANDS first before searching.
COMMANDS is a comma-separated list of `exts:command [option ...]',
where `exts' is a comma-separated list of filename extensions and
`command' is a filter utility. Files matching one of `exts' are
filtered. When `exts' is a `*', all files are filtered. One or
more `option' separated by spacing may be specified, which are
passed verbatim to the command. A `%' as `option' expands into the
pathname to search. For example, --filter='pdf:pdftotext % -'
searches PDF files. The `%' expands into a `-' when searching
standard input. When a `%' is not specified, a filter utility
should read from standard input and write to standard output.
Option --label=.ext may be used to specify extension `ext' when
searching standard input. This option may be repeated.
--filter-magic-label=LABEL:MAGIC
Associate LABEL with files whose signature "magic bytes" match the
MAGIC regex pattern. Only files that have no filename extension
are labeled, unless +LABEL is specified. When LABEL matches an
extension specified in --filter=COMMANDS, the corresponding command
is invoked. This option may be repeated.
The --filter option associates one or more filter utilities with specific filename extensions. A filter utility is selected based on the filename extension and executed by forking a process: the utility's standard input reads the open input file and the utility's standard output is searched. When a % is specified as an option to the utility, the % is expanded to the pathname of the file to open and read by the utility.
When a specified utility is not found on the system, an error message is displayed. When a utility fails to produce output, eg when the specified options for the utility are invalid, the search is silently skipped.
Filtering does not apply to files stored in archives and compressed files. A filter is usually applied to a file that is physically stored in the file system. Archived files are not physically stored.
Common filter utilities are cat (concat, pass through), head (select first lines or bytes) tr (translate), iconv and uconv (convert), and more advanced utilities, such as:
pdftotext to convert pdf to textantiword to convert doc to textpandoc to convert .docx, .epub, and other document formatsexiftool to read meta information embedded in image and video media formats.soffice to convert office documentscsvkit to convert spreadsheetsopenssl to convert certificates and key files to text and other formats The ugrep+ and ug+ commands use the pdftotext , antiword , pandoc and exiftool filters, when installed, to search pdfs, documents, e-books, and image metadata.
Also decompressors may be used as filter utilities, such as unzip , gunzip , bunzip2 , unlzma , unxz , lzop and 7z that decompress files to standard output when option --stdout is specified.例如：
ug --filter='lzo:lzop -d --stdout -' ...
ug --filter='gz:gunzip -d --stdout -' ...
ug --filter='7z:7z x -so %' ...
The --filter='lzo:lzop -d --stdout -' option decompresses files with extension lzo to standard output with --stdout with the compressed stream being read from standard input with - . The --filter='7z:7z x -so -si option decompresses files with extension 7z to standard output -so while reading standard input -si with the compressed file contents.
Note that ugrep option -z is typically faster to search compressed files compared to --filter .
The --filter option may also be used to run a user-defined shell script to filter files. For example, to invoke an action depending on the filename extension of the % argument. Another use case is to pass a file to more than one filter, which can be accomplished with a shell script containing the line tool1 $1; tool2 $1 . This filters the file argument $1 with tool1 followed by tool2 to produce combined output to search for pattern matches. Likewise, we can use a script with the line tool1 $1 | tool2 to stack two filters tool1 and tool2 .
The --filter option may also be used as a predicate to skip certain files from the search. As the most basic example, consider the false utility that exits with a nonzero exit code without reading input or producing output. Therefore, --filter='swp: false' skips all .swp files from recursive searches. The same can be done more efficiently with -O^swp . However, the --filter option could invoke a script that determines if the filename passed as a % argument meets certain constraints. If the constraint is met the script copies standard input to standard output with cat . If not, the script exits.
Warning: option --filter should not be used with utilities that modify files. Otherwise searches may be unpredicatable. In the worst case files may be lost, for example when the specified utility replaces or deletes the file passed to the command with --filter option % .
To recursively search files including PDF files in the working directory without recursing into subdirectories (with -1 ), for matches of drink me using the pdftotext filter to convert PDF to text without preserving page breaks:
ug -r -1 --filter='pdf:pdftotext -nopgbrk % -' 'drink me'
To recursively search text files for eat me while converting non-printable characters in .txt and .md files using the cat -v filter:
ug -r -ttext --filter='txt,md:cat -v' 'eat me'
The same, but specifying the .txt and .md filters separately:
ug -r -ttext --filter='txt:cat -v, md:cat -v' 'eat me'
To search the first 8K of a text file:
ug --filter='txt:head -c 8192' 'eat me' wonderland.txt
To recursively search and list the files that contain the word Alice , including .docx and .epub documents using the pandoc filter:
ug -rl -w --filter='docx,epub:pandoc --wrap=preserve -t plain % -o -' 'Alice'
Important: the pandoc utility requires an input file and will not read standard input. Option % expands into the full pathname of the file to search. The output format specified is markdown , which is close enough to text to be searched.
To recursively search and list the files that contain the word Alice , including .odt, .doc, .docx, .rtf, .xls, .xlsx, .ppt, .pptx documents using the soffice filter:
ug -rl -w --filter='odt,doc,docx,rtf,xls,xlsx,ppt,pptx:soffice --headless --cat %' 'Alice'
Important: the soffice utility will not output any text when one or more LibreOffice GUIs are open. Make sure to quit all LibreOffice apps first. This looks like a bug, but the LibreOffice developers do not appear to fix this any time soon (unless perhaps more people complain?). You can work around this problem by specifying a specific user profile for soffice with the following semi-documented argument passed to soffice : -env:UserInstallation=file:///home/user/.libreoffice-alt .
To recursively search and display rows of .csv, .xls, and .xlsx spreadsheets that contain 10/6 using the in2csv filter of csvkit:
ug -r -Ocsv,xls,xlsx --filter='xls,xlsx:in2csv %' '10/6'
To search .docx, .xlsx, and .pptx files converted to XML for a match with 10/6 using unzip as a filter:
ug -lr -Odocx,xlsx,pptx --filter='docx,xlsx,pptx:unzip -p %' '10/6'
Important: unzipping docx, xlxs, pptx files produces extensive XML output containing meta information and binary data such as images. By contrast, ugrep option -z with -Oxml selects the XML components only:
ug -z -lr -Odocx,xlsx,pptx,xml '10/6'
Note: docx, xlsx, and pptx are zip files containing multiple components. When selecting the XML components with option -Oxml in docx, xlsx, and pptx documents, we should also specify -Odocx,xlsx,pptx to search these type of files, otherwise these files will be ignored.
To recurssively search X509 certificate files for lines with Not After (eg to find expired certificates), using openssl as a filter:
ug -r 'Not After' -Ocer,der,pem --filter='pem:openssl x509 -text,cer,crt,der:openssl x509 -text -inform der'
Note that openssl warning messages are displayed on standard error. If a file cannot be converted it is probably in a different format. This can be resolved by writing a shell script that executes openssl with options based on the file content. Then write a script with ugrep --filter .
To search PNG files by filename extension with -tpng using exiftool :
ug -r -i 'copyright' -tpng --filter='*:exiftool %'
Same, but also include files matching PNG "magic bytes" with -tPng and --filter-magic-label='+png:x89pngx0dx0ax1ax0a' to select the png filter:
ug -r -i 'copyright' -tPng --filter='png:exiftool %' --filter-magic-label='+png:x89pngx0dx0ax1ax0a'
Note that +png overrides any filename extension match for --filter . Otherwise, without a + , the filename extension, when present, takes priority over labelled magic patterns to invoke the corresponding filter command. The LABEL used with --filter-magic-label and --filter has no specific meaning; any name or string that does not contain a : or , may be used.
？返回目录
--hexdump[=[1-8][a][bch][A[NUM]][B[NUM]][C[NUM]]]
Output matches in 1 to 8 columns of 8 hexadecimal octets. The
default is 2 columns or 16 octets per line. Argument `a' outputs a
`*' for all hex lines that are identical to the previous hex line,
`b' removes all space breaks, `c' removes the character column, `h'
removes hex spacing, `A' includes up to NUM hex lines after a
match, `B' includes up to NUM hex lines before a match and `C'
includes up to NUM hex lines before and after a match. Arguments
`A', `B' and `C' are the same as options -A, -B and -C when used
with --hexdump. See also options -U, -W and -X.
-U, --ascii, --binary
Disables Unicode matching for binary file matching, forcing PATTERN
to match bytes, not Unicode characters. For example, -U 'xa3'
matches byte A3 (hex) instead of the Unicode code point U+00A3
represented by the UTF-8 sequence C2 A3. See also --dotall.
-W, --with-hex
Output binary matches in hexadecimal, leaving text matches alone.
This option is equivalent to the --binary-files=with-hex option.
To omit the matching line from the hex output, use both options -W
and --hexdump. See also options -U.
-X, --hex
Output matches and matching lines in hexadecimal. This option is
equivalent to the --binary-files=hex option. To omit the matching
line from the hex output use option --hexdump. See also option -U.
--dotall
Dot `.' in regular expressions matches anything, including newline.
Note that `.*' matches all input and should not be used.
Note that --hexdump differs from -X by omitting the matching line from the hex output, showing only the matching pattern using a minimal number of hex lines. Additional match context hex lines are output with the -ABC context options or with --hexdump=C3 to output 3 hex lines as context, for example.
To search a file for ASCII words, displaying text lines as usual while binary content is shown in hex with -U and -W :
ug -UW 'w+' myfile
To hexdump an entire file as a match with -X :
ug -X '' myfile
To hexdump an entire file with -X , displaying line numbers and byte offsets with -nb (here with -y to display all line numbers):
ug -Xynb '' myfile
To hexdump lines containing one or more in a (binary) file using a non-Unicode pattern with -U and -X :
ug -UX 'x00+' myfile
Same, but hexdump the entire file as context with -y (note that this line-based option does not permit matching patterns with newlines):
ug -UX -y 'x00+' myfile
Same, compacted to 32 bytes per line without the character column:
ug -UX -y 'x00+' myfile
To match the binary pattern A3..A3. (hex) in a binary file without Unicode pattern matching (which would otherwise match xaf as a Unicode character U+00A3 with UTF-8 byte sequence C2 A3) and display the results in compact hex with --hexdump with pager:
ug --pager --hexdump -U 'xa3[x00-xff]{2}xa3[x00-xff]' a.out
Same, but using option --dotall to let . match any byte, including newline that is not matched by dot (the default as required by grep):
ug --dotall --pager --hexdump -U 'xa3.{2}xa3.' a.out
To list all files containing a RPM signature, located in the rpm directory and recursively below (see for example list of file signatures):
ug -RlU 'Axedxabxeexdb' rpm
？返回目录
-I Ignore matches in binary files. This option is equivalent to the
--binary-files=without-match option.
To recursively search without following symlinks and ignoring binary files:
ug -rl -I 'xyz'
To ignore specific binary files with extensions such as .exe, .bin, .out, .a, use --exclude or --exclude-from :
ug -rl --exclude-from=ignore_binaries 'xyz'
where ignore_binaries is a file containing a glob on each line to ignore matching files, eg *.exe , *.bin , *.out , *.a . Because the command is quite long to type, an alias for this is recommended, for example ugs (ugrep source):
alias ugs="ugrep --exclude-from=~/ignore_binaries"
ugs -rl 'xyz'
？返回目录
--ignore-files[=FILE]
Ignore files and directories matching the globs in each FILE that
is encountered in recursive searches. The default FILE is
`.gitignore'. Matching files and directories located in the
directory of the FILE and in subdirectories below are ignored.
Globbing syntax is the same as the --exclude-from=FILE gitignore
syntax, but files and directories are excluded instead of only
files. Directories are specifically excluded when the glob ends in
a `/'. Files and directories explicitly specified as command line
arguments are never ignored. This option may be repeated to
specify additional files.
Option --ignore-files looks for .gitignore , or the specified FILE , in recursive searches. When .gitignore , or the specified FILE , is found while traversing directory tree branches down, the .gitignore file is used to temporarily extend the previous exclusions with the additional globs in .gitignore to apply the combined exclusions to the directory tree rooted at the .gitignore location. Use --stats to show the selection criteria applied to the search results and the locations of each FILE found. To avoid confusion, files and directories specified as command-line arguments to ugrep are never ignored.
Note that exclude glob patterns take priority over include glob patterns when specified with command line options. By contrast, negated glob patterns specified with ! in --ignore-files files take priority. This effectively overrides the exclusions and resolves conflicts in favor of listing matching files that are explicitly specified as exceptions and should be included in the search.
See also Using gitignore-style globs to select directories and files to search.
To recursively search without following symlinks, while ignoring files and directories ignored by .gitignore (when present), use option --ignore-files . Note that -r is the default when no FILE arguments are specified, we use it here to make the examples easier to follow.
ug -rl --ignore-files 'xyz'
Same, but includes hidden files with -. rather than ignoring them:
ug -rl. --ignore-files 'xyz'
To recursively list all files that are not ignored by .gitignore (when present) with --ignore-files :
ug -rl --ignore-files ''
Same, but list shell scripts that are not ignored by .gitignore, when present:
ug -rl -tShell '' --ignore-files
To recursively list all files that are not ignored by .gitignore and are also not excluded by .git/info/exclude :
ug -rl '' --ignore-files --exclude-from=.git/info/exclude
Same, but by creating a symlink to .git/info/exclude to make the exclusions implicit:
ln -s .git/info/exclude .ignore
ug -rl '' --ignore-files --ignore-files=.ignore
？返回目录
-g GLOBS, --glob=GLOBS
Search only files whose name matches the specified comma-separated
list of GLOBS, same as --include='glob' for each `glob' in GLOBS.
When a `glob' is preceded by a `!' or a `^', skip files whose name
matches `glob', same as --exclude='glob'. When `glob' contains a
`/', full pathnames are matched. Otherwise basenames are matched.
When `glob' ends with a `/', directories are matched, same as
--include-dir='glob' and --exclude-dir='glob'. A leading `/'
matches the working directory. This option may be repeated and may
be combined with options -M, -O and -t to expand searches. See
`ugrep --help globs' and `man ugrep' section GLOBBING for details.
--exclude=GLOB
Skip files whose name matches GLOB using wildcard matching, same as
-g ^GLOB. GLOB can use **, *, ?, and [...] as wildcards, and \ to
quote a wildcard or backslash character literally. When GLOB
contains a `/', full pathnames are matched. Otherwise basenames
are matched. When GLOB ends with a `/', directories are excluded
as if --exclude-dir is specified. Otherwise files are excluded.
Note that --exclude patterns take priority over --include patterns.
GLOB should be quoted to prevent shell globbing. This option may
be repeated.
--exclude-dir=GLOB
Exclude directories whose name matches GLOB from recursive
searches, same as -g ^GLOB/. GLOB can use **, *, ?, and [...] as
wildcards, and \ to quote a wildcard or backslash character
literally. When GLOB contains a `/', full pathnames are matched.
Otherwise basenames are matched. Note that --exclude-dir patterns
take priority over --include-dir patterns. GLOB should be quoted
to prevent shell globbing. This option may be repeated.
--exclude-from=FILE
Read the globs from FILE and skip files and directories whose name
matches one or more globs. A glob can use **, *, ?, and [...] as
wildcards, and to quote a wildcard or backslash character
literally. When a glob contains a `/', full pathnames are matched.
Otherwise basenames are matched. When a glob ends with a `/',
directories are excluded as if --exclude-dir is specified.
Otherwise files are excluded. A glob starting with a `!' overrides
previously-specified exclusions by including matching files. Lines
starting with a `#' and empty lines in FILE are ignored. When FILE
is a `-', standard input is read. This option may be repeated.
--ignore-files[=FILE]
Ignore files and directories matching the globs in each FILE that
is encountered in recursive searches. The default FILE is
`.gitignore'. Matching files and directories located in the
directory of the FILE and in subdirectories below are ignored.
Globbing syntax is the same as the --exclude-from=FILE gitignore
syntax, but files and directories are excluded instead of only
files. Directories are specifically excluded when the glob ends in
a `/'. Files and directories explicitly specified as command line
arguments are never ignored. This option may be repeated to
specify additional files.
--include=GLOB
Search only files whose name matches GLOB using wildcard matching,
same as -g GLOB. GLOB can use **, *, ?, and [...] as wildcards,
and \ to quote a wildcard or backslash character literally. When
GLOB contains a `/', full pathnames are matched. Otherwise
basenames are matched. When GLOB ends with a `/', directories are
included as if --include-dir is specified. Otherwise files are
included. Note that --exclude patterns take priority over
--include patterns. GLOB should be quoted to prevent shell
globbing. This option may be repeated.
--include-dir=GLOB
Only directories whose name matches GLOB are included in recursive
searches, same as -g GLOB/. GLOB can use **, *, ?, and [...] as
wildcards, and \ to quote a wildcard or backslash character
literally. When GLOB contains a `/', full pathnames are matched.
Otherwise basenames are matched. Note that --exclude-dir patterns
take priority over --include-dir patterns. GLOB should be quoted
to prevent shell globbing. This option may be repeated.
--include-from=FILE
Read the globs from FILE and search only files and directories
whose name matches one or more globs. A glob can use **, *, ?, and
[...] as wildcards, and to quote a wildcard or backslash
character literally. When a glob contains a `/', full pathnames
are matched. Otherwise basenames are matched. When a glob ends
with a `/', directories are included as if --include-dir is
specified. Otherwise files are included. A glob starting with a
`!' overrides previously-specified inclusions by excluding matching
files. Lines starting with a `#' and empty lines in FILE are
ignored. When FILE is a `-', standard input is read. This option
may be repeated.
-O EXTENSIONS, --file-extension=EXTENSIONS
Search only files whose filename extensions match the specified
comma-separated list of EXTENSIONS, same as --include='*.ext' for
each `ext' in EXTENSIONS. When `ext' is preceded by a `!' or a
`^', skip files whose filename extensions matches `ext', same as
--exclude='*.ext'. This option may be repeated and may be combined
with options -g, -M and -t to expand the recursive search.
--stats
Output statistics on the number of files and directories searched,
and the inclusion and exclusion constraints applied.
See also Including or excluding mounted file systems from searches.
Gitignore-style glob syntax and conventions:
| 图案 | 比赛 |
|---|---|
* | anything except / |
? | any one character except / |
[abc-e] | one character a , b , c , d , e |
[^abc-e] | one character not a , b , c , d , e , / |
[!abc-e] | one character not a , b , c , d , e , / |
/ | when used at the start of a glob, matches working directory |
**/ | zero or more directories |
/** | when at the end of a glob, matches everything after the / |
? | 一个? or any other character specified after the backslash |
When a glob pattern contains a path separator / , the full pathname is matched. Otherwise the basename of a file or directory is matched in recursive searches. For example, *.h matches foo.h and bar/foo.h . bar/*.h matches bar/foo.h but not foo.h and not bar/bar/foo.h .
When a glob pattern begins with a / , files and directories are matched at the working directory, not recursively. For example, use a leading / to force /*.h to match foo.h but not bar/foo.h .
When a glob pattern ends with a / , directories are matched instead of files, same as --include-dir .
When a glob starts with a ! as specified with -g!GLOB , or specified in a FILE with --include-from=FILE or --exclude-from=FILE , it is negated.
To view a list of inclusions and exclusions that were applied to a search, use option --stats .
To list only readable files with names starting with foo in the working directory, that contain xyz , without producing warning messages with -s and -l :
ug -sl 'xyz' foo*
The same, but using deep recursion with inclusion constraints (note that -g'/foo* is the same as --include='/foo*' and -g'/foo*/' is the same as --include-dir='/foo*' , ie immediate subdirectories matching /foo* only):
ug -rl 'xyz' -g'/foo*' -g'/foo*/'
Note that -r is the default, we use it here to make the examples easier to follow.
To exclude directory bak located in the working directory:
ug -rl 'xyz' -g'^/bak/'
To exclude all directoies bak at any directory level deep:
ug -rl 'xyz' -g'^bak/'
To only list files in the working directory and its subdirectory doc , that contain xyz (note that -g'/doc/' is the same as --include-dir='/doc' , ie immediate subdirectory doc only):
ug -rl 'xyz' -g'/doc/'
To only list files that are on a subdirectory path doc that includes subdirectory html anywhere, that contain xyz :
ug -rl 'xyz' -g'doc/**/html/'
To only list files in the working directory and in the subdirectories doc and doc/latest but not below, that contain xyz :
ug -rl 'xyz' -g'/doc/' -g'/doc/latest/'
To recursively list .cpp files in the working directory and any subdirectory at any depth, that contain xyz :
ug -rl 'xyz' -g'*.cpp'
The same, but using a .gitignore-style glob that matches pathnames (globs with / ) instead of matching basenames (globs without / ) in the recursive search:
ug -rl 'xyz' -g'**/*.cpp'
Same, but using option -Ocpp to match file name extensions:
ug -rl -Ocpp 'xyz'
To recursively list all files in the working directory and below that are not ignored by a specific .gitignore file:
ug -rl '' --exclude-from=.gitignore
To recursively list all files in the working directory and below that are not ignored by one or more .gitignore files, when any are present:
ug -rl '' --ignore-files
？返回目录
--exclude-fs=MOUNTS
Exclude file systems specified by MOUNTS from recursive searches.
MOUNTS is a comma-separated list of mount points or pathnames to
directories. When MOUNTS is not specified, only descends into the
file systems associated with the specified file and directory
search targets, i.e. excludes all other file systems. Note that
--exclude-fs=MOUNTS take priority over --include-fs=MOUNTS. This
option may be repeated.
--include-fs=MOUNTS
Only file systems specified by MOUNTS are included in recursive
searches. MOUNTS is a comma-separated list of mount points or
pathnames to directories. When MOUNTS is not specified, restricts
recursive searches to the file system of the working directory,
same as --include-fs=. (dot). Note that --exclude-fs=MOUNTS take
priority over --include-fs=MOUNTS. This option may be repeated.
These options control recursive searches across file systems by comparing device numbers. Mounted devices and symbolic links to files and directories located on mounted file systems may be included or excluded from recursive searches by specifying a mount point or a pathname of any directory on the file system to specify the applicable file system.
Note that a list of mounted file systems is typically stored in /etc/mtab .
To restrict recursive searches to the file system(s) of the search targets only, without crossing into other file systems (similar to find option -x ):
ug -rl --exclude-fs 'xyz' /sys /var
To restrict recursive searches to the file system of the working directory only, without crossing into other file systems:
ug -l --include-fs 'xyz'
In fact, for this case we can use --exclude-fs because we search the working directory as the target and we want to exclude all other file systems:
ug -l --exclude-fs 'xyz'
To exclude the file systems mounted at /dev and /proc from recursive searches:
ug -l --exclude-fs=/dev,/proc 'xyz'
To only include the file system associated with drive d: in recursive searches:
ug -l --include-fs=d:/ 'xyz'
To exclude fuse and tmpfs type file systems from recursive searches:
exfs=`ugrep -w -e fuse -e tmpfs /etc/mtab | ugrep -P '^S+ (S+)' --format='%,%1'`
ug -l --exclude-fs="$exfs" 'xyz'
？返回目录
-c, --count
Only a count of selected lines is written to standard output.
If -o or -u is specified, counts the number of patterns matched.
If -v is specified, counts the number of non-matching lines. If
-m1, (with a comma or --min-count=1) is specified, counts only
matching files without outputting zero matches.
To count the number of lines in a file:
ug -c '' myfile.txt
To count the number of lines with TODO :
ug -c -w 'TODO' myfile.cpp
To count the total number of TODO in a file, use -c and -o :
ug -co -w 'TODO' myfile.cpp
To count the number of ASCII words in a file:
ug -co '[[:word:]]+' myfile.txt
To count the number of ASCII and Unicode words in a file:
ug -co 'w+' myfile.txt
To count the number of Unicode characters in a file:
ug -co 'p{Unicode}' myfile.txt
To count the number of zero bytes in a file:
ug -UX -co 'x00' image.jpg
？返回目录
-b, --byte-offset
The offset in bytes of a matched line is displayed in front of the
respective matched line. When used with option -u, displays the
offset in bytes of each pattern matched. Byte offsets are exact
for ASCII, UTF-8, and raw binary input. Otherwise, the byte offset
in the UTF-8 converted input is displayed.
-H, --with-filename
Always print the filename with output lines. This is the default
when there is more than one file to search.
-k, --column-number
The column number of a matched pattern is displayed in front of the
respective matched line, starting at column 1. Tabs are expanded
when columns are counted, see option --tabs.
-n, --line-number
Each output line is preceded by its relative line number in the
file, starting at line 1. The line number counter is reset for
each file processed.
-T, --initial-tab
Add a tab space to separate the file name, line number, column
number, and byte offset with the matched line.
To display the file name -H , line -n , and column -k numbers of matches in myfile.cpp , with spaces and tabs to space the columns apart with -T :
ug -THnk 'main' myfile.cpp
To display the line with -n of word main in myfile.cpp :
ug -nw 'main' myfile.cpp
To display the entire file myfile.cpp with line -n numbers:
ug -n '' myfile.cpp
To recursively search for C++ files with main , showing the line and column numbers of matches with -n and -k :
ug -r -nk -tc++ 'main'
To display the byte offset of matches with -b :
ug -r -b -tc++ 'main'
To display the line and column numbers of matches in XML with --xml :
ug -r -nk --xml -tc++ 'main'
？返回目录
--color[=WHEN], --colour[=WHEN]
Mark up the matching text with the expression stored in the
GREP_COLOR or GREP_COLORS environment variable. The possible
values of WHEN can be `never', `always', or `auto', where `auto'
marks up matches only when output on a terminal. The default is
`auto'.
--colors=COLORS, --colours=COLORS
Use COLORS to mark up text. COLORS is a colon-separated list of
one or more parameters `sl=' (selected line), `cx=' (context line),
`mt=' (matched text), `ms=' (match selected), `mc=' (match
context), `fn=' (file name), `ln=' (line number), `cn=' (column
number), `bn=' (byte offset), `se=' (separator), `qp=' (TUI
prompt), `qe=' (TUI errors), `qr=' (TUI regex), `qm=' (TUI regex
meta characters), `ql=' (TUI regex lists and literals), `qb=' (TUI
regex braces). Parameter values are ANSI SGR color codes or `k'
(black), `r' (red), `g' (green), `y' (yellow), `b' (blue), `m'
(magenta), `c' (cyan), `w' (white), or leave empty for no color.
Upper case specifies background colors. A `+' qualifies a color as
bright. A foreground and a background color may be combined with
font properties `n' (normal), `f' (faint), `h' (highlight), `i'
(invert), `u' (underline). Parameter `hl' enables file name
hyperlinks. Parameter `rv' reverses the `sl=' and `cx=' parameters
when option -v is specified. Selectively overrides GREP_COLORS.
Legacy grep single parameter codes may be specified, for example
--colors='7;32' or --colors=ig to set ms (match selected).
--tag[=TAG[,END]]
Disables colors to mark up matches with TAG. END marks the end of
a match if specified, otherwise TAG. The default is `___'.
--pager[=COMMAND]
When output is sent to the terminal, uses COMMAND to page through
the output. COMMAND defaults to environment variable PAGER when
defined or `less'. Enables --heading and --line-buffered.
--pretty[=WHEN]
When output is sent to a terminal, enables --color, --heading, -n,
--sort, --tree and -T when not explicitly disabled. WHEN can be
`never', `always', or `auto'. The default is `auto'.
--tree, -^
Output directories with matching files in a tree-like format for
option -c or --count, -l or --files-with-matches, -L or
--files-without-match. This option is enabled by --pretty when the
output is sent to a terminal.
To change the color palette, set the GREP_COLORS environment variable or use --colors=COLORS . The value is a colon-separated list of ANSI SGR parameters that defaults to cx=33:mt=1;31:fn=1;35:ln=1;32:cn=1;32:bn=1;32:se=36 :
| 参数 | 结果 |
|---|---|
sl= | selected lines |
cx= | context lines |
rv | Swaps the sl= and cx= capabilities when -v is specified |
mt= | matching text in any matching line |
ms= | matching text in a selected line. The substring mt= by default |
mc= | matching text in a context line. The substring mt= by default |
fn= | file names |
ln= | line numbers |
cn= | 列号 |
bn= | byte offsets |
se= | separators |
hl | hyperlink file names, same as --hyperlink |
qp= | TUI prompt |
qe= | TUI errors |
qr= | TUI regex |
qm= | TUI regex meta characters |
ql= | TUI regex lists and literals |
qb= | TUI regex braces |
Multiple SGR codes may be specified for a single parameter when separated by a semicolon, eg mt=1;31 specifies bright red. The following SGR codes are available on most color terminals:
| 代码 | c | 影响 | 代码 | c | 影响 |
|---|---|---|---|---|---|
| 0 | n | normal font and color | 2 | f | faint (not widely supported) |
| 1 | 小时 | highlighted bold font | 21 | H | highlighted bold off |
| 4 | 你 | 强调 | 24 | U | underline off |
| 7 | 我 | invert video | 27 号 | 我 | invert off |
| 30 | k | 黑色文字 | 90 | +k | bright gray text |
| 31 | r | red text | 91 | +r | bright red text |
| 32 | 克 | 绿色文本 | 92 | +g | bright green text |
| 33 | y | yellow text | 93 | +y | bright yellow text |
| 34 | 乙 | blue text | 94 | +b | bright blue text |
| 35 | 米 | magenta text | 95 | +米 | bright magenta text |
| 36 | c | cyan text | 96 | +c | bright cyan text |
| 37 | w | 白色文字 | 97 | +w | bright white text |
| 40 | K | 黑色背景 | 100 | +K | bright gray background |
| 41 | 右 | 深红色背景 | 101 | +R | 明亮的红色背景 |
| 42 | G | 深绿色背景 | 102 | +G | bright green background |
| 43 | 是 | dark yellow backgrounda | 103 | +Y | bright yellow background |
| 44 | 乙 | dark blue background | 104 | +B | bright blue background |
| 45 | 中号 | dark magenta background | 105 | +M | bright magenta background |
| 46 | C | dark cyan background | 106 | +C | bright cyan background |
| 47 | 瓦 | dark white background | 107 | +W | bright white background |
See Wikipedia ANSI escape code - SGR parameters
For quick and easy color specification, the corresponding single-letter color names may be used in place of numeric SGR codes and semicolons are not required to separate color names. Color names and numeric codes may be mixed.
For example, to display matches in underlined bright green on bright selected lines, aiding in visualizing white space in matches and file names:
export GREP_COLORS='sl=1:cx=33:ms=1;4;32;100:mc=1;4;32:fn=1;32;100:ln=1;32:cn=1;32:bn=1;32:se=36'
The same, but with single-letter color names:
export GREP_COLORS='sl=h:cx=y:ms=hug+K:mc=hug:fn=hg+K:ln=hg:cn=hg:bn=hg:se=c'
Another color scheme that works well:
export GREP_COLORS='cx=hb:ms=hiy:mc=hic:fn=hi+y+K:ln=hg:cn=hg:bn=hg:se='
Modern Windows command interpreters support ANSI escape codes. Named or numeric colors can be set with SET GREP_COLORS , for example:
SET GREP_COLORS=sl=1;37:cx=33:mt=1;31:fn=1;35:ln=1;32:cn=1;32:bn=1;32:se=36
To disable colors on Windows:
SET GREP_COLORS=""
Color intensities may differ per platform and per terminal program used, which affects readability.
Option -y outputs every line of input, including non-matching lines as context. The use of color helps distinguish matches from non-matching context.
To copy silver searcher's color palette:
export GREP_COLORS='mt=30;43:fn=1;32:ln=1;33:cn=1;33:bn=1;33'
To produce color-highlighted results ( --color is redundance since it is the default):
ug --color -r -n -k -tc++ 'FIXME.*'
To page through the results with pager ( less -R by default):
ug --pager -r -n -k -tc++ 'FIXME'
To display a hexdump of a zip file itself (ie without decompressing), with color-highlighted matches of the zip magic bytes PKx03x04 ( --color is redundant since it is the default):
ug --color -y -UX 'PKx03x04' some.zip
To use predefined patterns to list all #include and #define in C++ files:
ug --pretty -r -n -tc++ -f c++/includes -f c++/defines
Same, but overriding the color of matches as inverted yellow (reverse video) and headings with yellow on blue using --pretty :
ug --pretty --colors="ms=yi:fn=hyB" -r -n -tc++ -f c++/includes -f c++/defines
To list all #define FOO... macros in C++ files, color-highlighted:
ug --color=always -r -n -tc++ -f c++/defines | ug 'FOO.*'
Same, but restricted to .cpp files only:
ug --color=always -r -n -Ocpp -f c++/defines | ug 'FOO.*'
To search tarballs for matching names of PDF files (assuming bash is our shell):
for tb in *.tar *.tar.gz *.tgz; do echo "$tb"; tar tfz "$tb" | ugrep '.*.pdf$'; done
？返回目录
--cpp Output file matches in C++. See also options --format and -u.
--csv Output file matches in CSV. If -H, -n, -k, or -b is specified,
additional values are output. See also options --format and -u.
--json Output file matches in JSON. If -H, -n, -k, or -b is specified,
additional values are output. See also options --format and -u.
--xml Output file matches in XML. If -H, -n, -k, or -b is specified,
additional values are output. See also options --format and -u.
To recursively search for lines with TODO and display C++ file matches in JSON with line number properties:
ug -tc++ -n --json 'TODO'
To recursively search for lines with TODO and display C++ file matches in XML with line and column number attributes:
ug -tc++ -nk --xml 'TODO'
To recursively search for lines with TODO and display C++ file matches in CSV format with file pathname, line number, and column number fields:
ug -tc++ --csv -Hnk 'TODO'
To extract a table from an HTML file and put it in C/C++ source code using -o :
ug -o --cpp '<tr>.*</tr>' index.html > table.cpp
？返回目录
--format=FORMAT
Output FORMAT-formatted matches. For example --format='%f:%n:%O%~'
outputs matching lines `%O' with filename `%f` and line number `%n'
followed by a newline `%~'. If -P is specified, FORMAT may include
`%1' to `%9', `%[NUM]#' and `%[NAME]#' to output group captures. A
`%%' outputs `%'. See `ugrep --help format' and `man ugrep'
section FORMAT for details. When option -o is specified, option -u
is also enabled. Context options -A, -B, -C and -y are ignored.
-P, --perl-regexp
Interpret PATTERN as a Perl regular expression.
Use option -P to use group captures and backreferences. Capturing groups in regex patterns are parenthesized expressions (pattern) . The first group is referenced in FORMAT by %1 , the second by %2 and so on. Named captures are of the form (?<NAME>pattern) and are referenced in FORMAT by %[NAME]# .
The following output formatting options may be used. The FORMAT string % -fields are listed in a table further below:
| 选项 | 结果 |
|---|---|
--format-begin=FORMAT | FORMAT beginning the search |
--format-open=FORMAT | FORMAT opening a file and a match was found |
--format=FORMAT | FORMAT for each match in a file |
--format-close=FORMAT | FORMAT closing a file and a match was found |
--format-end=FORMAT | FORMAT ending the search |
The following tables show the formatting options corresponding to --csv , --json , and --xml .
--csv| 选项 | format string (within quotes) |
|---|---|
--format-open | '%+' |
--format | '%[,]$%H%N%K%B%V%~%u' |
--json| 选项 | format string (within quotes) |
|---|---|
--format-begin | '[' |
--format-open | '%,%~ {%~ %[,%~ ]$%["file": ]H"matches": [' |
--format | '%,%~ { %[, ]$%["line": ]N%["column": ]K%["offset": ]B"match": %J }%u' |
--format-close | '%~ ]%~ }' |
--format-end | '%~]%~' |
--xml| 选项 | format string (within quotes) |
|---|---|
--format-begin | '<grep>%~' |
--format-open | ' <file%["]$%[ name="]I>%~' |
--format | ' <match%["]$%[ line="]N%[ column="]K%[ offset="]B>%X</match>%~%u' |
--format-close | ' </file>%~' |
--format-end | '</grep>%~' |
--only-line-number| 选项 | format string (within quotes) |
|---|---|
--format-open | '%+' |
--format | '%F%n%s%K%B%~%u' |
The following fields may be used in the FORMAT string:
| 场地 | 输出 |
|---|---|
%% | the percentage sign |
%~ | a newline (LF or CRLF in Windows) |
%F | if option -H is used: the file pathname and separator |
%[TEXT]F | if option -H is used: TEXT , the file pathname and separator |
%f | the file pathname |
%a | the file basename without directory path |
%p | the directory path to the file |
%z | the pathname in a (compressed) archive, without { and } |
%H | if option -H is used: the quoted pathname and separator, " and \ replace " and |
%+ | if option -+ or --heading is used: %F and a newline character, suppress all %F and %H afterward |
%[TEXT]H | if option -H is used: TEXT , the quoted pathname and separator, " and \ replace " and |
%h | the quoted file pathname, " and \ replace " and |
%I | if option -H is used: the pathname in XML and separator |
%[TEXT]I | if option -H is used: TEXT , the pathname as XML and separator |
%i | the file pathnames as XML |
%N | if option -n is used: the line number and separator |
%[TEXT]N | if option -n is used: TEXT , the line number and separator |
%n | the line number of the match |
%l | the last line number of the match (multi-line matching) |
%L | the number of lines matched (multi-line matching) |
%K | if option -k is used: the column number and separator |
%[TEXT]K | if option -k is used: TEXT , the column number and separator |
%k | the column number of the match |
%A | byte range (offset and end) of a match in hex |
%B | if option -b is used: the byte offset and separator |
%[TEXT]B | if option -b is used: TEXT , the byte offset and separator |
%b | the byte offset of the match |
%T | if option -T is used: TEXT and a tab character |
%[TEXT]T | if option -T is used: TEXT and a tab character |
%t | a tab character |
%[SEP]$ | set field separator to SEP for the rest of the format fields |
%[TEXT]< | if the first match: TEXT |
%[TEXT]> | if not the first match: TEXT |
%, | if not the first match: a comma, same as %[,]> |
%: | if not the first match: a colon, same as %[:]> |
%; | if not the first match: a semicolon, same as %[;]> |
%│ | if not the first match: a vertical bar, same as %[│]> |
%S | if not the first match: separator, see also %[SEP]$ |
%[TEXT]S | if not the first match: TEXT and separator, see also %[SEP]$ |
%s | the separator, see also %[TEXT]S and %[SEP]$ |
%R | if option --break or --heading is used: a newline |
%m | the number of matches, sequential (or number of matching files with --format-end ) |
%M | the number of matching lines (or number of matching files with --format-end ) |
%O | the matching line is output as is (a raw string of bytes) |
%o | the match is output as is (a raw string of bytes) |
%Q | the matching line as a quoted string, " and \ replace " and |
%q | the match as a quoted string, " and \ replace " and |
%C | the matching line formatted as a quoted C/C++ string |
%c | the match formatted as a quoted C/C++ string |
%J | the matching line formatted as a quoted JSON string |
%j | the match formatted as a quoted JSON string |
%V | the matching line formatted as a quoted CSV string |
%v | the match formatted as a quoted CSV string |
%X | the matching line formatted as XML character data |
%x | the match formatted as XML character data |
%Y | the matching line formatted in hex |
%y | the match formatted in hex |
%A | byte range of the match in hex |
%w | the width of the match, counting (wide) characters |
%d | the size of the match, counting bytes |
%e | the ending byte offset of the match |
%Z | the edit distance cost of an approximate match with option -Z |
%u | select unique lines only unless option -u is used |
%[hhhh]U | U+hhhh Unicode code point |
%[CODE]= | a color CODE, such as ms , see colors |
%= | turn color off |
%1 %2 ... %9 | the first regex group capture of the match, and so on up to group %9 , requires option -P |
%[NUM]# | the group capture NUM ; requires option -P |
%[NUM]b | the byte offset of the group capture NUM ; requires option -P |
%[NUM]e | the ending byte offset of the group capture NUM ; requires option -P |
%[NUM]d | the byte length of the group capture NUM ; requires option -P |
%[NUM]j | the group capture NUM as JSON; requires option -P |
%[NUM]q | the group capture NUM quoted; requires option -P |
%[NUM]x | the group capture NUM as XML; requires option -P |
%[NUM]y | the group capture NUM as hex; requires option -P |
%[NUM]v | the group capture NUM as CSV; requires option -P |
%[NUM1|NUM2|...]# | the first group capture NUM that matched; requires option -P |
%[NUM1|NUM2|...]b | the byte offset of the first group capture NUM that matched; requires option -P . |
%[NUM1|NUM2|...]e | the ending byte offset of the first group capture NUM that matched; requires option -P . |
%[NUM1|NUM2|...]d | the byte length of the first group capture NUM that matched; requires option -P . |
%[NUM1|NUM2|...]j | the first group capture NUM that matched, as JSON; requires option -P |
%[NUM1|NUM2|...]q | the first group capture NUM that matched, quoted; requires option -P |
%[NUM1|NUM2|...]x | the first group capture NUM that matched, as XML; requires option -P |
%[NUM1|NUM2|...]y | the first group capture NUM that matched, as hex; requires option -P |
%[NUM1|NUM2|...]v | the first group capture NUM that matched, as CSV; requires option -P |
%[NAME]# | the NAME d group capture; requires option -P and capturing pattern (?<NAME>PATTERN) |
%[NAME]b | the byte offset of the NAME d group capture; requires option -P and capturing pattern (?<NAME>PATTERN) . |
%[NAME]e | the ending byte offset of the NAME d group capture; requires option -P and capturing pattern (?<NAME>PATTERN) . |
%[NAME]d | the byte length of the NAME d group capture; requires option -P and capturing pattern (?<NAME>PATTERN) . |
%[NAME]j | the NAME d group capture as JSON; requires option -P and capturing pattern (?<NAME>PATTERN) |
%[NAME]q | the NAME d group capture quoted; requires option -P and capturing pattern (?<NAME>PATTERN) |
%[NAME]x | the NAME d group capture as XML; requires option -P and capturing pattern (?<NAME>PATTERN) |
%[NAME]y | the NAME d group capture as hex; requires option -P and capturing pattern (?<NAME>PATTERN) |
%[NAME]v | the NAME d group capture as CSV; requires option -P and capturing pattern (?<NAME>PATTERN) |
%[NAME1|NAME2|...]# | the first NAME d group capture that matched; requires option -P and capturing pattern (?<NAME>PATTERN) |
%[NAME1|NAME2|...]b | the byte offset of the first NAME d group capture that matched; requires option -P and capturing pattern (?<NAME>PATTERN) |
%[NAME1|NAME2|...]e | the ending byte offset of the first NAME d group capture that matched; requires option -P and capturing pattern (?<NAME>PATTERN) |
%[NAME1|NAME2|...]d | the byte length of the first NAME d group capture that matched; requires option -P and capturing pattern (?<NAME>PATTERN) |
%[NAME1|NAME2|...]j | the first NAME d group capture that matched, as JSON; requires option -P and capturing pattern (?<NAME>PATTERN) |
%[NAME1|NAME2|...]q | the first NAME d group capture that matched, quoted; requires option -P and capturing pattern (?<NAME>PATTERN) |
%[NAME1|NAME2|...]x | the first NAME d group capture that matched, as XML; requires option -P and capturing pattern (?<NAME>PATTERN) |
%[NAME1|NAME2|...]y | the first NAME d group capture that matched, as hex; requires option -P and capturing pattern (?<NAME>PATTERN) |
%[NAME1|NAME2|...]v | the first NAME d group capture that matched, as CSV; requires option -P and capturing pattern (?<NAME>PATTERN) |
%G | list of group capture indices/names of the match (see note) |
%[TEXT1|TEXT2|...]G | list of TEXT indexed by group capture indices that matched; requires option -P |
%g | the group capture index of the match or 1 (see note) |
%[TEXT1|TEXT2|...]g | the first TEXT indexed by the first group capture index that matched; requires option -P |
笔记：
%~ is explicitly specified in the format string.-o changes the output of the %O and %Q fields to output the match only.-c , -l and -o change the output of %C , %J , %X and %Y accordingly[TEXT] part of a field is optional and may be omitted. When present, the argument must be placed in [] brackets, for example %[,]F to output a comma, the pathname, and a separator, when option -H is used.%n are padded with spaces when %{width}n is specified.%O are cut to width when %{width}O is specified or when %{-width}O is specified to cut from the end of the line.%{-width}o or %{+width}o is specified for match fields such as %o , where %{width}o without a +/- sign cuts the match to the specified width.%[SEP]$ and %u are switches and do not write anything to the output.%F , %H , %N , %K , %B , %S , and %G may be changed by preceding the field with a %[SEP]$ . When [SEP] is not provided, reverts the separator to the default separator or the separator specified by --separator .%u is found anywhere in the specified format string, matching lines are output only once unless option -u , --ungroup is used or when a newline is matched.%g corresponds to the index of the sub-pattern matched among the alternations in the pattern when option -P is not used. For example foo|bar matches foo with index 1 and bar with index 2. With option -P , the index corresponds to the number of the first group captured in the specified pattern.%[TEXT1|TEXT2|...]G and %[TEXT1|TEXT2|...]g should correspond to the group capture index (see the note above), ie TEXT1 is output for index 1, TEXT2 is output for index 2, and so on. If the list is too short, the index value is output or the name of a named group capture is output.-T and --pretty add right-justifying spacing to fields %N and %K if no leading [TEXT] part is specified.%+ may be used in --format-open to output the pathname heading and a newline break, respectively. Field %+ suppresses %a , %F , %f , %H , %h and %p output. To output matching lines faster by omitting the header output and binary match checks, using --format with field %O (output matching line as is) and field %~ (output newline):
ug --format='%O%~' 'href=' index.html
Same, but also displaying the line and column numbers:
ug --format='%n%k: %O%~' 'href=' index.html
Same, but display a line at most once when matching multiple patterns, unless option -u is used:
ug --format='%u%n%k: %O%~' 'href=' index.html
To string together a list of unique line numbers of matches, separated by commas with field %, :
ug --format='%u%,%n' 'href=' index.html
To output the matching part of a line only with field %o (or option -o with field %O ):
ug --format='%o%~' "href=["'][^"']["']" index.html
To string together the pattern matches as CSV-formatted strings with field %v separated by commas with field %, :
ug --format='%,%v' "href=["'][^"']["']" index.html
To output matches in CSV (comma-separated values), the same as option --csv (works with options -H , -n , -k , -b to add CSV values):
ug --format='"%[,]$%H%N%K%B%V%~%u"' 'href=' index.html
To output matches in AckMate format:
ug --format=":%f%~%n;%k %w:%O%~" 'href=' index.html
To output the sub-pattern indices 1, 2, and 3 on the left to the match for the three patterns foo , bar , and baz in file foobar.txt :
ug --format='%g: %o%~' 'foo|bar|baz' foobar.txt
Same, but using a file foos containing three lines with foo , bar , and baz , where option -F is used to match strings instead of regex:
ug -F -f foos --format='%g: %o%~' foobar.txt
To output one , two , and a word for the sub-patterns [fF]oo , [bB]ar , and any other word w+ , respectively, using argument [one|two|a word] with field %g indexed by sub-pattern (or group captures with option -P ):
ug --format='%[one|two|a word]g%~' '([fF]oo)|([bB]ar)|(w+)' foobar.txt
To output a list of group capture indices with %G separated by the word and instead of the default colons with %[ and ]$ , followed by the matching line:
ug -P --format='%[ and ]$%G%$%s%O%~' '(foo)|(ba((r)|(z)))' foobar.txt
Same, but showing names instead of numbers:
ug -P --format='%[ and ]$%[foo|ba|r|z]G%$%s%O%~' '(foo)|(ba(?:(r)|(z)))' foobar.txt
Note that option -P is required for general use of group captures for sub-patterns. Named sub-pattern matches may be used with PCRE2 and shown in the output:
ug -P --format='%[ and ]$%G%$%s%O%~' '(?P<foo>foo)|(?P<ba>ba(?:(?P<r>r)|(?P<z>z)))' foobar.txt
？返回目录
--replace=FORMAT
Replace matching patterns in the output by the specified FORMAT
with `%' fields. If -P is specified, FORMAT may include `%1' to
`%9', `%[NUM]#' and `%[NAME]#' to output group captures. A `%%'
outputs `%' and `%~' outputs a newline. See option --format,
`ugrep --help format' and `man ugrep' section FORMAT for details.
-y, --any-line
Any line is output (passthru). Non-matching lines are output as
context with a `-' separator. See also options -A, -B, and -C.
-P, --perl-regexp
Interpret PATTERN as a Perl regular expression.
--format=FORMAT
Output FORMAT-formatted matches. For example --format='%f:%n:%O%~'
outputs matching lines `%O' with filename `%f` and line number `%n'
followed by a newline `%~'. If -P is specified, FORMAT may include
`%1' to `%9', `%[NUM]#' and `%[NAME]#' to output group captures. A
`%%' outputs `%'. See `ugrep --help format' and `man ugrep'
section FORMAT for details. When option -o is specified, option -u
is also enabled. Context options -A, -B, -C and -y are ignored.
See customized output with --format for details on the FORMAT fields.
For option -o , the replacement is not automatically followed by a newline to allow for more flexibility in replacements. To output a newline, use %~ in the FORMAT string.
Use option -P to use group captures and backreferences. Capturing groups in regex patterns are parenthesized expressions (pattern) and the first is referenced in FORMAT by %1 , the second by %2 and so on. Named captures are of the form (?<NAME>pattern) and are referenced in FORMAT by %[NAME]# .
To display pattern matches with their sequential match number using --replace='%m:%o' where %m is the sequential match number and %o is the pattern matched:
ug --replace='%m:%o' pattern myfile.txt
Same, but passing the file through with option -y , while applying the replacements to the output:
ug -y --replace='%m:%o' pattern myfile.txt
To extract table cells from an HTML file using Perl matching ( -P ) to support group captures with lazy quantifier (.*?) , and translate the matches to a comma-separated list with format %,%1 (conditional comma and group capture ）：
ug -P -o '<td>(.*?)</td>' --replace='%,%1' index.html
Same, but using --format='%,%1' instead and we do not need -o (note that --replace color-highlights matches shown on a terminal but --format does not):
ug -P '<td>(.*?)</td>' --format='%,%1' index.html
Same, but displaying the formatted matches line-by-line, with --replace or with --format :
ug -P -o '<td>(.*?)</td>' --replace='%,%1' index.html
ug -P '<td>(.*?)</td>' --format='%1%~' index.html
To collect all href URLs from all HTML and PHP files down the working directory, then sort them:
ug -r -thtml,php -P '<[^<>]+hrefh*=h*.([^x27"]+).' --format='%1%~' | sort -u
Same, but much easier by using the predefined html/href pattern:
ug -r -thtml,php -P -f html/href --format='%1%~' | sort -u
Same, but in this case select <script> src URLs when referencing http and https sites:
ug -r -thtml,php -P '<script.*srch*=h*.(https?:[^x27"]+).' --format='%1%~' | sort -u
？返回目录
--depth=[MIN,][MAX], -1, -2, -3, ... -9, -10, -11, -12, ...
Restrict recursive searches from MIN to MAX directory levels deep,
where -1 (--depth=1) searches the specified path without recursing
into subdirectories. Note that -3 -5, -3-5, and -35 search 3 to 5
levels deep. Enables -r if -R or -r is not specified.
-K [MIN,][MAX], --range=[MIN,][MAX], --min-line=MIN, --max-line=MAX
Start searching at line MIN, stop at line MAX when specified.
-m [MIN,][MAX], --min-count=MIN, --max-count=MAX
Require MIN matches, stop after MAX matches when specified. Output
MIN to MAX matches. For example, -m1 outputs the first match and
-cm1, (with a comma) counts nonzero matches. If -u is specified,
each individual match counts. See also option -K.
--max-files=NUM
Restrict the number of files matched to NUM. Note that --sort or
-J1 may be specified to produce replicable results. If --sort is
specified, the number of threads spawned is limited to NUM.
--sort[=KEY]
Displays matching files in the order specified by KEY in recursive
searches. Normally the ug command sorts by name whereas the ugrep
batch command displays matches in no particular order to improve
performance. The sort KEY can be `name' to sort by pathname
(default), `best' to sort by best match with option -Z (sort by
best match requires two passes over files, which is expensive),
`size' to sort by file size, `used' to sort by last access time,
`changed' to sort by last modification time and `created' to sort
by creation time. Sorting is reversed with `rname', `rbest',
`rsize', `rused', `rchanged', or `rcreated'. Archive contents are
not sorted. Subdirectories are sorted and displayed after matching
files. FILE arguments are searched in the same order as specified.
To show only up to the first 10 matching lines with FIXME in C++ files in the working directory and all subdirectories below:
ug -r -m10 -tc++ FIXME
Same, but recursively search up to two directory levels, meaning that ./ and ./sub/ are visited but not deeper:
ug -2 -m10 -tc++ FIXME
To show only the first two files that have one or more matches of FIXME in the list of files sorted by pathname, using --max-files=2 :
ug --sort -r --max-files=2 -tc++ FIXME
To search file install.sh for the occurrences of the word make after the first line, we use -K with line number 2 to start searching, where -n shows the line numbers in the output:
ug -n -K2 -w make install.sh
Same, but restricting the search to lines 2 to 40 (inclusive):
ug -n -K2,40 -w make install.sh
Same, but showing all lines 2 to 40 with -y :
ug -y -n -K2,40 -w make install.sh
Same, but showing only the first four matching lines after line 2, with one line of context:
ug -n -C1 -K2 -m4 -w make install.sh
？返回目录
-Y, --empty
Permits empty matches. By default, empty matches are disabled,
unless a pattern begins with `^' or ends with `$'. Note that -Y
when specified with an empty-matching pattern, such as x? and x*,
match all input, not only lines containing the character `x'.
Option -Y permits empty pattern matches, like GNU/BSD grep. This option is introduced by ugrep to prevent accidental matching with empty patterns: empty-matching patterns such as x? and x* match all input, not only lines with x . By default, without -Y , patterns match lines with at least one x as intended.
This option is automatically enabled when a pattern starts with ^ or ends with $ is specified. For example, ^h*$ matches blank lines, including empty lines.
To recursively list files in the working directory with blank lines, ie lines with white space only, including empty lines (note that option -Y is implicitly enabled since the pattern starts with ^ and ends with $ ):
ug -l '^h*$'
？返回目录
-i, --ignore-case
Perform case insensitive matching. By default, ugrep is case
sensitive. By default, this option applies to ASCII letters only.
Use options -P and -i for Unicode case insensitive matching.
-j, --smart-case
Perform case insensitive matching like option -i, unless a pattern
is specified with a literal ASCII upper case letter.
To match todo in myfile.cpp regardless of case:
ug -i 'todo' myfile.txt
To match todo XXX with todo in any case but XXX as given, with pattern (?i:todo) to match todo ignoring case:
ug '(?i:todo) XXX' myfile.cpp
？返回目录
--sort[=KEY]
Displays matching files in the order specified by KEY in recursive
searches. Normally the ug command sorts by name whereas the ugrep
batch command displays matches in no particular order to improve
performance. The sort KEY can be `name' to sort by pathname
(default), `best' to sort by best match with option -Z (sort by
best match requires two passes over files, which is expensive),
`size' to sort by file size, `used' to sort by last access time,
`changed' to sort by last modification time and `created' to sort
by creation time. Sorting is reversed with `rname', `rbest',
`rsize', `rused', `rchanged', or `rcreated'. Archive contents are
not sorted. Subdirectories are sorted and displayed after matching
files. FILE arguments are searched in the same order as specified.
Matching files are displayed in the order specified by --sort per directory searched. By default, the ug command sorts by name whereas the output of the ugrep command is not sorted to improve performance, unless option -Q is used which sorts files by name. An optimized sorting method and strategy are implemented in the asynchronous output class to keep the overhead of sorting very low. Directories are displayed after files are displayed first, when recursing, which visually aids the user in finding the "closest" matching files first at the top of the displayed results.
To recursively search for C++ files that match main and sort them by date created:
ug --sort=created -tc++ 'main'
Same, but sorted by time changed from most recent to oldest:
ug --sort=rchanged -tc++ 'main'
？返回目录
When searching non-binary files only, the binary content check is disabled with option -a ( --text ) to speed up searching and displaying pattern matches. For example, searching for lines with int in C++ source code:
ug -r -a -Ocpp -w 'int'
If a file has potentially many pattern matches, but each match is only one a single line, then option -u ( --ungroup ) can speed this up:
ug -r -a -u -Opython -w 'def'
Even greater speeds can be achieved with --format when searching files with many matches. For example, --format='%O%~' displays matching lines for each match on that line, while --format='%o%~' displays the matching part only. Note that the --format option does not check for binary matches, so the output is always "as is". To match text and binary, you can use --format='%C%~' to display matches formatted as quoted C++ strings with escapes. To display a line at most once (unless option -u is used), add the %u (unique) field to the format string, eg --format='%u%O%~' .
For example, to match all words recursively in the working directory with line and column numbers, where %n is the line number, %k is the column number, %o is the match (only matching), and %~ is a newline:
ug -r --format='%n,%k:%o%~' 'w+'
？返回目录
To search for pattern -o in script.sh using -e to explicitly specify a pattern to prevent pattern -o from being interpreted as an option:
ug -n -e '-o' script.sh
Alternatively, using -- to end the list of command arguments:
ug -n -- '-o' script.sh
To recursively list all text files (.txt and .md) that do not properly end with a n ( -o is required to match n or z ):
ug -L -o -Otext 'nz'
To list all markdown sections in text files (.text, .txt, .TXT, and .md):
ug -o -ttext -e '^.*(?=r?n(===|---))' -e '^#{1,6}h+.*'
To display multi-line backtick and indented code blocks in markdown files with their line numbers, using a lazy quantifier *? to make the pattern compact:
ug -n -ttext -e '^```(.|n)*?n```' -e '^(t|[ ]{4}).*'
To find mismatched code (a backtick without matching backtick on the same line) in markdown:
ug -n -ttext -e '`[^`]+' -N '`[^`]*`'
？返回目录
UGREP(1) User Commands UGREP(1)
NAME
ugrep, ug -- file pattern searcher
SYNOPSIS
ugrep [OPTIONS] [-i] [-Q|PATTERN] [-e PATTERN] [-N PATTERN] [-f FILE]
[-F|-G|-P|-Z] [-U] [-m [MIN,][MAX]] [--bool [--files|--lines]]
[-r|-R|-1|...|-9|-10|...] [-t TYPES] [-g GLOBS] [--sort[=KEY]]
[-l|-c] [-o] [-n] [-k] [-b] [-A NUM] [-B NUM] [-C NUM] [-y]
[--color[=WHEN]|--colour[=WHEN]] [--pretty] [--pager[=COMMAND]]
[--hexdump|--csv|--json|--xml] [-I] [-z] [--zmax=NUM] [FILE ...]
DESCRIPTION
The ugrep utility searches any given input files, selecting files and
lines that match one or more patterns specified as regular expressions or
as fixed strings. A pattern matches multiple input lines when the
pattern's regular expression matches one or more newlines. An empty
pattern matches every line. Each input line that matches at least one of
the patterns is written to the standard output.
The ug command is intended for interactive searching, using a .ugrep
configuration file located in the working directory or home directory,
see CONFIGURATION. ug is equivalent to ugrep --config --pretty --sort to
load a .ugrep file, enhance the terminal output, and sort files by name.
The ugrep+ and ug+ commands are the same as the ugrep and ug commands,
but also use filters to search pdfs, documents, e-books, and image
metadata, when the corresponding filter tools are installed.
A list of matching files is produced with option -l (--files-with-
matches). Option -c (--count) counts the number of matching lines. When
combined with option -o, counts the total number of matches. When
combined with option -m1, (--min-count=1), skips files with zero matches.
The default pattern syntax is an extended form of the POSIX ERE syntax,
same as option -E (--extended-regexp). Try ug --help regex for help with
pattern syntax and how to use logical connectives to specify Boolean
search queries with option -% (--bool) to match lines and -%% (--bool
--files) to match files. Options -F (--fixed-strings), -G (--basic-
regexp) and -P (--perl-regexp) specify other pattern syntaxes.
Option -i (--ignore-case) ignores case in ASCII patterns. When combined
with option -P, ignores case in Unicode patterns. Option -j (--smart-
case) enables -i only if the search patterns are specified in lower case.
Fuzzy (approximate) search is specified with option -Z (--fuzzy) with an
optional argument to control character insertions, deletions, and/or
substitutions. Try ug --help fuzzy for help with fuzzy search.
Note that pattern `.' matches any non-newline character. Pattern `n'
matches a newline character. Multiple lines may be matched with patterns
that match one or more newline characters.
The empty pattern "" matches all lines. Other empty-matching patterns do
not. For example, the pattern `a*' will match one or more a's. Option
-Y forces empty matches for compatibility with other grep tools.
Option -f FILE matches patterns specified in FILE.
By default Unicode patterns are matched. Option -U (--ascii or --binary)
disables Unicode matching for ASCII and binary pattern matching. Non-
Unicode matching is more efficient.
ugrep accepts input of various encoding formats and normalizes the output
to UTF-8. When a UTF byte order mark is present in the input, the input
is automatically normalized. An input encoding format may be specified
with option --encoding.
If no FILE arguments are specified and standard input is read from a
terminal, recursive searches are performed as if -r is specified. To
force reading from standard input, specify `-' as a FILE argument.
Directories specified as FILE arguments are searched without recursing
deeper into subdirectories, unless -R, -r, or -2...-9 is specified to
search subdirectories recursively (up to the specified depth.)
Option -I (--ignore-binary) ignores binary files. A binary file is a
file with non-text content. A file with zero bytes or invalid UTF
formatting is considered binary.
Hidden files and directories are ignored in recursive searches. Option
-. (--hidden) includes hidden files and directories in recursive
searches.
To match the names of files to search and the names of directories to
recurse, one or more of the following options may be specified. Option
-O specifies one or more filename extensions to match. Option -t
specifies one or more file types to search (-t list outputs a list of
types.) Option -g specifies a gitignore-style glob pattern to match
filenames. Option --ignore-files specifies a file with gitignore-style
globs to ignore directories and files. Try ug --help globs for help with
filename and directory name matching. See also section GLOBBING.
Compressed files and archives are searched with option -z (--decompress).
When used with option --zmax=NUM, searches the contents of compressed
files and archives stored within archives up to NUM levels.
A query terminal user interface (TUI) is opened with -Q (--query) to
interactively specify search patterns and view search results. A PATTERN
argument requires -e PATTERN to start the query TUI with the specified
pattern.
Output to a terminal for viewing is enhanced with --pretty, which is
enabled by default with the ug command.
A terminal output pager is enabled with --pager.
Customized output is produced with option --format or --replace. Try ug
--help format for help with custom formatting of the output. Predefined
formats include CSV with option --csv, JSON with option --json, and XML
with option --xml. Hexdumps are output with option -X (--hex) or with
option --hexdump to customize hexdumps. See also section FORMAT.
A `--' signals the end of options; the rest of the parameters are FILE
arguments, allowing filenames to begin with a `-' character.
Long options may start with `--no-' to disable, when applicable.
ug --help WHAT displays help on options related to WHAT.
The following options are available:
-A NUM, --after-context=NUM
Output NUM lines of trailing context after matching lines. Places
a --group-separator between contiguous groups of matches. If -o
is specified, output the match with context to fit NUM columns
after the match or shortens the match. See also options -B, -C
and -y.
-a, --text
Process a binary file as if it were text. This is equivalent to
the --binary-files=text option. This option might output binary
garbage to the terminal, which can have problematic consequences
if the terminal driver interprets some of it as commands.
--all, -@
Search all files except hidden: cancel previous file and directory
search restrictions and cancel --ignore-binary and --ignore-files
when specified. Restrictions specified after this option, i.e. to
the right, are still applied. For example, -@I searches all
non-binary files and -@. searches all files including hidden
files. Note that hidden files and directories are never searched,
unless option -. or --hidden is specified.
--and [-e] PATTERN
Specify additional PATTERN that must match. Additional -e PATTERN
following this option is considered an alternative pattern to
match, i.e. each -e is interpreted as an OR pattern enclosed
within the AND. For example, -e A -e B --and -e C -e D matches
lines with (`A' or `B') and (`C' or `D'). Note that multiple -e
PATTERN are alternations that bind more tightly together than
--and. Option --stats displays the search patterns applied. See
also options --not, --andnot, --bool, --files and --lines.
--andnot [-e] PATTERN
Combines --and --not. See also options --and, --not and --bool.
-B NUM, --before-context=NUM
Output NUM lines of leading context before matching lines. Places
a --group-separator between contiguous groups of matches. If -o
is specified, output the match with context to fit NUM columns
before the match or shortens the match. See also options -A, -C
and -y.
-b, --byte-offset
The offset in bytes of a pattern match is displayed in front of
the respective matched line. When -u is specified, displays the
offset for each pattern matched on the same line. Byte offsets
are exact for ASCII, UTF-8 and raw binary input. Otherwise, the
byte offset in the UTF-8 normalized input is displayed.
--binary-files=TYPE
Controls searching and reporting pattern matches in binary files.
TYPE can be `binary', `without-match`, `text`, `hex` and
`with-hex'. The default is `binary' to search binary files and to
report a match without displaying the match. `without-match'
ignores binary matches. `text' treats all binary files as text,
which might output binary garbage to the terminal, which can have
problematic consequences if the terminal driver interprets some of
it as commands. `hex' reports all matches in hexadecimal.
`with-hex' only reports binary matches in hexadecimal, leaving
text matches alone. A match is considered binary when matching a
zero byte or invalid UTF. Short options are -a, -I, -U, -W and
-X.
--bool, -%, -%%
Specifies Boolean query patterns. A Boolean query pattern is
composed of `AND', `OR', `NOT' operators and grouping with `('
`)'. Spacing between subpatterns is the same as `AND', `|' is the
same as `OR' and a `-' is the same as `NOT'. The `OR' operator
binds more tightly than `AND'. For example, --bool 'A|B C|D'
matches lines with (`A' or `B') and (`C' or `D'), --bool 'A -B'
matches lines with `A' and not `B'. Operators `AND', `OR', `NOT'
require proper spacing. For example, --bool 'A OR B AND C OR D'
matches lines with (`A' or `B') and (`C' or `D'), --bool 'A AND
NOT B' matches lines with `A' without `B'. Quoted subpatterns are
matched literally as strings. For example, --bool 'A "AND"|"OR"'
matches lines with `A' and also either `AND' or `OR'. Parentheses
are used for grouping. For example, --bool '(A B)|C' matches
lines with `A' and `B', or lines with `C'. Note that all
subpatterns in a Boolean query pattern are regular expressions,
unless -F is specified. Options -E, -F, -G, -P and -Z can be
combined with --bool to match subpatterns as strings or regular
expressions (-E is the default.) This option does not apply to -f
FILE patterns. The double short option -%% enables options --bool
--files. Option --stats displays the Boolean search patterns
applied. See also options --and, --andnot, --not, --files and
--lines.
--break
Adds a line break between results from different files. This
option is enabled by --heading.
-C NUM, --context=NUM
Output NUM lines of leading and trailing context surrounding each
matching line. Places a --group-separator between contiguous
groups of matches. If -o is specified, output the match with
context to fit NUM columns before and after the match or shortens
the match. See also options -A, -B and -y.
-c, --count
Only a count of selected lines is written to standard output. If
-o or -u is specified, counts the number of patterns matched. If
-v is specified, counts the number of non-matching lines. If -m1,
(with a comma or --min-count=1) is specified, counts only matching
files without outputting zero matches.
--color[=WHEN], --colour[=WHEN]
Mark up the matching text with the colors specified with option
--colors or the GREP_COLOR or GREP_COLORS environment variable.
WHEN can be `never', `always', or `auto', where `auto' marks up
matches only when output on a terminal. The default is `auto'.
--colors=COLORS, --colours=COLORS
Use COLORS to mark up text. COLORS is a colon-separated list of
one or more parameters `sl=' (selected line), `cx=' (context
line), `mt=' (matched text), `ms=' (match selected), `mc=' (match
context), `fn=' (file name), `ln=' (line number), `cn=' (column
number), `bn=' (byte offset), `se=' (separator), `qp=' (TUI
prompt), `qe=' (TUI errors), `qr=' (TUI regex), `qm=' (TUI regex
meta characters), `ql=' (TUI regex lists and literals), `qb=' (TUI
regex braces). Parameter values are ANSI SGR color codes or `k'
(black), `r' (red), `g' (green), `y' (yellow), `b' (blue), `m'
(magenta), `c' (cyan), `w' (white), or leave empty for no color.
Upper case specifies background colors. A `+' qualifies a color
as bright. A foreground and a background color may be combined
with font properties `n' (normal), `f' (faint), `h' (highlight),
`i' (invert), `u' (underline). Parameter `hl' enables file name
hyperlinks. Parameter `rv' reverses the `sl=' and `cx='
parameters when option -v is specified. Selectively overrides
GREP_COLORS. Legacy grep single parameter codes may be specified,
for example --colors='7;32' or --colors=ig to set ms (match
selected).
--config[=FILE], ---[FILE]
Use configuration FILE. The default FILE is `.ugrep'. The
working directory is checked first for FILE, then the home
directory. The options specified in the configuration FILE are
parsed first, followed by the remaining options specified on the
command line. The ug command automatically loads a `.ugrep'
configuration file, unless --config=FILE or --no-config is
specified.
--no-config
Do not automatically load the default .ugrep configuration file.
--no-confirm
Do not confirm actions in -Q query TUI. The default is confirm.
--cpp Output file matches in C++. See also options --format and -u.
--csv Output file matches in CSV. If -H, -n, -k, or -b is specified,
additional values are output. See also options --format and -u.
-D ACTION, --devices=ACTION
If an input file is a device, FIFO or socket, use ACTION to
process it. By default, ACTION is `skip', which means that
devices are silently skipped. If ACTION is `read', devices read
just as if they were ordinary files.
-d ACTION, --directories=ACTION
If an input file is a directory, use ACTION to process it. By
default, ACTION is `skip', i.e., silently skip directories unless
specified on the command line. If ACTION is `read', warn when
directories are read as input. If ACTION is `recurse', read all
files under each directory, recursively, following symbolic links
only if they are on the command line. This is equivalent to the
-r option. If ACTION is `dereference-recurse', read all files
under each directory, recursively, following symbolic links. This
is equivalent to the -R option.
--delay=DELAY
Set the default -Q key response delay. Default is 3 for 300ms.
--depth=[MIN,][MAX], -1, -2, -3, ... -9, -10, -11, ...
Restrict recursive searches from MIN to MAX directory levels deep,
where -1 (--depth=1) searches the specified path without recursing
into subdirectories. The short forms -3 -5, -3-5 and -3,5 search
3 to 5 levels deep. Enables -r if -R or -r is not specified.
--dotall
Dot `.' in regular expressions matches anything, including
newline. Note that `.*' matches all input and should not be used.
-E, --extended-regexp
Interpret patterns as extended regular expressions (EREs). This is
the default.
-e PATTERN, --regexp=PATTERN
Specify a PATTERN to search the input. An input line is selected
if it matches any of the specified patterns. This option is
useful when multiple -e options are used to specify multiple
patterns, or when a pattern begins with a dash (`-'), or to
specify a pattern after option -f or after the FILE arguments.
--encoding=ENCODING
The encoding format of the input. The default ENCODING is binary
and UTF-8 which are the same. Note that option -U specifies
binary PATTERN matching (text matching is the default.) ENCODING
can be: `binary', `ASCII', `UTF-8', `UTF-16', `UTF-16BE',
`UTF-16LE', `UTF-32', `UTF-32BE', `UTF-32LE', `LATIN1',
`ISO-8859-1', `ISO-8859-2', `ISO-8859-3', `ISO-8859-4',
`ISO-8859-5', `ISO-8859-6', `ISO-8859-7', `ISO-8859-8',
`ISO-8859-9', `ISO-8859-10', `ISO-8859-11', `ISO-8859-13',
`ISO-8859-14', `ISO-8859-15', `ISO-8859-16', `MAC', `MACROMAN',
`EBCDIC', `CP437', `CP850', `CP858', `CP1250', `CP1251', `CP1252',
`CP1253', `CP1254', `CP1255', `CP1256', `CP1257', `CP1258',
`KOI8-R', `KOI8-U', `KOI8-RU'.
--exclude=GLOB
Exclude files whose name matches GLOB, same as -g ^GLOB. GLOB can
use **, *, ?, and [...] as wildcards and to quote a wildcard or
backslash character literally. When GLOB contains a `/', full
pathnames are matched. Otherwise basenames are matched. When
GLOB ends with a `/', directories are excluded as if --exclude-dir
is specified. Otherwise files are excluded. Note that --exclude
patterns take priority over --include patterns. GLOB should be
quoted to prevent shell globbing. This option may be repeated.
--exclude-dir=GLOB
Exclude directories whose name matches GLOB from recursive
searches, same as -g ^GLOB/. GLOB can use **, *, ?, and [...] as
wildcards and to quote a wildcard or backslash character
literally. When GLOB contains a `/', full pathnames are matched.
Otherwise basenames are matched. Note that --exclude-dir patterns
take priority over --include-dir patterns. GLOB should be quoted
to prevent shell globbing. This option may be repeated.
--exclude-from=FILE
Read the globs from FILE and skip files and directories whose name
matches one or more globs. A glob can use **, *, ?, and [...] as
wildcards and to quote a wildcard or backslash character
literally. When a glob contains a `/', full pathnames are
matched. Otherwise basenames are matched. When a glob ends with
a `/', directories are excluded as if --exclude-dir is specified.
Otherwise files are excluded. A glob starting with a `!'
overrides previously-specified exclusions by including matching
files. Lines starting with a `#' and empty lines in FILE are
ignored. When FILE is a `-', standard input is read. This option
may be repeated.
--exclude-fs=MOUNTS
Exclude file systems specified by MOUNTS from recursive searches.
MOUNTS is a comma-separated list of mount points or pathnames to
directories. When MOUNTS is not specified, only descends into the
file systems associated with the specified file and directory
search targets, i.e. excludes all other file systems. Note that
--exclude-fs=MOUNTS take priority over --include-fs=MOUNTS. This
option may be repeated.
-F, --fixed-strings
Interpret pattern as a set of fixed strings, separated by
newlines, any of which is to be matched. This makes ugrep behave
as fgrep. If a PATTERN is specified, or -e PATTERN or -N PATTERN,
then this option has no effect on -f FILE patterns to allow -f
FILE patterns to narrow or widen the scope of the PATTERN search.
-f FILE, --file=FILE
Read newline-separated patterns from FILE. White space in
patterns is significant. Empty lines in FILE are ignored. If
FILE does not exist, the GREP_PATH environment variable is used as
path to FILE. If that fails, looks for FILE in
/usr/local/share/ugrep/patterns. When FILE is a `-', standard
input is read. Empty files contain no patterns; thus nothing is
matched. This option may be repeated.
--filter=COMMANDS
Filter files through the specified COMMANDS first before
searching. COMMANDS is a comma-separated list of `exts:command
arguments', where `exts' is a comma-separated list of filename
extensions and `command' is a filter utility. Files matching one
of `exts' are filtered. A `*' matches any file. The specified
`command' may include arguments separated by spaces. An argument
may be quoted to include spacing, commas or a `%'. A `%' argument
expands into the pathname to search. For example,
--filter='pdf:pdftotext % -' searches PDF files. The `%' expands
into a `-' when searching standard input. When a `%' is not
specified, the filter command should read from standard input and
write to standard output. Option --label=.ext may be used to
specify extension `ext' when searching standard input. This
option may be repeated.
--filter-magic-label=[+]LABEL:MAGIC
Associate LABEL with files whose signature "magic bytes" match the
MAGIC regex pattern. Only files that have no filename extension
are labeled, unless +LABEL is specified. When LABEL matches an
extension specified in --filter=COMMANDS, the corresponding
command is invoked. This option may be repeated.
--format=FORMAT
Output FORMAT-formatted matches. For example
--format='%f:%n:%O%~' outputs matching lines `%O' with filename
`%f` and line number `%n' followed by a newline `%~'. If -P is
specified, FORMAT may include `%1' to `%9', `%[NUM]#' and
`%[NAME]#' to output group captures. A `%%' outputs `%'. See
`ugrep --help format' and `man ugrep' section FORMAT for details.
When option -o is specified, option -u is also enabled. Context
options -A, -B, -C and -y are ignored.
--free-space
Spacing (blanks and tabs) in regular expressions are ignored.
-G, --basic-regexp
Interpret patterns as basic regular expressions (BREs).
-g GLOBS, --glob=GLOBS, --iglob=GLOBS
Only search files whose name matches the specified comma-separated
list of GLOBS, same as --include=glob for each `glob' in GLOBS.
When a `glob' is preceded by a `!' or a `^', skip files whose name
matches `glob', same as --exclude='glob'. When `glob' contains a
`/', full pathnames are matched. Otherwise basenames are matched.
When `glob' ends with a `/', directories are matched, same as
--include-dir='glob' and --exclude-dir='glob'. A leading `/'
matches the working directory. Option --iglob performs
case-insensitive name matching. This option may be repeated and
may be combined with options -M, -O and -t to expand searches.
See `ugrep --help globs' and `man ugrep' section GLOBBING for
details.
--glob-ignore-case
Perform case-insensitive glob matching in general.
--group-separator[=SEP]
Use SEP as a group separator for context options -A, -B and -C.
The default is a double hyphen (`--').
--no-group-separator
Removes the group separator line from the output for context
options -A, -B and -C.
-H, --with-filename
Always print the filename with output lines. This is the default
when there is more than one file to search.
-h, --no-filename
Never print filenames with output lines. This is the default when
there is only one file (or only standard input) to search.
--heading, -+
Group matches per file. Adds a heading and a line break between
results from different files. This option is enabled by --pretty
when the output is sent to a terminal.
--help [WHAT], -? [WHAT]
Display a help message on options related to WHAT when specified.
In addition, `--help regex' displays an overview of regular
expressions, `--help globs' displays an overview of glob syntax
and conventions. `--help fuzzy' displays details of fuzzy search
with option -Z and `--help format' displays a list of --format
fields.
--hexdump[=[1-8][a][bch][A[NUM]][B[NUM]][C[NUM]]]
Output matches in 1 to 8 columns of 8 hexadecimal octets. The
default is 2 columns or 16 octets per line. Argument `a' outputs
a `*' for all hex lines that are identical to the previous hex
line, `b' removes all space breaks, `c' removes the character
column, `h' removes hex spacing, `A' includes up to NUM hex lines
after a match, `B' includes up to NUM hex lines before a match and
`C' includes up to NUM hex lines before and after a match.
Arguments `A', `B' and `C' are the same as options -A, -B and -C
when used with --hexdump. See also options -U, -W and -X.
--hidden, -.
Search hidden files and directories.
--hyperlink[=[PREFIX][+]]
Hyperlinks are enabled for file names when colors are enabled.
Same as --colors=hl. When PREFIX is specified, replaces file://
with PREFIX:// in the hyperlink. A `+' includes the line number
in the hyperlink and when option -k is specified, the column
number.
-I, --ignore-binary
Ignore matches in binary files. This option is equivalent to the
--binary-files=without-match option.
-i, --ignore-case
Perform case insensitive matching. By default, ugrep is case
sensitive. By default, this option applies to ASCII letters only.
Use options -P and -i for Unicode case insensitive matching.
--ignore-files[=FILE]
Ignore files and directories matching the globs in each FILE that
is encountered in recursive searches. The default FILE is
`.gitignore'. Matching files and directories located in the
directory of the FILE and in subdirectories below are ignored.
Globbing syntax is the same as the --exclude-from=FILE gitignore
syntax, but files and directories are excluded instead of only
files. Directories are specifically excluded when the glob ends
in a `/'. Files and directories explicitly specified as command
line arguments are never ignored. This option may be repeated to
specify additional files.
--no-ignore-files
Do not ignore files, i.e. cancel --ignore-files when specified.
--include=GLOB
Only search files whose name matches GLOB, same as -g GLOB. GLOB
can use **, *, ?, and [...] as wildcards and to quote a wildcard
or backslash character literally. When GLOB contains a `/', full
pathnames are matched. Otherwise basenames are matched. When
GLOB ends with a `/', directories are included as if --include-dir
is specified. Otherwise files are included. Note that --exclude
patterns take priority over --include patterns. GLOB should be
quoted to prevent shell globbing. This option may be repeated.
--include-dir=GLOB
Only directories whose name matches GLOB are included in recursive
searches, same as -g GLOB/. GLOB can use **, *, ?, and [...] as
wildcards and to quote a wildcard or backslash character
literally. When GLOB contains a `/', full pathnames are matched.
Otherwise basenames are matched. Note that --exclude-dir patterns
take priority over --include-dir patterns. GLOB should be quoted
to prevent shell globbing. This option may be repeated.
--include-from=FILE
Read the globs from FILE and search only files and directories
whose name matches one or more globs. A glob can use **, *, ?,
and [...] as wildcards and to quote a wildcard or backslash
character literally. When a glob contains a `/', full pathnames
are matched. Otherwise basenames are matched. When a glob ends
with a `/', directories are included as if --include-dir is
specified. Otherwise files are included. A glob starting with a
`!' overrides previously-specified inclusions by excluding
matching files. Lines starting with a `#' and empty lines in FILE
are ignored. When FILE is a `-', standard input is read. This
option may be repeated.
--include-fs=MOUNTS
Only file systems specified by MOUNTS are included in recursive
searches. MOUNTS is a comma-separated list of mount points or
pathnames to directories. When MOUNTS is not specified, restricts
recursive searches to the file system of the working directory,
same as --include-fs=. (dot). Note that --exclude-fs=MOUNTS take
priority over --include-fs=MOUNTS. This option may be repeated.
--index
Perform fast index-based recursive search. This option assumes,
but does not require, that files are indexed with ugrep-indexer.
This option also enables option -r or --recursive. Skips indexed
non-matching files, archives and compressed files. Significant
acceleration may be achieved on cold (not file-cached) and large
file systems, or any file system that is slow to search. Note
that the start-up time to search may be increased when complex
search patterns are specified that contain large Unicode character
classes combined with `*' or `+' repeats, which should be avoided.
Option -U (--ascii) improves performance. Option --stats displays
an index search report.
-J NUM, --jobs=NUM
Specifies the number of threads spawned to search files. By
default an optimum number of threads is spawned to search files
simultaneously. -J1 disables threading: files are searched in the
same order as specified.
-j, --smart-case
Perform case insensitive matching, unless a pattern is specified
with a literal upper case ASCII letter.
--json Output file matches in JSON. If -H, -n, -k, or -b is specified,
additional values are output. See also options --format and -u.
-K [MIN,][MAX], --range=[MIN,][MAX], --min-line=MIN, --max-line=MAX
Start searching at line MIN, stop at line MAX when specified.
-k, --column-number
The column number of a pattern match is displayed in front of the
respective matched line, starting at column 1. Tabs are expanded
in counting columns, see also option --tabs.
-L, --files-without-match
Only the names of files not containing selected lines are written
to standard output. Pathnames are listed once per file searched.
If the standard input is searched, the string ``(standard input)''
is written.
-l, --files-with-matches
Only the names of files containing selected lines are written to
standard output. ugrep will only search a file until a match has
been found, making searches potentially less expensive. Pathnames
are listed once per file searched. If the standard input is
searched, the string ``(standard input)'' is written.
--label=LABEL
Displays the LABEL value when input is read from standard input
where a file name would normally be printed in the output.
Associates a filename extension with standard input when LABEL has
a suffix. The default value is `(standard input)'.
--line-buffered
Force output to be line buffered instead of block buffered.
--lines
Boolean line matching mode for option --bool, the default mode.
-M MAGIC, --file-magic=MAGIC
Only search files matching the magic signature pattern MAGIC. The
signature "magic bytes" at the start of a file are compared to the
MAGIC regex pattern. When matching, the file will be searched.
When MAGIC is preceded by a `!' or a `^', skip files with matching
MAGIC signatures. This option may be repeated and may be combined
with options -O and -t to expand the search. Every file on the
search path is read, making searches potentially more expensive.
-m [MIN,][MAX], --min-count=MIN, --max-count=MAX
Require MIN matches, stop after MAX matches when specified.
Output MIN to MAX matches. For example, -m1 outputs the first
match and -cm1, (with a comma) counts nonzero matches. If -u is
specified, each individual match counts. See also option -K.
--match
Match all input. Same as specifying an empty pattern to search.
--max-files=NUM
Restrict the number of files matched to NUM. Note that --sort or
-J1 may be specified to produce replicable results. If --sort is
specified, the number of threads spawned is limited to NUM.
--mmap[=MAX]
Use memory maps to search files. By default, memory maps are used
under certain conditions to improve performance. When MAX is
specified, use up to MAX mmap memory per thread.
-N PATTERN, --neg-regexp=PATTERN
Specify a negative PATTERN to reject specific -e PATTERN matches
with a counter pattern. Note that longer patterns take precedence
over shorter patterns, i.e. a negative pattern must be of the same
length or longer to reject matching patterns. Option -N cannot be
specified with -P. This option may be repeated.
-n, --line-number
Each output line is preceded by its relative line number in the
file, starting at line 1. The line number counter is reset for
each file processed.
--not [-e] PATTERN
Specifies that PATTERN should not match. Note that -e A --not -e
B matches lines with `A' or lines without a `B'. To match lines
with `A' that have no `B', specify -e A --andnot -e B. Option
--stats displays the search patterns applied. See also options
--and, --andnot, --bool, --files and --lines.
-O EXTENSIONS, --file-extension=EXTENSIONS
Only search files whose filename extensions match the specified
comma-separated list of EXTENSIONS, same as -g '*.ext' for each
`ext' in EXTENSIONS. When an `ext' is preceded by a `!' or a `^',
skip files whose filename extensions matches `ext', same as -g
'^*.ext'. This option may be repeated and may be combined with
options -g, -M and -t to expand the recursive search.
-o, --only-matching
Only the matching part of a pattern match is output. If -A, -B or
-C is specified, fits the match and its context on a line within
the specified number of columns.
--only-line-number
Only the line number of a matching line is output. The line
number counter is reset for each file processed.
--files, -%%
Boolean file matching mode, the opposite of --lines. When
combined with option --bool, matches a file if all Boolean
conditions are satisfied. For example, --bool --files 'A B|C -D'
matches a file if some lines match `A', and some lines match
either `B' or `C', and no line matches `D'. See also options
--and, --andnot, --not, --bool and --lines. The double short
option -%% enables options --bool --files.
-P, --perl-regexp
Interpret PATTERN as a Perl regular expression using PCRE2. Note
that Perl pattern matching differs from the default grep POSIX
pattern matching.
-p, --no-dereference
If -R or -r is specified, do not follow symbolic links, even when
symbolic links are specified on the command line.
--pager[=COMMAND]
When output is sent to the terminal, uses COMMAND to page through
the output. COMMAND defaults to environment variable PAGER when
defined or `less'. Enables --heading and --line-buffered.
--pretty[=WHEN]
When output is sent to a terminal, enables --color, --heading, -n,
--sort, --tree and -T when not explicitly disabled. WHEN can be
`never', `always', or `auto'. The default is `auto'.
-Q[=DELAY], --query[=DELAY]
Query mode: start a TUI to perform interactive searches. This
mode requires an ANSI capable terminal. An optional DELAY
argument may be specified to reduce or increase the response time
to execute searches after the last key press, in increments of
100ms, where the default is 3 (300ms delay). No whitespace may be
given between -Q and its argument DELAY. Initial patterns may be
specified with -e PATTERN, i.e. a PATTERN argument requires option
-e. Press F1 or CTRL-Z to view the help screen. Press F2 or
CTRL-Y to invoke a command to view or edit the file shown at the
top of the screen. The command can be specified with option
--view and defaults to environment variable PAGER when defined, or
VISUAL or EDITOR. Press Tab or Shift-Tab to navigate directories
and to select a file to search. Press Enter to select lines to
output. Press ALT-l for option -l to list files, ALT-n for -n,
etc. Non-option commands include ALT-] to increase context and
ALT-} to increase fuzzyness. See also options --no-confirm,
--delay, --split and --view.
-q, --quiet, --silent
Quiet mode: suppress all output. Only search a file until a match
has been found.
-R, --dereference-recursive
Recursively read all files under each directory, following
symbolic links to files and directories, unlike -r.
-r, --recursive
Recursively read all files under each directory, following
symbolic links only if they are on the command line. Note that
when no FILE arguments are specified and input is read from a
terminal, recursive searches are performed as if -r is specified.
--replace=FORMAT
Replace matching patterns in the output by FORMAT with `%' fields.
If -P is specified, FORMAT may include `%1' to `%9', `%[NUM]#' and
`%[NAME]#' to output group captures. A `%%' outputs `%' and `%~'
outputs a newline. See also option --format, `ugrep --help
format' and `man ugrep' section FORMAT for details.
-S, --dereference-files
When -r is specified, follow symbolic links to files, but not to
directories. The default is not to follow symbolic links.
-s, --no-messages
Silent mode: nonexistent and unreadable files are ignored and
their error messages and warnings are suppressed.
--save-config[=FILE] [OPTIONS]
Save configuration FILE to include OPTIONS. Update FILE when
first loaded with --config=FILE. The default FILE is `.ugrep',
which is automatically loaded by the ug command. When FILE is a
`-', writes the configuration to standard output. Only part of
the OPTIONS are saved that do not cause searches to fail when
combined with other options. Additional options may be specified
by editing the saved configuration file. A configuration file may
be modified manually to specify one or more config[=FILE] to
indirectly load the specified FILE, but recursive config loading
is not allowed.
--separator[=SEP], --context-separator=SEP
Use SEP as field separator between file name, line number, column
number, byte offset and the matched line. The default separator
is a colon (`:') and a bar (`|') for multi-line pattern matches,
and a dash (`-') for context lines. See also option
--group-separator.
--split
Split the -Q query TUI screen on startup.
--sort[=KEY]
Displays matching files in the order specified by KEY in recursive
searches. Normally the ug command sorts by name whereas the ugrep
batch command displays matches in no particular order to improve
performance. The sort KEY can be `name' to sort by pathname
(default), `best' to sort by best match with option -Z (sort by
best match requires two passes over files, which is expensive),
`size' to sort by file size, `used' to sort by last access time,
`changed' to sort by last modification time and `created' to sort
by creation time. Sorting is reversed with `rname', `rbest',
`rsize', `rused', `rchanged', or `rcreated'. Archive contents are
not sorted. Subdirectories are sorted and displayed after
matching files. FILE arguments are searched in the same order as
specified.
--stats
Output statistics on the number of files and directories searched
and the inclusion and exclusion constraints applied.
-T, --initial-tab
Add a tab space to separate the file name, line number, column
number and byte offset with the matched line.
-t TYPES, --file-type=TYPES
Search only files associated with TYPES, a comma-separated list of
file types. Each file type corresponds to a set of filename
extensions passed to option -O and filenames passed to option -g.
For capitalized file types, the search is expanded to include
files with matching file signature magic bytes, as if passed to
option -M. When a type is preceded by a `!' or a `^', excludes
files of the specified type. Specifying the initial part of a
type name suffices when the choice is unambiguous. This option
may be repeated. The possible file types can be (-tlist displays
a list): `actionscript', `ada', `asm', `asp', `aspx', `autoconf',
`automake', `awk', `Awk', `basic', `batch', `bison', `c', `c++',
`clojure', `cpp', `csharp', `css', `csv', `dart', `Dart',
`delphi', `elisp', `elixir', `erlang', `fortran', `gif', `Gif',
`go', `groovy', `gsp', `haskell', `html', `jade', `java', `jpeg',
`Jpeg', `js', `json', `jsp', `julia', `kotlin', `less', `lex',
`lisp', `lua', `m4', `make', `markdown', `matlab', `node', `Node',
`objc', `objc++', `ocaml', `parrot', `pascal', `pdf', `Pdf',
`perl', `Perl', `php', `Php', `png', `Png', `prolog', `python',
`Python', `r', `rpm', `Rpm', `rst', `rtf', `Rtf', `ruby', `Ruby',
`rust', `scala', `scheme', `shell', `Shell', `smalltalk', `sql',
`svg', `swift', `tcl', `tex', `text', `tiff', `Tiff', `tt',
`typescript', `verilog', `vhdl', `vim', `xml', `Xml', `yacc',
`yaml', `zig'.
--tabs[=NUM]
Set the tab size to NUM to expand tabs for option -k. The value
of NUM may be 1 (no expansion), 2, 4, or 8. The default size is
8.
--tag[=TAG[,END]]
Disables colors to mark up matches with TAG. END marks the end of
a match if specified, otherwise TAG. The default is `___'.
--tree, -^
Output directories with matching files in a tree-like format for
option -c or --count, -l or --files-with-matches, -L or
--files-without-match. This option is enabled by --pretty when
the output is sent to a terminal.
-U, --ascii, --binary
Disables Unicode matching for ASCII and binary matching. PATTERN
matches bytes, not Unicode characters. For example, -U 'xa3'
matches byte A3 (hex) instead of the Unicode code point U+00A3
represented by the UTF-8 sequence C2 A3. See also option
--dotall.
-u, --ungroup
Do not group multiple pattern matches on the same matched line.
Output the matched line again for each additional pattern match.
-V, --version
Display version with linked libraries and exit.
-v, --invert-match
Selected lines are those not matching any of the specified
patterns.
--view[=COMMAND]
Use COMMAND to view/edit a file in -Q query TUI by pressing
CTRL-Y.
-W, --with-hex
Output binary matches in hexadecimal, leaving text matches alone.
This option is equivalent to the --binary-files=with-hex option.
To omit the matching line from the hex output, use both options -W
and --hexdump. See also options -U.
-w, --word-regexp
The PATTERN is searched for as a word, such that the matching text
is preceded by a non-word character and is followed by a non-word
character. Word-like characters are Unicode letters, digits and
connector punctuations such as underscore.
--width[=NUM]
Truncate the output to NUM visible characters per line. The width
of the terminal window is used if NUM is not specified. Note that
double wide characters in the output may result in wider lines.
-X, --hex
Output matches and matching lines in hexadecimal. This option is
equivalent to the --binary-files=hex option. To omit the matching
line from the hex output use option --hexdump. See also option
-U.
-x, --line-regexp
Select only those matches that exactly match the whole line, as if
the patterns are surrounded by ^ and $.
--xml Output file matches in XML. If -H, -n, -k, or -b is specified,
additional values are output. See also options --format and -u.
-Y, --empty
Permits empty matches. By default, empty matches are disabled,
unless a pattern begins with `^' or ends with `$'. With this
option, empty-matching patterns such as x? and x*, match all
input, not only lines containing the character `x'.
-y, --any-line, --passthru
Any line is output (passthru). Non-matching lines are output as
context with a `-' separator. See also options -A, -B and -C.
-Z[best][+-~][MAX], --fuzzy[=[best][+-~][MAX]]
Fuzzy mode: report approximate pattern matches within MAX errors.
The default is -Z1: one deletion, insertion or substitution is
allowed. If `+`, `-' and/or `~' is specified, then `+' allows
insertions, `-' allows deletions and `~' allows substitutions.
For example, -Z+~3 allows up to three insertions or substitutions,
but no deletions. If `best' is specified, then only the best
matching lines are output with the lowest cost per file. Option
-Zbest requires two passes over a file and cannot be used with
standard input or Boolean queries. Option --sort=best orders
matching files by best match. The first character of an
approximate match always matches a character at the beginning of
the pattern. To fuzzy match the first character, replace it with
a `.' or `.?'. Option -U applies fuzzy matching to ASCII and
bytes instead of Unicode text. No whitespace may be given between
-Z and its argument.
-z, --decompress
Search compressed files and archives. Archives (.cpio, .pax,
.tar) and compressed archives (e.g. .zip, .7z, .taz, .tgz, .tpz,
.tbz, .tbz2, .tb2, .tz2, .tlz, .txz, .tzst) are searched and
matching pathnames of files in archives are output in braces.
When used with option --zmax=NUM, searches the contents of
compressed files and archives stored within archives up to NUM
levels. If -g, -O, -M, or -t is specified, searches files stored
in archives whose filenames match globs, match filename
extensions, match file signature magic bytes, or match file types,
respectively. Supported compression formats: gzip (.gz), compress
(.Z), zip, 7z, bzip2 (requires suffix .bz, .bz2, .bzip2, .tbz,
.tbz2, .tb2, .tz2), lzma and xz (requires suffix .lzma, .tlz, .xz,
.txz), lz4 (requires suffix .lz4), zstd (requires suffix .zst,
.zstd, .tzst), brotli (requires suffix .br).
--zmax=NUM
When used with option -z (--decompress), searches the contents of
compressed files and archives stored within archives by up to NUM
expansion stages. The default --zmax=1 only permits searching
uncompressed files stored in cpio, pax, tar, zip and 7z archives;
compressed files and archives are detected as binary files and are
effectively ignored. Specify --zmax=2 to search compressed files
and archives stored in cpio, pax, tar, zip and 7z archives. NUM
may range from 1 to 99 for up to 99 decompression and de-archiving
steps. Increasing NUM values gradually degrades performance.
-0, --null
Output a zero-byte (NUL) after the file name. This option can be
used with commands such as `find -print0' and `xargs -0' to
process arbitrary file names.
EXIT STATUS
The ugrep utility exits with one of the following values:
0 One or more lines were selected.
1 No lines were selected.
>1 An error occurred.
If -q or --quiet or --silent is used and a line is selected, the exit
status is 0 even if an error occurred.
CONFIGURATION
The ug command is intended for context-dependent interactive searching
and is equivalent to the ugrep --config --pretty --sort command to load
the default configuration file `.ugrep' when present in the working
directory or in the home directory.
A configuration file contains `NAME=VALUE' pairs per line, where `NAME`
is the name of a long option (without `--') and `=VALUE' is an argument,
which is optional and may be omitted depending on the option. Empty
lines and lines starting with a `#' are ignored.
The --config=FILE option and its abbreviated form ---FILE load the
specified configuration file located in the working directory or, when
not found, located in the home directory. An error is produced when FILE
is not found or cannot be read.
Command line options are parsed in the following order: the configuration
file is loaded first, followed by the remaining options and arguments on
the command line.
The --save-config option saves a `.ugrep' configuration file to the
working directory with a subset of the options specified on the command
line. The --save-config=FILE option saves the configuration to FILE.
The configuration is written to standard output when FILE is a `-'.
GLOBBING
Globbing is used by options -g, --include, --include-dir, --include-from,
--exclude, --exclude-dir, --exclude-from and --ignore-files to match
pathnames and basenames in recursive searches. Glob arguments for these
options should be quoted to prevent shell globbing.
Globbing supports gitignore syntax and the corresponding matching rules,
except that a glob normally matches files but not directories. If a glob
ends in a path separator `/', then it matches directories but not files,
as if --include-dir or --exclude-dir is specified. When a glob contains
a path separator `/', the full pathname is matched. Otherwise the
basename of a file or directory is matched. For example, *.h matches
foo.h and bar/foo.h. bar/*.h matches bar/foo.h but not foo.h and not
bar/bar/foo.h. Use a leading `/' to force /*.h to match foo.h but not
bar/foo.h.
When a glob starts with a `^' or a `!' as in -g^GLOB, the match is
negated. Likewise, a `!' (but not a `^') may be used with globs in the
files specified --include-from, --exclude-from, and --ignore-files to
negate the glob match. Empty lines or lines starting with a `#' are
ignored.
Glob Syntax and Conventions
* Matches anything except /.
? Matches any one character except /.
[abc-e]
Matches one character a,b,c,d,e.
[^abc-e]
Matches one character not a,b,c,d,e,/.
[!abc-e]
Matches one character not a,b,c,d,e,/.
/ When used at the start of a glob, matches if pathname has no /.
When used at the end of a glob, matches directories only.
**/ Matches zero or more directories.
/** When used at the end of a glob, matches everything after the /.
? Matches a ? or any other character specified after the backslash.
Glob Matching Examples
* Matches a, b, x/a, x/y/b
a Matches a, x/a, x/y/a, but not b, x/b, a/a/b
/* Matches a, b, but not x/a, x/b, x/y/a
/a Matches a, but not x/a, x/y/a
a?b Matches axb, ayb, but not a, b, ab, a/b
a[xy]b Matches axb, ayb but not a, b, azb
a[a-z]b
Matches aab, abb, acb, azb, but not a, b, a3b, aAb, aZb
a[^xy]b
Matches aab, abb, acb, azb, but not a, b, axb, ayb
a[^a-z]b
Matches a3b, aAb, aZb but not a, b, aab, abb, acb, azb
a/*/b Matches a/x/b, a/y/b, but not a/b, a/x/y/b
**/a Matches a, x/a, x/y/a, but not b, x/b.
a/**/b Matches a/b, a/x/b, a/x/y/b, but not x/a/b, a/b/x
a/** Matches a/x, a/y, a/x/y, but not a, b/x
a?b Matches a?b, but not a, b, ab, axb, a/b
Note that exclude glob patterns take priority over include glob patterns
when specified with options -g, --exclude, --exclude-dir, --include and
include-dir.
Glob patterns specified with prefix `!' in any of the files associated
with --include-from, --exclude-from and --ignore-files will negate a
previous glob match. That is, any matching file or directory excluded by
a previous glob pattern specified in the files associated with --exclude-
from or --ignore-file will become included again. Likewise, any matching
file or directory included by a previous glob pattern specified in the
files associated with --include-from will become excluded again.
ENVIRONMENT
GREP_PATH
May be used to specify a file path to pattern files. The file
path is used by option -f to open a pattern file, when the pattern
file does not exist.
GREP_COLOR
May be used to specify ANSI SGR parameters to highlight matches
when option --color is used, e.g. 1;35;40 shows pattern matches in
bold magenta text on a black background. Deprecated in favor of
GREP_COLORS, but still supported.
GREP_COLORS
May be used to specify ANSI SGR parameters to highlight matches
and other attributes when option --color is used. Its value is a
colon-separated list of ANSI SGR parameters that defaults to
cx=33:mt=1;31:fn=1;35:ln=1;32:cn=1;32:bn=1;32:se=36 with
additional parameters for TUI colors
:qp=1;32:qe=1;37;41:qm=1;32:ql=36:qb=1;35. The mt=, ms=, and mc=
capabilities of GREP_COLORS take priority over GREP_COLOR. Option
--colors takes priority over GREP_COLORS.
GREP_COLORS
Colors are specified as string of colon-separated ANSI SGR parameters of
the form `what=substring', where `substring' is a semicolon-separated
list of ANSI SGR codes or `k' (black), `r' (red), `g' (green), `y'
(yellow), `b' (blue), `m' (magenta), `c' (cyan), `w' (white). Upper case
specifies background colors. A `+' qualifies a color as bright. A
foreground and a background color may be combined with one or more font
properties `n' (normal), `f' (faint), `h' (highlight), `i' (invert), `u'
(underline). Substrings may be specified for:
sl= selected lines.
cx= context lines.
rv swaps the sl= and cx= capabilities when -v is specified.
mt= matching text in any matching line.
ms= matching text in a selected line. The substring mt= by default.
mc= matching text in a context line. The substring mt= by default.
fn= filenames.
ln= line numbers.
cn= column numbers.
bn= byte offsets.
se= separators.
rv a Boolean parameter, switches sl= and cx= with option -v.
hl a Boolean parameter, enables filename hyperlinks (33]8;;link).
ne a Boolean parameter, disables ``erase in line'' 33[K.
qp= TUI prompt.
qe= TUI errors.
qr= TUI regex.
qm= TUI regex meta characters.
ql= TUI regex lists and literals.
qb= TUI regex braces.
FORMAT
Option --format=FORMAT specifies an output format for file matches.
Fields may be used in FORMAT, which expand into the following values:
%[TEXT]F
if option -H is used: TEXT, the file pathname and separator.
%f the file pathname.
%a the file basename without directory path.
%p the directory path to the file.
%z the file pathname in a (compressed) archive.
%[TEXT]H
if option -H is used: TEXT, the quoted pathname and separator, "
and \ replace " and .
%h the quoted file pathname, " and \ replace " and .
%[TEXT]I
if option -H is used: TEXT, the pathname as XML character data and
separator.
%i the file pathname as XML character data.
%[TEXT]N
if option -n is used: TEXT, the line number and separator.
%n the line number of the match.
%[TEXT]K
if option -k is used: TEXT, the column number and separator.
%k the column number of the match.
%[TEXT]B
if option -b is used: TEXT, the byte offset and separator.
%b the byte offset of the match.
%[TEXT]T
if option -T is used: TEXT and a tab character.
%t a tab character.
%[SEP]$
set field separator to SEP for the rest of the format fields.
%[TEXT]<
if the first match: TEXT.
%[TEXT]>
if not the first match: TEXT.
%, if not the first match: a comma, same as %[,]>.
%: if not the first match: a colon, same as %[:]>.
%; if not the first match: a semicolon, same as %[;]>.
%| if not the first match: a vertical bar, same as %[|]>.
%[TEXT]S
if not the first match: TEXT and separator, see also %[SEP]$.
%s the separator, see also %[TEXT]S and %[SEP]$.
%~ a newline character.
%M the number of matching lines
%m the number of matches
%O the matching line is output as a raw string of bytes.
%o the match is output as a raw string of bytes.
%Q the matching line as a quoted string, " and \ replace " and .
%q the match as a quoted string, " and \ replace " and .
%C the matching line formatted as a quoted C/C++ string.
%c the match formatted as a quoted C/C++ string.
%J the matching line formatted as a quoted JSON string.
%j the match formatted as a quoted JSON string.
%V the matching line formatted as a quoted CSV string.
%v the match formatted as a quoted CSV string.
%X the matching line formatted as XML character data.
%x the match formatted as XML character data.
%w the width of the match, counting wide characters.
%d the size of the match, counting bytes.
%e the ending byte offset of the match.
%Z the edit distance cost of an approximate match with option -Z
%u select unique lines only, unless option -u is used.
%1 the first regex group capture of the match, and so on up to group
%9, same as %[1]#; requires option -P.
%[NUM]#
the regex group capture NUM; requires option -P.
%[NUM]b
the byte offset of the group capture NUM; requires option -P. Use
e for the ending byte offset and d for the byte length.
%[NUM1|NUM2|...]#
the first group capture NUM that matched; requires option -P.
%[NUM1|NUM2|...]b
the byte offset of the first group capture NUM that matched;
requires option -P. Use e for the ending byte offset and d for
the byte length.
%[NAME]#
the NAMEd group capture; requires option -P and capturing pattern
`(?<NAME>PATTERN)', see also %G.
%[NAME]b
the byte offset of the NAMEd group capture; requires option -P and
capturing pattern `(?<NAME>PATTERN)'. Use e for the ending byte
offset and d for the byte length.
%[NAME1|NAME2|...]#
the first NAMEd group capture that matched; requires option -P and
capturing pattern `(?<NAME>PATTERN)', see also %G.
%[NAME1|NAME2|...]b
the byte offset of the first NAMEd group capture that matched;
requires option -P and capturing pattern `(?<NAME>PATTERN)'. Use
e for the ending byte offset and d for the byte length.
%G list of group capture indices/names that matched; requires option
-P.
%[TEXT1|TEXT2|...]G
list of TEXT indexed by group capture indices that matched;
requires option -P.
%g the group capture index/name matched or 1; requires option -P.
%[TEXT1|TEXT2|...]g
the first TEXT indexed by the first group capture index that
matched; requires option -P.
%% the percentage sign.
Formatted output is written without a terminating newline, unless %~ or
`n' is explicitly specified in the format string.
The [TEXT] part of a field is optional and may be omitted. When present,
the argument must be placed in [] brackets, for example %[,]F to output a
comma, the pathname, and a separator.
%[SEP]$ and %u are switches and do not send anything to the output.
The separator used by the %F, %H, %I, %N, %K, %B, %S and %G fields may be
changed by preceding the field by %[SEP]$. When [SEP] is not provided,
this reverts the separator to the default separator or the separator
specified with --separator.
Formatted output is written for each matching pattern, which means that a
line may be output multiple times when patterns match more than once on
the same line. If field %u is specified anywhere in a format string,
matching lines are output only once, unless option -u, --ungroup is
specified or when more than one line of input matched the search pattern.
Additional formatting options:
--format-begin=FORMAT
the FORMAT when beginning the search.
--format-open=FORMAT
the FORMAT when opening a file and a match was found.
--format-close=FORMAT
the FORMAT when closing a file and a match was found.
--format-end=FORMAT
the FORMAT when ending the search.
The context options -A, -B, -C, -y, and display options --break,
--heading, --color, -T, and --null have no effect on formatted output.
EXAMPLES
Display lines containing the word `patricia' in `myfile.txt':
$ ugrep -w patricia myfile.txt
Display lines containing the word `patricia', ignoring case:
$ ugrep -wi patricia myfile.txt
Display lines approximately matching the word `patricia', ignoring case
and allowing up to 2 spelling errors using fuzzy search:
$ ugrep -Z2 -wi patricia myfile.txt
Count the number of lines containing `patricia', ignoring case:
$ ugrep -cwi patricia myfile.txt
Count the number of words `patricia', ignoring case:
$ ugrep -cowi patricia myfile.txt
List lines with `amount' and a decimal, ignoring case (space is AND):
$ ugrep -i -% 'amount +(.+)?' myfile.txt
Alternative query:
$ ugrep -wi -e amount --and '+(.+)?' myfile.txt
List all Unicode words in a file:
$ ugrep -o 'w+' myfile.txt
List the laughing face emojis (Unicode code points U+1F600 to U+1F60F):
$ ugrep -o '[x{1F600}-x{1F60F}]' myfile.txt
Check if a file contains any non-ASCII (i.e. Unicode) characters:
$ ugrep -q '[^[:ascii:]]' myfile.txt && echo "contains Unicode"
Display the line and column number of `FIXME' in C++ files using
recursive search, with one line of context before and after a matched
line:
$ ugrep -C1 -R -n -k -tc++ FIXME
Display the line and column number of `FIXME' in long Javascript files
using recursive search, showing only matches with up to 10 characters of
context before and after:
$ ugrep -o -C20 -R -n -k -tjs FIXME
Find blocks of text between lines matching BEGIN and END by using a lazy
quantifier `*?' to match only what is necessary and pattern `n' to match
newlines:
$ ugrep -n 'BEGIN.*n(.*n)*?.*END' myfile.txt
Likewise, list the C/C++ comments in a file and line numbers:
$ ugrep -n -e '//.*' -e '/*(.*n)*?.**+/' myfile.cpp
The same, but using predefined pattern c++/comments:
$ ugrep -n -f c++/comments myfile.cpp
List the lines that need fixing in a C/C++ source file by looking for the
word `FIXME' while skipping any `FIXME' in quoted strings:
$ ugrep -e FIXME -N '"(\.|\r?n|[^\n"])*"' myfile.cpp
The same, but using predefined pattern cpp/zap_strings:
$ ugrep -e FIXME -f cpp/zap_strings myfile.cpp
Find lines with `FIXME' or `TODO', showing line numbers:
$ ugrep -n -e FIXME -e TODO myfile.cpp
Find lines with `FIXME' that also contain `urgent':
$ ugrep -n -e FIXME --and urgent myfile.cpp
The same, but with a Boolean query pattern (a space is AND):
$ ugrep -n -% 'FIXME urgent' myfile.cpp
Find lines with `FIXME' that do not also contain `later':
$ ugrep -n -e FIXME --andnot later myfile.cpp
The same, but with a Boolean query pattern (a space is AND, - is NOT):
$ ugrep -n -% 'FIXME -later' myfile.cpp
Output a list of line numbers of lines with `FIXME' but not `later':
$ ugrep -e FIXME --andnot later --format='%,%n' myfile.cpp
Recursively list all files with both `FIXME' and `LICENSE' anywhere in
the file, not necessarily on the same line:
$ ugrep -l -%% 'FIXME LICENSE'
Find lines with `FIXME' in the C/C++ files stored in a tarball:
$ ugrep -z -tc++ -n FIXME project.tgz
Recursively find lines with `FIXME' in C/C++ files, but do not search any
`bak' and `old' directories:
$ ugrep -n FIXME -tc++ -g^bak/,^old/
Recursively search for the word `copyright' in cpio, jar, pax, tar, zip,
7z archives, compressed and regular files, and in PDFs using a PDF
filter:
$ ugrep -z -w --filter='pdf:pdftotext % -' copyright
Match the binary pattern `A3hhhhA3' (hex) in a binary file without
Unicode pattern matching -U (which would otherwise match `xaf' as a
Unicode character U+00A3 with UTF-8 byte sequence C2 A3) and display the
results in hex with --hexdump with C1 to output one hex line before and
after each match:
$ ugrep -U --hexdump=C1 'xa3[x00-xff]{2}xa3' a.out
Hexdump an entire file using a pager for viewing:
$ ugrep -X --pager '' a.out
List all files that are not ignored by one or more `.gitignore':
$ ugrep -l '' --ignore-files
List all files containing a RPM signature, located in the `rpm' directory
and recursively below up to two levels deeper (3 levels total):
$ ugrep -3 -l -tRpm '' rpm/
Monitor the system log for bug reports and ungroup multiple matches on a
line:
$ tail -f /var/log/system.log | ugrep -u -i -w bug
Interactive fuzzy search with Boolean search queries:
$ ugrep -Q -l -% -Z3 --sort=best
Display all words in a MacRoman-encoded file that has CR newlines:
$ ugrep --encoding=MACROMAN 'w+' mac.txt
Display options related to "fuzzy" searching:
$ ugrep --help fuzzy
COPYRIGHT
Copyright (c) 2021,2024 Robert A. van Engelen <[email protected]>
ugrep is released under the BSD-3 license. All parts of the software
have reasonable copyright terms permitting free redistribution. This
includes the ability to reuse all or parts of the ugrep source tree.
SEE ALSO
ugrep-indexer(1), grep(1), zgrep(1).
BUGS
Report bugs at: <https://github.com/Genivia/ugrep/issues>
ugrep 7.1.1 November 29, 2024 UGREP(1)
？返回目录
For PCRE regex patterns with option -P , please see the PCRE documentation https://www.pcre.org/original/doc/html/pcrepattern.html. The pattern syntax has more features than the pattern syntax described below. For the patterns in common the syntax and meaning are the same.
Note that [[:space:]] and s and inverted bracket lists [^...] are modified in ugrep to prevent matching newlines n . This modification is done to replicate the behavior of grep.
An empty pattern is a special case that matches everything except empty files, ie does not match zero-length files, as per POSIX.1 grep standard.
A regex pattern is an extended set of regular expressions (ERE), with nested sub-expression patterns φ and ψ :
| 图案 | 火柴 |
|---|---|
x | matches the character x , where x is not a special character |
. | matches any single character except newline (unless in dotall mode) |
. | 匹配. (dot), special characters are escaped with a backslash |
n | matches a newline, others are a (BEL), b (BS), t (HT), v (VT), f (FF), and r (CR) |
| matches the NUL character |
cX | matches the control character X mod 32 (eg cA is x01 ) |
141 | matches an 8-bit character with octal value 141 , ie a |
x7f | matches an 8-bit character with hexadecimal value 7f |
x{3B1} | matches Unicode character U+03B1, ie α |
u{3B1} | matches Unicode character U+03B1, ie α |
o{141} | matches Unicode character U+0061, ie a , in octal |
p{C} | matches a character in Unicode category C |
Q...E | matches the quoted content between Q and E literally |
[abc] | matches one of a , b , or c |
[0-9] | matches a digit 0 to 9 |
[^0-9] | matches any character except a digit and excluding n |
φ? | matches φ zero or one time (optional) |
φ* | matches φ zero or more times (repetition) |
φ+ | matches φ one or more times (repetition) |
φ{2,5} | matches φ two to five times (repetition) |
φ{2,} | matches φ at least two times (repetition) |
φ{2} | matches φ exactly two times (repetition) |
φ?? | matches φ zero or once as needed (lazy optional) |
φ*? | matches φ a minimum number of times as needed (lazy repetition) |
φ+? | matches φ a minimum number of times at least once as needed (lazy repetition) |
φ{2,5}? | matches φ two to five times as needed (lazy repetition) |
φ{2,}? | matches φ at least two times or more as needed (lazy repetition) |
φψ | matches φ then matches ψ (concatenation) |
φ⎮ψ | matches φ or matches ψ (alternation) |
(φ) | matches φ as a group |
(?:φ) | matches φ as a group without capture |
(?=φ) | matches φ without consuming it, ie lookahead (without option -P : nothing may occur after (?=φ) ) |
(?^φ) | matches φ and ignores it, marking everything in the pattern as a non-match |
^φ | matches φ at the start of input or start of a line (nothing may occur before ^ ) |
φ$ | matches φ at the end of input or end of a line (nothing may occur after $ ) |
Aφ | matches φ at the start of input (nothing may occur before A ) |
φz | matches φ at the end of input (nothing may occur after z ) |
bφ | matches φ starting at a word boundary (without option -P : nothing may occur before b ) |
φb | matches φ ending at a word boundary (without option -P : nothing may occur after b ) |
Bφ | matches φ starting at a non-word boundary (without option -P : nothing may occur before B ) |
φB | matches φ ending at a non-word boundary (without option -P : nothing may occur after B ) |
<φ | matches φ that starts a word (without option -P : nothing may occur before < ) |
>φ | matches φ that starts a non-word (without option -P : nothing may occur before > ) |
φ< | matches φ that ends a non-word (without option -P : nothing may occur after < ) |
φ> | matches φ that ends a word (without option -P : nothing may occur after > ) |
(?i:φ) | matches φ ignoring case |
(?s:φ) | . (dot) in φ matches newline |
(?x:φ) | ignore all whitespace and comments in φ |
(?#:X) | all of X is skipped as a comment |
The order of precedence for composing larger patterns from sub-patterns is as follows, from high to low precedence:
(φ) , (?:φ) , (?=φ) , and inline modifiers (?imsux:φ)? , * , + , {n,m}φψ^ , $ , < , > , b , B , A , zφ|ψ(?imsux)φ？返回目录
Character classes in bracket lists represent sets of characters. Sets can be negated (inverted), subtracted, intersected, and merged (not supported by PCRE2 with option -P ):
| 图案 | 火柴 |
|---|---|
[a-zA-Z] | matches a letter |
[^a-zA-Z] | matches a non-letter (character class negation), newlines are not matched |
[az−−[aeiou]] | matches a consonant (character class subtraction) |
[az&&[^aeiou]] | matches a consonant (character class intersection) |
[az⎮⎮[AZ]] | matches a letter (character class union) |
Bracket lists cannot be empty, so [] and [^] are invalid. In fact, the first character after the bracket is always part of the list. So [][] is a list that matches a ] and a [ , [^][] is a list that matches anything but ] and [ , and [-^] is a list that matches a - and a ^ .
Negated character classes such as [^az] do not match newlines for compatibility with traditional grep pattern matching.
？返回目录
The POSIX form can only be used in bracket lists, for example [[:lower:][:digit:]] matches an ASCII lower case letter or a digit.
You can also use the p{C} form for class C and upper case P{C} form that has the same meaning as p{^C} , which matches any character except characters in the class C . For example, P{ASCII} is the same as p{^ASCII} which is the same as [[:^ascii]] .
| POSIX form | 火柴 |
|---|---|
[:ascii:] | matches an ASCII character U+0000 to U+007F including n |
[:space:] | matches a white space character [ tvfr] excluding n |
[:xdigit:] | matches a hex digit [0-9A-Fa-f] |
[:cntrl:] | matches a control character [x00-tx0b-x1fx7f] excluding n |
[:print:] | matches a printable character [x20-x7e] |
[:alnum:] | matches a alphanumeric character [0-9A-Za-z] |
[:alpha:] | matches a letter [A-Za-z] |
[:blank:] | matches a blank character h same as [ t] |
[:digit:] | matches a digit [0-9] |
[:graph:] | matches a visible character [x21-x7e] |
[:lower:] | matches a lower case letter [az] |
[:punct:] | matches a punctuation character [x21-x2fx3a-x40x5b-x60x7b-x7e] |
[:upper:] | matches an upper case letter [AZ] |
[:word:] | matches a word character [0-9A-Za-z_] |
[:^blank:] | matches a non-blank characater H same as [^ t] |
[:^digit:] | matches a non-digit [^0-9] |
POSIX character categories only cover ASCII, [[:^ascii]] is empty and therefore invalid to use. By contrast, [^[:ascii]] is a Unicode character class that excludes the ASCII character category.
Note that the patterns [[:ascii:]] and negated classes such as [[:^digit:]] match newlines, which is the official definition of these POSIX categories. By contrast, GNU/BSD grep never match newlines. As a consequence, more patterns may match.
Negated character classes of the form [^...] match any Unicode character except the given characters and does not match newlines either. For example [^[:digit:]] matches non-digits (including Unicode) and does not match newlines. By contrast, [[:^digit:]] matches ASCII non-digits, including newlines.
Option -U disables Unicode wide-character matching, ie ASCII matching.
| Unicode category | 火柴 |
|---|---|
. | matches any single Unicode character except newline n unless with --dotall |
a | matches BEL U+0007 |
d | matches a digit [0-9] or p{Nd} |
D | matches a non-digit including n |
e | matches ESC U+001b |
f | matches FF U+000c |
h | matches a blank [ t] |
H | matches a non-blank [^ t] including n |
l | matches a lower case letter p{Ll} |
n | matches LF U+000a |
N | matches a non-LF character |
r | matches CR U+000d |
R | matches a Unicode line break ( rn , r , v , f , n , U+0085, U+2028 and U+2029) |
s | matches a white space character [ tvfrx85p{Z}] excluding n |
S | matches a non-white space character and excluding n |
t | matches TAB U+0009 |
u | matches an upper case letter p{Lu} |
v | matches VT U+000b or vertical space character with option -P |
w | matches a word character [0-9A-Za-z_] or [p{L}p{Nd}p{Pc}] |
W | matches a non-Unicode word character including n |
X | matches any ISO-8859-1 or Unicode character including n |
p{Space} | matches a white space character [ tvfrx85p{Z}] excluding n |
p{Unicode} | matches any Unicode character U+0000 to U+10FFFF minus U+D800 to U+DFFF |
p{ASCII} | matches an ASCII character U+0000 to U+007F including n |
p{Non_ASCII_Unicode} | matches a non-ASCII character U+0080 to U+10FFFF minus U+D800 to U+DFFF |
p{L&} | matches a character with Unicode property L& (ie property Ll, Lu, or Lt) |
p{Letter} , p{L} | matches a character with Unicode property Letter |
p{Mark} , p{M} | matches a character with Unicode property Mark |
p{Separator} , p{Z} | matches a character with Unicode property Separator |
p{Symbol} , p{S} | matches a character with Unicode property Symbol |
p{Number} , p{N} | matches a character with Unicode property Number |
p{Punctuation} , p{P} | matches a character with Unicode property Punctuation |
p{Other} , p{C} | matches a character with Unicode property Other |
p{Lowercase_Letter} , p{Ll} | matches a character with Unicode sub-property Ll |
p{Uppercase_Letter} , p{Lu} | matches a character with Unicode sub-property Lu |
p{Titlecase_Letter} , p{Lt} | matches a character with Unicode sub-property Lt |
p{Modifier_Letter} , p{Lm} | matches a character with Unicode sub-property Lm |
p{Other_Letter} , p{Lo} | matches a character with Unicode sub-property Lo |
p{Non_Spacing_Mark} , p{Mn} | matches a character with Unicode sub-property Mn |
p{Spacing_Combining_Mark} , p{Mc} | matches a character with Unicode sub-property Mc |
p{Enclosing_Mark} , p{Me} | matches a character with Unicode sub-property Me |
p{Space_Separator} , p{Zs} | matches a character with Unicode sub-property Zs |
p{Line_Separator} , p{Zl} | matches a character with Unicode sub-property Zl |
p{Paragraph_Separator} , p{Zp} | matches a character with Unicode sub-property Zp |
p{Math_Symbol} , p{Sm} | matches a character with Unicode sub-property Sm |
p{Currency_Symbol} , p{Sc} | matches a character with Unicode sub-property Sc |
p{Modifier_Symbol} , p{Sk} | matches a character with Unicode sub-property Sk |
p{Other_Symbol} , p{So} | matches a character with Unicode sub-property So |
p{Decimal_Digit_Number} , p{Nd} | matches a character with Unicode sub-property Nd |
p{Letter_Number} , p{Nl} | matches a character with Unicode sub-property Nl |
p{Other_Number} , p{No} | matches a character with Unicode sub-property No |
p{Dash_Punctuation} , p{Pd} | matches a character with Unicode sub-property Pd |
p{Open_Punctuation} , p{Ps} | matches a character with Unicode sub-property Ps |
p{Close_Punctuation} , p{Pe} | matches a character with Unicode sub-property Pe |
p{Initial_Punctuation} , p{Pi} | matches a character with Unicode sub-property Pi |
p{Final_Punctuation} , p{Pf} | matches a character with Unicode sub-property Pf |
p{Connector_Punctuation} , p{Pc} | matches a character with Unicode sub-property Pc |
p{Other_Punctuation} , p{Po} | matches a character with Unicode sub-property Po |
p{Control} , p{Cc} | matches a character with Unicode sub-property Cc |
p{Format} , p{Cf} | matches a character with Unicode sub-property Cf |
p{UnicodeIdentifierStart} | matches a character in the Unicode IdentifierStart class |
p{UnicodeIdentifierPart} | matches a character in the Unicode IdentifierPart class |
p{IdentifierIgnorable} | matches a character in the IdentifierIgnorable class |
p{JavaIdentifierStart} | matches a character in the Java IdentifierStart class |
p{JavaIdentifierPart} | matches a character in the Java IdentifierPart class |
p{CsIdentifierStart} | matches a character in the C# IdentifierStart class |
p{CsIdentifierPart} | matches a character in the C# IdentifierPart class |
p{PythonIdentifierStart} | matches a character in the Python IdentifierStart class |
p{PythonIdentifierPart} | matches a character in the Python IdentifierPart class |
To specify a Unicode block as a category use p{IsBlockName} with a Unicode BlockName .
To specify a Unicode language script, use p{Language} with a Unicode Language .
Unicode language script character classes differ from the Unicode blocks that have a similar name. For example, the p{Greek} class represents Greek and Coptic letters and differs from the Unicode block p{IsGreek} that spans a specific Unicode block of Greek and Coptic characters only, which also includes unassigned characters.
？返回目录
For the pattern syntax of ugrep option -P (Perl regular expressions), see for example Perl regular expression syntax. However, ugrep enhances the Perl regular expression syntax with all of the features listed in POSIX regular expression syntax.
？返回目录
If something is not working, then please check the tutorial and the man page. If you can't find it there and it looks like a bug, then report an issue on GitHub. Bug reports are quickly addressed.
Copyright (c) Robert van Engelen, 2024
