rg完整中文操作指南

可视化运维管理爱好者2026-05-02 9:28

ripgrep (rg) 完整中文操作指南 v15.1.0

基于 ripgrep 15.1.0 官方文档完整翻译与整理

原项目地址：https://github.com/BurntSushi/ripgrep

目录

  1. 简介
  2. 安装
  3. 基本使用
  4. 递归搜索
  5. 自动过滤
  6. [手动过滤：Glob 模式](#手动过滤：Glob 模式)
  7. 手动过滤：文件类型
  8. 替换功能
  9. 配置文件
  10. 文件编码
  11. 二进制数据处理
  12. 预处理器
  13. 常用选项速查
  14. 正则表达式语法
  15. 输入选项详解
  16. 搜索选项详解
  17. 过滤选项详解
  18. 输出选项详解
  19. 输出模式
  20. 调试与日志
  21. 其他行为选项
  22. 退出状态码
  23. 自动过滤机制详解
  24. 配置文件详解
  25. [Shell 自动补全](#Shell 自动补全)
  26. 注意事项与性能
  27. [常见问题 FAQ](#常见问题 FAQ)

1. 简介

ripgrep (rg) 是一个面向行的递归搜索工具，默认在当前目录下搜索正则表达式模式。ripgrep 会自动遵循 .gitignore 规则，并自动跳过隐藏文件/目录和二进制文件。

为什么选择 ripgrep？

  • 极快：基于 Rust 的正则引擎，使用有限自动机、SIMD 和激进的字面量优化，搜索速度极快
  • 默认智能过滤 ：自动尊重 .gitignore、跳过隐藏文件和二进制文件
  • Unicode 一流支持：默认开启 Unicode，不损失性能
  • PCRE2 可选支持 ：通过 -P 启用环视和反向引用
  • 替换输出 ：支持 --replace 对匹配文本进行替换输出
  • 多编码支持：支持 UTF-8、UTF-16、GBK、EUC-JP、Shift_JIS 等
  • 压缩文件搜索 ：通过 -z 支持 gzip、bzip2、xz 等压缩格式
  • 预处理器 ：通过 --pre 可以搜索 PDF 等非纯文本文件
  • 配置文件 ：通过 RIPGREP_CONFIG_PATH 环境变量持久化配置
  • 跨平台：Windows、macOS、Linux 原生支持

性能对比

与同类工具的基准测试对比（搜索 Linux 内核源码树）：

工具 命令 耗时 相对速度
ripgrep rg -n -w '[A-Z]+_SUSPEND' 0.082s 1.00x
git grep git grep -P -n -w '[A-Z]+_SUSPEND' 0.273s 3.34x
ag ag -w '[A-Z]+_SUSPEND' 0.443s 5.43x
ugrep ugrep -r ... -w '[A-Z]+_SUSPEND' 0.639s 7.82x
GNU grep LC_ALL=C grep -E -r -n ... 0.674s 10.69x

2. 安装

命令行格式

复制代码 
rg [OPTIONS] PATTERN [PATH...]
rg [OPTIONS] -e PATTERN... [PATH...]
rg [OPTIONS] -f PATTERNFILE... [PATH...]
rg [OPTIONS] --files [PATH...]
rg [OPTIONS] --type-list
command | rg [OPTIONS] PATTERN

各平台安装方式

平台 安装命令
Windows (Chocolatey) choco install ripgrep
Windows (Scoop) scoop install ripgrep
Windows (Winget) winget install BurntSushi.ripgrep.MSVC
macOS (Homebrew) brew install ripgrep
MacPorts sudo port install ripgrep
Arch Linux sudo pacman -S ripgrep
Fedora sudo dnf install ripgrep
Debian/Ubuntu sudo apt-get install ripgrep
openSUSE sudo zypper install ripgrep
FreeBSD sudo pkg install ripgrep
Rust (cargo) cargo install ripgrep

也可以从 GitHub Releases 下载预编译二进制文件。Windows 和 Linux 的二进制文件是静态链接的，可直接运行。

3. 基本使用

搜索字面量字符串

bash 复制代码 
rg fast README.md

输出示例：

复制代码 
75:  faster than both.
88:  color and full Unicode support. Unlike GNU grep, `ripgrep` stays fast while
119:### Is it really faster than everything else?

ripgrep 读取文件内容，对每一行进行匹配，匹配成功则打印行号和内容。

使用正则表达式

bash 复制代码 
# 查找 fast 后跟一个或多个单词字符
rg 'fast\w+' README.md

# 查找 fast 后跟零个或多个单词字符
rg 'fast\w*' README.md

正则表达式语法详见：https://docs.rs/regex/1.\*/regex/#syntax

大小写处理

bash 复制代码 
rg -i fast          # 忽略大小写（匹配 fast、FAST、fASt 等）
rg -S fast          # 智能大小写：模式全小写时忽略大小写，否则区分大小写
rg -s fast          # 强制区分大小写（默认行为）

4. 递归搜索

ripgrep 默认就是递归搜索 ，不需要像 grep 那样明确指定 -r。

bash 复制代码 
# 在当前目录递归搜索
rg 'fn write\('

# 等价于
rg 'fn write\(' ./

# 限制到特定目录
rg 'fn write\(' src

# 搜索特定文件
rg 'fn write\(' src/printer.rs

如果不指定路径，ripgrep 默认搜索当前工作目录（./）。

5. 自动过滤

ripgrep 默认会自动跳过以下内容：

  1. 匹配 gitignore 规则的文件/目录 （.gitignore、.ignore、.rgignore）
  2. 隐藏文件和目录 （以 . 开头的名称，Windows 上还包括隐藏属性文件）
  3. 二进制文件 （包含 NUL 字节的文件）
  4. 符号链接（不跟随）

控制过滤行为的标志

标志 作用
--no-ignore 禁用所有 ignore 文件规则
-. / --hidden 搜索隐藏文件和目录
-a / --text 将二进制文件当作文本搜索
-L / --follow 跟随符号链接
-u 禁用 .gitignore（等同于 --no-ignore）
-uu 禁用 .gitignore + 搜索隐藏文件
-uuu 禁用所有过滤，搜索一切（类似 grep -r）
bash 复制代码 
# 快速检测是否被过滤了结果
rg foo -uuu

忽略文件的优先级

从低到高（后面的覆盖前面的）：

  1. --ignore-file 指定的文件
  2. 全局 gitignore（$HOME/.config/git/ignore）
  3. 本地仓库排除规则（.git/info/exclude）
  4. .gitignore
  5. .ignore（优先级高于 .gitignore）
  6. .rgignore（优先级最高）
bash 复制代码 
# 使用 .ignore 文件覆盖 .gitignore 中的规则
# .gitignore 内容: log/
# .ignore 内容: !log/  (白名单，强制搜索 log 目录)

在 Windows/macOS 上启用大小写不敏感

bash 复制代码 
rg --ignore-file-case-insensitive pattern

6. 手动过滤：Glob 模式

通过 -g / --glob 标志手动指定包含或排除的文件：

bash 复制代码 
# 只搜索 .toml 文件
rg clap -g '*.toml'

# 排除 .toml 文件（! 前缀表示排除）
rg clap -g '!*.toml'

# 多个 glob：后面的覆盖前面的
rg clap -g '!*.toml' -g '*.toml'   # 结果：只搜索 *.toml

# 使用花括号替代语法
rg clap -g '*.{rs,toml}'           # 等价于 -g '*.rs' -g '*.toml'

# 搜索特定目录（注意要加 **）
rg foo -g 'src/**'

# 大小写不敏感的 glob
rg foo --iglob '*.RS'              # 匹配 .rs、.RS、.Rs 等
rg foo --glob-case-insensitive -g '*.RS'

7. 手动过滤：文件类型

ripgrep 内置了大量预定义的文件类型，通过 -t / --type 使用：

bash 复制代码 
# 只在 Rust 文件中搜索
rg 'fn run' --type rust
rg 'fn run' -trust          # 简写

# 排除某类型文件
rg clap --type-not rust
rg clap -Trust              # 简写

# 特殊类型 `all`：匹配所有已知类型
rg foo --type all           # 只搜索已知类型的文件

# 查看所有可用的文件类型
rg --type-list

自定义文件类型

bash 复制代码 
# 临时添加
rg --type-add 'web:*.{html,css,js}' -tweb title

# 使用 include 指令组合已有类型
rg --type-add 'src:include:cpp,py,md' -tsrc pattern

# 清除某类型的已有 glob
rg --type-clear rust --type-add 'rust:*.rs' -trust pattern

8. 替换功能

ripgrep 的 -r / --replace 标志可以在输出中替换匹配的文本，但永远不会修改原始文件。

bash 复制代码 
# 基本替换
rg fast README.md -r FAST

# 仅输出匹配部分并替换
rg fast README.md --only-matching -r FAST

# 替换整行（匹配整行后替换）
rg '^.*fast.*$' README.md -r FAST

# 使用捕获组
rg 'fast\s+(\w+)' README.md -r 'fast-$1'

# 使用命名捕获组
rg 'fast\s+(?P<word>\w+)' README.md -r 'fast-$word'

注意 ：如果需要实际修改文件，可以将 ripgrep 与 sed 配合使用：

bash 复制代码 
# GNU sed
rg foo --files-with-matches | xargs sed -i 's/foo/bar/g'

# BSD sed (macOS/FreeBSD)
rg foo --files-with-matches | xargs sed -i '' 's/foo/bar/g'

# 文件名含空格时，使用 NUL 分隔
rg foo --files-with-matches -0 | xargs -0 sed -i 's/foo/bar/g'

9. 配置文件

ripgrep 通过 RIPGREP_CONFIG_PATH 环境变量指定配置文件路径。

配置文件格式

  • 每行一个 shell 参数（去除首尾空格后）
  • 以 # 开头的行视为注释
  • 参数与值可以在同一行（用 = 分隔）或分开两行

示例配置文件 (~/.ripgreprc)

复制代码 
# 限制最大列宽
--max-columns=150
--max-columns-preview

# 添加自定义文件类型
--type-add
web:*.{html,css,js}*

# 默认搜索隐藏文件
--hidden

# 使用 glob 排除 .git
--glob=!.git/*

# 设置颜色
--colors=line:none
--colors=line:style:bold

# 默认智能大小写
--smart-case

覆盖配置

bash 复制代码 
# 命令行参数会覆盖配置文件中的设置
rg --max-columns 0 foo    # 完全禁用列宽限制

# 完全禁用配置文件
rg --no-config foo

10. 文件编码

默认行为 (--encoding auto)

  • 假设所有输入兼容 ASCII（ASCII、latin1、UTF-8 均适用）
  • 对 UTF-8 效果最佳（完整 Unicode 支持）
  • 自动 BOM 嗅探：检测 UTF-16 BOM 并自动转码为 UTF-8
  • 不要求输入必须是有效的 UTF-8，可以搜索任意字节

指定编码

bash 复制代码 
# 指定所有文件为 GBK 编码
rg pattern -E gbk

# 指定所有文件为 Shift_JIS 编码
rg pattern -E shift_jis

# 完全禁用编码处理（搜索原始字节，包括 BOM）
rg pattern -E none

支持的所有编码标签列表：https://encoding.spec.whatwg.org/#concept-encoding-get

在正则中禁用 Unicode

bash 复制代码 
# 让 . 匹配任意字节（而非任意 Unicode 码点）
rg '(?-u:.)'

# 混合使用：Unicode 单词字符 + ASCII 单词字符 + Unicode 单词字符
rg '\w(?-u:\w)\w'

11. 二进制数据处理

ripgrep 对二进制文件有三种处理模式：

默认模式

一旦检测到 NUL 字节（在递归目录遍历中），立即停止搜索该文件。如果已经打印了匹配内容，会发出警告说明搜索提前终止。

二进制模式 (--binary)

继续搜索直到文件末尾或找到匹配（以先到者为准）。找到匹配后打印警告。

文本模式 (-a / --text)

完全禁用二进制检测，将所有文件当作文本搜索。小心：二进制内容可能向终端输出控制字符。

bash 复制代码 
# 搜索二进制文件
rg --binary pattern some-file

# 完全当作文本处理
rg -a pattern some-file

内存映射与二进制检测

  • 使用内存映射时，二进制检测仅在文件前几 KB + 每条匹配行上执行
  • 不使用内存映射时，对所有搜索的字节执行二进制检测
  • 如需一致的二进制检测行为，使用 --no-mmap 禁用内存映射

12. 预处理器

预处理器允许在搜索前对文件内容进行转换，使得搜索 PDF、压缩文件等成为可能。

基本用法

bash 复制代码 
# 使用预处理器脚本
rg --pre ./preprocess 'pattern' file.pdf

预处理器脚本示例（preprocess）：

bash 复制代码 
#!/bin/sh
case "$1" in
*.pdf)
  if [ -s "$1" ]; then
    exec pdftotext - -     # 将 PDF 转为纯文本
  else
    exec cat
  fi
  ;;
*)
  exec cat                 # 非 PDF 文件直接原样输出
  ;;
esac

使用 --pre-glob 减少开销

--pre 会为每个文件启动一个进程，开销很大。通过 --pre-glob 限制只对匹配的文件使用预处理器：

bash 复制代码 
rg --pre ./preprocess --pre-glob '*.pdf' 'pattern'

这样只有 .pdf 文件会调用预处理器，其他文件直接搜索，大幅提升性能。

进阶预处理脚本

bash 复制代码 
#!/bin/sh
case "$1" in
*.pdf)
  if [ -s "$1" ]; then
    exec pdftotext - -
  else
    exec cat
  fi
  ;;
*)
  case $(file "$1") in
  *Zstandard*)
    exec pzstd -cdq
    ;;
  *)
    exec cat
    ;;
  esac
  ;;
esac

13. 常用选项速查

最常用选项

标志 长标志 作用
-i --ignore-case 忽略大小写
-S --smart-case 智能大小写（模式无大写时忽略大小写）
-F --fixed-strings 将模式视为字面量字符串（非正则）
-w --word-regexp 仅匹配整个单词
-x --line-regexp 仅匹配整行
-v --invert-match 反转匹配（显示不匹配的行）
-c --count 显示每个文件的匹配行数
-l --files-with-matches 只显示有匹配的文件路径
--files-without-match 只显示没有匹配的文件路径
-o --only-matching 仅输出匹配的部分
-n --line-number 显示行号（默认）
-N --no-line-number 不显示行号
--column 显示列号（1-based）
-b --byte-offset 显示字节偏移
-r --replace 替换匹配文本再输出
-A NUM --after-context=NUM 显示匹配行后的 NUM 行
-B NUM --before-context=NUM 显示匹配行前的 NUM 行
-C NUM --context=NUM 显示匹配行前后的 NUM 行
-a --text 将二进制文件当作文本搜索
-U --multiline 启用多行匹配
-z --search-zip 搜索压缩文件
-L --follow 跟随符号链接
-M NUM --max-columns=NUM 限制输出行的最大长度
-m NUM --max-count=NUM 每个文件最多匹配 NUM 行
--files 列出将被搜索的文件（不实际搜索）
--sort path 按文件路径排序输出
-p --pretty 美化输出（--color=always --heading --line-number）
-q --quiet 安静模式，不输出，仅通过退出码表示是否找到匹配
-h 显示简略帮助
--help 显示详细帮助
-V --version 显示版本信息

过滤相关速查

标志 作用
-u 等价于 --no-ignore
-uu 等价于 --no-ignore --hidden
-uuu 等价于 --no-ignore --hidden --binary
-g '*.rs' 仅搜索匹配该 glob 的文件
-g '!*.rs' 排除匹配该 glob 的文件
-t rust 仅搜索 Rust 文件
-T rust 排除 Rust 文件
-d NUM 最大递归深度
--max-filesize 50K 忽略大于 50KB 的文件
--type-list 列出所有文件类型
--type-add 'web:*.{html,css}' 添加自定义文件类型

14. 正则表达式语法

默认正则引擎

ripgrep 默认使用 Rust 的 regex 引擎，文档地址：

https://docs.rs/regex/1.\*/regex/#syntax

大致相当于没有环视和反向引用的 Perl 风格正则 ，类似 egrep 的扩展正则（ERE），但增加了 Unicode 字符类等特性。

常用正则语法

语法 说明
. 匹配任意字符（除 \n，启用 (?s) 后匹配所有）
^ 行首锚定
$ 行尾锚定
\b 单词边界
\B 非单词边界
\w 单词字符（Unicode 感知）
\W 非单词字符
\d 数字字符（Unicode 感知）
\D 非数字字符
\s 空白字符（Unicode 感知）
\S 非空白字符
` `
() 捕获组
(?:) 非捕获组
(?P<name>) 命名捕获组
* 零次或多次
+ 一次或多次
? 零次或一次
{n} 精确 n 次
{n,} 至少 n 次
{n,m} n 到 m 次
[abc] 字符类（匹配 a、b、c 之一）
[^abc] 否定字符类
[a-z] 范围
\p{...} Unicode 属性（如 \p{Emoji}、\pL）

内联标志

标志 作用
(?i) 忽略大小写
(?-i) 区分大小写
(?s) 点号匹配所有字符（包括 \n）
(?-s) 点号不匹配 \n
(?u) 启用 Unicode 模式（默认）
(?-u) 禁用 Unicode 模式
(?R) 启用 CRLF 模式
(?-R) 禁用 CRLF 模式
bash 复制代码 
# 只对部分模式忽略大小写
rg '(?i)foo(?-i)bar'

# 只对部分模式禁用 Unicode（. 匹配任意字节）
rg '(?-u:.)'

启用 PCRE2（支持环视和反向引用）

bash 复制代码 
# 使用 PCRE2 引擎
rg -P '(\w{10})\1'                    # 反向引用

# 使用 --engine 参数（推荐）
rg --engine pcre2 'pattern'

# 自动选择引擎
rg --engine auto 'pattern'

注意 ：PCRE2 是可选特性。如果 rg -P 报错 "PCRE2 is not available"，说明当前版本未编译 PCRE2 支持。

15. 输入选项详解

-e PATTERN / --regexp=PATTERN

指定搜索模式。可多次使用，搜索所有匹配任一模式的行。

bash 复制代码 
# 搜索以 - 开头的字面量字符串
rg -e -foo

# 或使用 -- 分隔符
rg -- -foo

# 多个模式（匹配任一即可）
rg -e foo -e bar

-f PATTERNFILE / --file=PATTERNFILE

从文件读取模式，每行一个。可多次使用。

bash 复制代码 
rg -f patterns.txt

# 从 stdin 读取模式
echo 'foo' | rg -f -

--pre COMMAND

对每个输入文件执行预处理命令，搜索命令的 stdout 而非文件内容。

bash 复制代码 
rg --pre ./preprocess 'pattern' file.pdf

--pre-glob GLOB

配合 --pre 使用，限制预处理器仅应用于匹配 glob 的文件。

bash 复制代码 
rg --pre ./preprocess --pre-glob '*.pdf' 'pattern'

-z / --search-zip

搜索压缩文件（gzip、bzip2、xz、LZ4、LZMA、Brotli、Zstd）。需要系统安装对应的解压工具。

bash 复制代码 
rg -z 'pattern' logs.gz

16. 搜索选项详解

-s / --case-sensitive

强制区分大小写（默认行为）。

-i / --ignore-case

忽略大小写，使用 Unicode 简单大小写折叠规则。

-S / --smart-case

模式全小写时忽略大小写，否则区分大小写。"全小写"定义：至少包含一个字面量字符，且所有字面量都不是大写。

bash 复制代码 
rg -S foo     # 忽略大小写（匹配 Foo、FOO）
rg -S Foo     # 区分大小写（只匹配 Foo）

-F / --fixed-strings

将模式视为字面量字符串，而非正则表达式。

bash 复制代码 
rg -F 'func('       # 搜索字面量 "func("，不转义括号

-v / --invert-match

反转匹配，显示不匹配的行。

-x / --line-regexp

只显示匹配整行的结果（等同于用 ^ 和 $ 包裹模式）。

bash 复制代码 
rg -x 'exact line'

-w / --word-regexp

只显示被单词边界包围的匹配。

-m NUM / --max-count=NUM

每个文件最多显示 NUM 行匹配。

-U / --multiline

启用多行搜索，允许匹配跨越多行。

bash 复制代码 
rg -U 'foo\nbar'    # 搜索跨行的 foo + 换行 + bar

--multiline-dotall

使 . 在多行模式下也匹配换行符。

--no-unicode

禁用所有模式的 Unicode 模式，将 .、\w、\s 等限制为 ASCII。

bash 复制代码 
rg --no-unicode '\w+'    # \w 只匹配 [A-Za-z0-9_]

-P / --pcre2

使用 PCRE2 正则引擎。

--engine ENGINE

选择正则引擎：default（默认）、pcre2、auto（自动选择）。

--null-data

使用 NUL 作为行终止符（代替 \n），用于搜索大型二进制文件或 NUL 分隔的数据。

bash 复制代码 
rg --null-data 'pattern' binary-file
find . -print0 | rg --null-data 'pattern'

--crlf

将 CRLF（\r\n）视为行终止符。

-j NUM / --threads=NUM

设置线程数。0 为自动选择。

--no-mmap

禁用内存映射（对于被同时截断的文件可避免意外终止）。

--regex-size-limit NUM+SUFFIX?

设置编译后正则的大小限制。

bash 复制代码 
rg --regex-size-limit 1G '\pL{1000}'

--dfa-size-limit NUM+SUFFIX?

设置正则 DFA 的大小限制。用于加速大量模式（-f 模式文件很大时）。

bash 复制代码 
rg --dfa-size-limit 1G -f huge-patterns.txt

--stop-on-nonmatch

遇到非匹配行后停止搜索该文件。

17. 过滤选项详解

--binary

搜索二进制文件。找到 NUL 字节后不立即停止，而是继续搜索直到找到匹配或文件末尾。

-L / --follow

跟随符号链接。会检测循环链接。

-g GLOB / --glob=GLOB

按 glob 模式包含或排除文件。! 前缀表示排除。

bash 复制代码 
rg -g '*.{c,h}' pattern           # 仅 C 源文件和头文件
rg -g '!*.log' pattern             # 排除日志文件
rg -g 'src/**' pattern             # 仅 src 目录

--iglob=GLOB

同 -g，但大小写不敏感。

--glob-case-insensitive

使所有 -g / --glob 的匹配大小写不敏感。

-d NUM / --max-depth=NUM

限制目录遍历深度。

bash 复制代码 
rg --max-depth 1 pattern ./       # 仅搜索当前目录的直接子文件
rg --max-depth 0 pattern ./       # 不进入子目录

--max-filesize NUM+SUFFIX?

忽略大于指定大小的文件。

bash 复制代码 
rg --max-filesize 50K pattern     # 跳过 >50KB 的文件
rg --max-filesize 80M pattern     # 跳过 >80MB 的文件

-t TYPE / --type=TYPE

仅搜索指定类型的文件。

bash 复制代码 
rg -t rust pattern        # 仅 Rust 文件
rg -t py -t js pattern    # Python 和 JavaScript 文件

-T TYPE / --type-not=TYPE

排除指定类型的文件。

bash 复制代码 
rg -T log pattern         # 排除日志文件类型

--type-add=TYPESPEC

添加文件类型定义。

bash 复制代码 
rg --type-add 'web:*.{html,css,js}' -tweb pattern
rg --type-add 'src:include:cpp,py,md' -tsrc pattern

--type-clear=TYPE

清除类型的已有 glob 定义。

-u / --unrestricted

降低智能过滤级别（可重复最多 3 次）：

次数 等效于
-u --no-ignore
-uu --no-ignore --hidden
-uuu --no-ignore --hidden --binary

-. / --hidden

搜索隐藏文件和目录。

--no-ignore

不遵守 ignore 文件（.gitignore、.ignore、.rgignore）。

--no-ignore-dot

不遵守 .ignore / .rgignore 规则。

--no-ignore-vcs

不遵守 VCS 忽略规则（如 .gitignore）。

--no-ignore-parent

不遵守父目录中的 ignore 文件。

--no-ignore-global

不遵守全局 gitignore 规则。

--no-ignore-exclude

不遵守仓库排除规则（如 .git/info/exclude）。

--no-ignore-files

忽略所有 --ignore-file 指定的文件。

--ignore-file=PATH

指定额外的 ignore 规则文件。

--ignore-file-case-insensitive

对 ignore 文件进行大小写不敏感的匹配。

--no-require-git

即使没有 git 仓库也遵守源代码控制忽略文件。

--one-file-system

不跨越文件系统边界。

18. 输出选项详解

-A NUM / --after-context=NUM

显示匹配行后的 NUM 行。

-B NUM / --before-context=NUM

显示匹配行前的 NUM 行。

-C NUM / --context=NUM

显示匹配行前后的 NUM 行。

bash 复制代码 
rg -C 3 pattern        # 显示匹配行前后各 3 行
rg -A 2 -B 1 pattern   # 前 1 行 + 后 2 行

--context-separator=SEPARATOR

设置上下文分隔符（默认为 --）。

bash 复制代码 
rg -C 2 pattern --context-separator='...'

--no-context-separator

完全禁用上下文分隔符。

--field-context-separator=SEPARATOR

设置上下文行的字段分隔符（默认为 -）。

--field-match-separator=SEPARATOR

设置匹配行的字段分隔符（默认为 :）。

-M NUM / --max-columns=NUM

限制输出行最大长度（字节）。超长行不显示内容，只显示匹配数。

bash 复制代码 
rg -M 150 pattern     # 忽略超过 150 列的行
rg -M 0 pattern       # 禁用限制

--max-columns-preview

配合 -M 使用，显示超长行的预览而非完全省略。

-n / --line-number

显示行号（默认开启）。

-N / --no-line-number

不显示行号。

--column

显示列号（1-based）。蕴含 --line-number。

-b / --byte-offset

显示 0-based 字节偏移。

-o / --only-matching

仅输出匹配的部分，每个匹配独立一行。

-r REPLACEMENT / --replace=REPLACEMENT

替换匹配文本后输出。

bash 复制代码 
rg foo -r bar          # 所有 "foo" 替换为 "bar"
rg '(\w+)-(\w+)' -r '$2-$1'   # 使用捕获组

--color=WHEN

控制颜色使用时机：never、auto（默认）、always、ansi。

--colors=COLOR_SPEC

配置颜色。格式：{type}:{attribute}:{value} 或 {type}:none。

支持的 type ：path、line、column、match、highlight

支持的 attribute ：fg（前景色）、bg（背景色）、style

style 值 ：bold、nobold、intense、nointense、underline、nounderline、italic、noitalic

颜色值：

  • 8 种基本颜色名：red、blue、green、cyan、magenta、yellow、white、black
  • 256 色：0-255（十进制）或 0x00-0xFF（十六进制）
  • 24-bit 真彩色：R,G,B（如 0,128,255 或 0x00,0x80,0xFF）
bash 复制代码 
# 蓝色背景 + 白色粗体匹配文字
rg --colors 'match:none' \
   --colors 'match:bg:0x33,0x66,0xFF' \
   --colors 'match:fg:white' \
   --colors 'match:style:bold' \
   pattern

# 模拟 The Silver Searcher 的输出
rg --colors line:fg:yellow \
   --colors line:style:bold \
   --colors path:fg:green \
   --colors path:style:bold \
   --colors match:fg:black \
   --colors match:bg:yellow \
   --colors match:style:nobold \
   foo

# 高亮匹配行中的非匹配部分
rg --colors 'highlight:bg:yellow' --colors 'highlight:fg:black' pattern

--heading

在每个文件的匹配集合上方打印文件路径（输出到 tty 时的默认模式）。

--no-heading

不使用 heading 模式，每个匹配行显示文件路径前缀。

-H / --with-filename

始终显示文件名（搜索多个文件时的默认行为）。

-I / --no-filename

从不显示文件名（搜索单个文件时的默认行为）。

--line-buffered

使用行缓冲（输出到管道时默认使用块缓冲，此标志强制行缓冲）。

bash 复制代码 
tail -f log | rg --line-buffered ERROR | rg timeout

--block-buffered

使用块缓冲。

-0 / --null

在文件路径后输出 NUL 字节，配合 xargs -0 使用。

--path-separator=SEPARATOR

设置文件路径分隔符（Unix 默认 /，Windows 默认 \）。

--passthru / --passthrough

打印所有行（匹配和不匹配的都打印），匹配的行高亮。

-p / --pretty

美化输出的便捷别名：--color=always --heading --line-number。

bash 复制代码 
rg -p foo | less -R    # 管道中也保留美化的输出

--trim

去除每行输出开头的 ASCII 空白。

--vimgrep

以 vimgrep 格式输出（每个匹配单独一行，含行号和列号）。警告：输出量可能非常大。

--hyperlink-format=FORMAT

设置超链接格式，使输出中的文件路径可点击（需终端支持 OSC-8）。

bash 复制代码 
# 别名
rg --hyperlink-format default pattern
rg --hyperlink-format vscode pattern
rg --hyperlink-format file pattern

--sort=SORTBY

排序输出结果。取值：none（默认）、path、modified、accessed、created。

bash 复制代码 
rg --sort path pattern       # 按文件路径排序
rg --sort modified pattern   # 按修改时间排序

--sortr=SORTBY

降序排序（同 --sort 的取值）。

19. 输出模式

-c / --count

抑制正常输出，显示每个文件的匹配行数。

bash 复制代码 
rg -c pattern            # 每个文件一行：路径:匹配行数
rg -c --include-zero pattern   # 零匹配的文件也显示

--count-matches

抑制正常输出，显示每个文件的匹配次数（而非行数）。

-l / --files-with-matches

仅打印有匹配的文件路径。

bash 复制代码 
rg -l pattern            # 有匹配的文件列表

--files-without-match

仅打印没有匹配的文件路径。

--json

以 JSON Lines 格式输出。输出包含 5 种消息类型：begin、end、match、context、summary。

bash 复制代码 
rg --json pattern | delta    # 配合 delta 语法高亮
rg --json pattern > results.jsonl

--stats

在搜索结束后打印聚合统计信息（匹配行数、含匹配的文件数、搜索的文件数、耗时）。

--files

列出将被搜索的文件而不实际搜索。

bash 复制代码 
rg --files                # 列出当前目录下会被搜索的所有文件
rg --files -t rust        # 列出会被搜索的 Rust 文件

20. 调试与日志

--debug

显示调试信息，帮助理解为什么某个文件被跳过。

--trace

显示跟踪信息，比 --debug 更详细，用于深入分析搜索行为。

--no-messages

抑制文件读取失败的错误消息。

--no-ignore-messages

抑制 ignore 文件解析相关的错误消息。

21. 其他行为选项

--generate KIND

生成特定类型的内容并退出。KIND 可选值：

  • man --- 生成 man 手册页
  • complete-bash --- Bash 补全脚本
  • complete-zsh --- Zsh 补全脚本
  • complete-fish --- Fish 补全脚本
  • complete-powershell --- PowerShell 补全脚本
bash 复制代码 
rg --generate man > rg.1
rg --generate complete-bash > rg.bash

--no-config

禁用所有配置文件读取。

--pcre2-version

显示 PCRE2 版本信息并退出。

22. 退出状态码

状态码 含义
0 找到至少一个匹配，无错误（除非使用了 -q）
1 没有找到匹配，无错误
2 发生错误（包括正则语法错误和文件读取错误）
bash 复制代码 
rg pattern file && echo "找到了" || echo "没找到或出错了"

23. 自动过滤机制详解

ripgrep 默认执行四种自动过滤：

  1. 忽略规则 ：遵循 .gitignore、.git/info/exclude、全局 gitignore、.ignore、.rgignore
  2. 隐藏文件 ：跳过以 . 开头的文件/目录（Windows 上还包括隐藏属性）
  3. 二进制文件 ：跳过包含 NUL 字节的文件
  4. 符号链接：不跟随

忽略规则的优先顺序（由低到高）

复制代码 
--ignore-file 指定的文件
  ↓
全局 gitignore ($HOME/.config/git/ignore)
  ↓
.git/info/exclude
  ↓
.gitignore
  ↓
.ignore
  ↓
.rgignore（最高优先级）

-u 标志的层级

复制代码 
-u    = --no-ignore
-uu   = --no-ignore --hidden
-uuu  = --no-ignore --hidden --binary

rg -uuu 将搜索和 grep -r 相同的内容。

需要注意的细节

  • 被 .gitignore 忽略但被 git 跟踪的文件，ripgrep 不会搜索（这与 git 行为不一致）
  • 使用 --no-require-git 可以在无 git 仓库时也遵守 .gitignore

24. 配置文件详解

设置配置文件

bash 复制代码 
# Linux/macOS
export RIPGREP_CONFIG_PATH="$HOME/.ripgreprc"

# Windows (PowerShell)
$env:RIPGREP_CONFIG_PATH = "$HOME\.ripgreprc"

配置文件的规则

  1. 每行一个 shell 参数（去除首尾空格后）
  2. # 开头的行是注释

完整示例

复制代码 
# ── 显示设置 ──
--max-columns=150
--max-columns-preview
--heading

# ── 搜索设置 ──
--smart-case

# ── 过滤设置 ──
--hidden
--glob=!.git/*

# ── 自定义文件类型 ──
--type-add
web:*.{html,css,js}*

# ── 颜色设置 ──
--colors=match:bg:yellow
--colors=match:fg:black
--colors=match:style:bold
--colors=line:fg:green
--colors=path:fg:blue
--colors=path:style:bold

配置中 flag 和 value 的写法

错误写法（flag 和 value 在同一行但用空格分隔）：

复制代码 
-j 4        # 错误！ripgrep 不会将其解析为 -j=4

正确写法：

复制代码 
-j4         # 正确
--threads=4 # 正确
-j          # 正确：flag 和 value 分开两行
4
--type-add  # 正确：含特殊字符的值分开写
web:*.{html,css,js}*

命令行覆盖配置

命令行参数会覆盖配置文件中的设置（后指定者优先）：

bash 复制代码 
RIPGREP_CONFIG_PATH=~/.ripgreprc rg --case-sensitive foo
# 相当于 rg --smart-case --case-sensitive foo
# --case-sensitive 覆盖了配置文件中的 --smart-case

25. Shell 自动补全

Bash

bash 复制代码 
mkdir -p "$XDG_CONFIG_HOME/bash_completion"
rg --generate complete-bash > "$XDG_CONFIG_HOME/bash_completion/rg.bash"

Zsh

bash 复制代码 
mkdir -p "$HOME/.zsh-complete"
rg --generate complete-zsh > "$HOME/.zsh-complete/_rg"
# 在 ~/.zshrc 中添加：fpath=($HOME/.zsh-complete $fpath)

Fish

bash 复制代码 
mkdir -p "$HOME/.config/fish/completions"
rg --generate complete-fish > "$HOME/.config/fish/completions/rg.fish"

PowerShell

powershell 复制代码 
rg --generate complete-powershell > _rg.ps1
# 在 PowerShell profile 中添加：. _rg.ps1

26. 注意事项与性能

内存使用

  1. 并行搜索时 ：每个文件的输出缓冲在内存中（防止交错输出）。用 -j1 禁用并行可减少内存。
  2. 长行 ：ripgrep 需要至少一行在内存中。搜索二进制文件时超长行（-a 标志）可能导致大量内存使用。
  3. 内存映射：搜索大文件时进程可能报告驻留内存接近文件大小，但这是操作系统管理的，实际堆内存占用不大。

文件截断

使用默认设置搜索同时被截断的文件可能导致 ripgrep 意外终止。通过 --no-mmap 禁用内存映射可以避免。

PCRE2 性能

启用 PCRE2（-P）后可能变慢的原因：

  • PCRE2 缺少模式静态分析 API，ripgrep 无法做 \n 剥离优化，强制使用逐行搜索
  • PCRE2 的 Unicode 模式要求数据必须是有效 UTF-8，ripgrep 需要先进行转码

让 PCRE2 更快的技巧：

bash 复制代码 
# 组合使用多行模式 + 禁用 PCRE2 Unicode
rg -P -U --no-pcre2-unicode 'pattern'

排序与并行

使用 --sort 会强制单线程运行。小仓库可能感觉不到性能差异。

27. 常见问题 FAQ

Q1: 如何搜索非 UTF-8 编码的文件？

bash 复制代码 
rg -E gbk pattern       # 指定 GBK 编码
rg -E shift_jis pattern # 指定 Shift_JIS
rg -E none pattern      # 按原始字节搜索

Q2: 如何搜索压缩文件？

bash 复制代码 
rg -z 'pattern' file.gz

支持 gzip、bzip2、xz、LZ4、LZMA、Brotli、Zstd。

Q3: 如何跨行搜索？

bash 复制代码 
rg -U 'foo\nbar'

Q4: 如何使用环视和反向引用？

bash 复制代码 
# 使用 PCRE2 引擎
rg -P '(?<=foo)bar'        # 后顾断言
rg -P '(\w+)\s+\1'         # 反向引用
rg --engine pcre2 pattern  # 推荐写法

Q5: 如何配置颜色？

bash 复制代码 
rg --colors 'match:fg:magenta' --colors 'line:bg:yellow' pattern

常用配置放入配置文件 ~/.ripgreprc。

Q6: Windows 上如何启用真彩色？

bash 复制代码 
# 需要先清除默认样式（Windows 10 的 VT100 不支持 bold + 真彩色同时使用）
rg --colors 'match:none' --colors 'match:fg:0x33,0x66,0xFF' pattern

Q7: 终止 ripgrep 后终端颜色乱了？

  • cmd.exe：输入 color
  • Unix：输入 echo -ne "\033[0m"
  • PowerShell：添加 Reset-ForegroundColor 函数到 profile

Q8: 在 Cygwin 中 / 开头的模式失败？

Cygwin 可能将 /foo 转换为 C:/msys64/foo。解决方法：

bash 复制代码 
rg //foo                     # 双斜杠
MSYS_NO_PATHCONV=1 rg /foo   # 禁用路径转换

Q9: 正则大小超限？

bash 复制代码 
rg --regex-size-limit 1G '\pL{1000}'

Q10: -f 模式文件很大时速度变慢？

bash 复制代码 
rg --dfa-size-limit 1G -f huge-patterns.txt

Q11: 如何模拟 The Silver Searcher 的输出样式？

bash 复制代码 
rg --colors line:fg:yellow --colors line:style:bold \
   --colors path:fg:green --colors path:style:bold \
   --colors match:fg:black --colors match:bg:yellow \
   --colors match:style:nobold foo

Q12: 如何获得一致的输出顺序？

bash 复制代码 
rg --sort path pattern    # 按文件路径排序（会禁用并行）

Q13: 为什么运行 rg 却执行了别的命令？

可能是 shell 别名冲突（如 Oh My Zsh 的 Rails 插件）。解决方法：

bash 复制代码 
which rg                  # 查看是什么
command rg pattern        # 绕过别名
\rg pattern               # 绕过别名
unalias rg                # 永久移除别名

Q14: Windows 上如何创建 ripgrep 别名（PowerShell）？

powershell 复制代码 
function grep {
    $count = @($input).Count
    $input.Reset()
    if ($count) {
        $input | rg.exe --hidden $args
    } else {
        rg.exe --hidden $args
    }
}

Q15: 如何在 PowerShell 中正确管道非 ASCII 内容？

powershell 复制代码 
# 设置 $OutputEncoding 为 UTF-8
$OutputEncoding = [System.Text.UTF8Encoding]::new()

Q16: ripgrep 能替换 grep 吗？

部分场景可以，但不是 100% 替代：

  • ✅ 适合：代码仓库搜索、UTF-8 文本搜索、需要自动过滤的场合
  • ❌ 不适合：需要 POSIX 兼容的脚本、需要极致便携性的环境

Q17: 如何搜索 PDF 文件？

bash 复制代码 
# 先用 pdftotext 转换为文本再搜索
pdftotext file.pdf - | rg pattern

# 或使用预处理器
rg --pre ./preprocess 'pattern' file.pdf    # preprocess 脚本调用 pdftotext

Q18: 如何查看 ripgrep 的 man 手册页？

bash 复制代码 
rg --generate man | man -l -
# 或
man rg    # 如果通过包管理器安装

Q19: ripgrep 的 "rip" 是什么意思？

最初作者想表达 "to rip through your text"（快速穿过文本），同时也巧合地与 "Rest in Peace" 形成双关（但并非本意）。

Q20: 如何捐赠支持 ripgrep？

通过 GitHub Sponsors 赞助作者，或向以下组织捐款：

附录：预定义文件类型速查

通过 rg --type-list 查看完整列表。以下是部分常用类型：

类型名 匹配的文件
rust *.rs
py *.py
js *.js
ts *.ts
html *.html
css *.css
c *.c, *.h, *.H
cpp *.cpp, *.cc, *.cxx, *.hpp, *.hh, *.hxx
java *.java, *.class
go *.go
md *.md, *.markdown
json *.json
toml *.toml
yaml *.yaml, *.yml
sh *.sh, *.bash, *.zsh
make *.mak, *.mk, GNUmakefile, Makefile
xml *.xml
svg *.svg, *.svgz
log *.log
lock *.lock, package-lock.json
markdown *.md, *.markdown
pdf *.pdf

文档版本 ：基于 ripgrep 15.1.0 (rev af60c2de9d) 官方文档整理
整理日期 ：2026-05-01
许可：本文档基于 ripgrep 官方文档，ripgrep 采用 MIT / UNLICENSE 双许可

相关推荐
是Dream呀7 小时前
从零到一:Triton实现CELU激活函数优化之路
ai·vllm·openclaw
计算机安禾7 小时前
【Linux从入门到精通】第40篇：LAMP/LNMP环境一键部署脚本实战
android·linux·adb
AI进化营-智能译站7 小时前
ROS2 C++开发系列04：如何有效输出机器人状态
开发语言·c++·ai·机器人
‎ദ്ദിᵔ.˛.ᵔ₎7 小时前
Linux 基础指令
linux
AI进化营-智能译站7 小时前
ROS2 C++开发系列05：机器人启动如何传递命令行参数实战
开发语言·c++·ai·机器人
寒山独见君~7 小时前
自动化-消息推送Server酱3，APP推送
运维·数据库·python·自动化·通知
都在酒里7 小时前
在公共服务器上构建 RK3588 SDK 的纯净 Docker 方案
运维·服务器·docker
计算机安禾7 小时前
【Linux从入门到精通】第46篇：SELinux与AppArmor——Linux的安全增强模块
linux·运维·安全
春蕾夏荷_7282977257 小时前
1、c++ acl udp服务器客户端简单实例-客户器端(2)
服务器·c++·udp
热门推荐
01要裂开了！ChatGPT要手机号验证了？注册Codex要求验证电话号码怎么办？2026年登陆Codex要手机号验证的解决办法02GitHub 镜像站点03裂开！ChatGPT 居然开始要手机号验证，附详细解决方法04【AI】2026 年具身智能模型和世界模型总结05Codex 接入 DeepSeek API 完整配置文档062026年4月AI大事件深度解读：大模型竞争进入“深水区“07实测可用｜小米 MiMo 百万亿 Token 免费领，开发者速冲082026年AI前瞻：量子AI、具身智能与科学发现的新纪元09零基础教你claude code 接入 deepseek V410在Windows 11上安装Docker的踩坑记录