ugrep 手册怎么查:命令、选项与正则用法入门

ugrep 官方手册入口在 ugrep.com 首页的导航区，按主题分为 Commands、Options、Regex、Globs、File types 等章节。查手册前先明确你要解决的是“用哪个命令”“加什么选项”“正则怎么写”还是“限定哪些文件”，再直奔对应章节，比从头读更快。本文按这个顺序说明各章节能查到什么，并给出一次从查手册到完成搜索的完整路径。

先分清 ug 和 ugrep：手册里两套命令的差别

手册的 Commands 章节首先区分了 ug 和 ugrep 两个命令，这是查阅时最容易混淆的地方：

如果你在脚本里发现结果和手动执行不一致，先检查是不是把 ug 写成了 ugrep 或反之——差异就来自 .ugrep 配置文件。手册还说明 ug --save-config OPTIONS 可以把当前配置连同相关选项保存为新的 .ugrep 文件，适合把调好的选项固化下来。

按需求定位手册章节

要查选项：Options 章节

Options 章节是手册中篇幅最大的部分，按功能分组列出所有命令行选项。查阅时建议先想清楚输出形态：

• 只要匹配的文件名：查“List matching files”相关选项
• 要显示匹配行及上下文：查“Displaying matches”
• 要结构化输出：手册明确支持 grep 风格输出，以及 JSON、XML、CSV 和自定义格式，对应“Formatted output”部分
• 要控制颜色和排版：查“Colors”“Formatting”

要查正则：Regex 章节

Regex 章节对应三种模式，按你的表达式复杂度选择：

• 扩展正则（Unicode extended regex）：默认语法，覆盖大多数日常需求
• PCRE 语法：需要环视、递归等高级特性时使用
• 多行匹配：手册说明无需特殊命令行选项即可进行多行模式匹配，写法在 Regex 章节内说明

如果一条正则在本机 grep 上能用、在 ugrep 上不行，优先核对是否落入了不同语法模式的差异，而不是怀疑选项写错。

要限定文件范围：Globs 与 File types 章节

Globs 章节讲通配符匹配规则，File types 章节讲按文件类型筛选。两者解决的是“搜哪些文件”而非“搜什么内容”，在搜索大目录时先查这两章能显著缩小范围。手册还提到排除与包含（Exclusions & inclusions）的相关内容，可与这两章配合使用。

要搜特殊文件：Archives、Binary、Indexing 等章节

手册单独设有 Archives & compressed files（支持嵌套的 zip/7z/tar/pax/cpio 及 gz、bz2、xz、zstd、brotli 等压缩格式）、Binary files & devices（含 hexdump）、Indexing（加速冷文件系统搜索）等章节。这些属于进阶能力，日常搜索用不到时不必先读。

一次完整的查阅与搜索流程

以“在当前项目里找出所有包含 TODO 的 Python 文件，并输出为 CSV”为例：

1. 定命令：交互使用选 ug；若要写进脚本选 ugrep。
2. 查文件范围：翻 File types 章节确认 Python 文件类型的写法，或用 Globs 章节的 --include 类通配符规则。
3. 查输出格式：在 Options 的 Formatted output 部分找到 CSV 输出选项。
4. 组合执行：预期结果是终端打印出 CSV 格式的匹配记录，每行含文件路径与匹配内容。
5. 验证：先用不带格式选项的默认输出跑一次，确认匹配数量一致，再切换 CSV 格式，排除是格式选项导致漏匹配。

常见卡点有三个：一是 ug 与 ugrep 混用导致选项行为不同；二是正则写法落入了非预期的语法模式；三是文件范围没限定，在大目录下等待过久——此时应回到 Globs 或 File types 章节收窄条件。

安装与文档获取

手册首页列出了各平台安装方式，例如 macOS 用 brew install ugrep，Debian/Ubuntu 用 apt-get install ugrep，Windows 可用 winget install Genivia.ugrep 或 choco install ugrep，其他 Linux 可下载静态构建，也可从 GitHub 克隆源码后执行 ./build.sh 构建。Alpine 用户注意安装 ugrep-doc 包以获取文档。安装后即可对照手册章节逐项试用选项，遇到具体问题时按“命令 → 选项 → 正则 → 文件范围”的顺序定位章节，通常能在一两章内找到答案。