ripgrep

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ripgrep (rg) - Fast Text Search Tool

Ripgrep (rg) - 快速文本搜索工具

Overview

概述

Ripgrep is a line-oriented search tool that recursively searches directories for regex patterns. It's 10-100x faster than grep and respects

.gitignore

by default. Use it instead of grep, find, or manually reading large files.

Core principle: When you need to find text in files, use ripgrep. Don't read entire files into context when you can search them.

Ripgrep 是一款面向行的搜索工具，可递归搜索目录中的 regex 模式。它的速度比 grep 快10-100倍，并且默认尊重

.gitignore

规则。可以用它替代 grep、find 或手动读取大文件。

核心原则： 当你需要在文件中查找文本时，使用 ripgrep。如果可以通过搜索找到内容，就不要把整个文件读入上下文。

When to Use

使用场景

Use ripgrep when:

Searching for text patterns across a codebase or directory
Finding all occurrences of a function, variable, or string
Searching through books, documentation, or large text files
Files are too large to read fully into context
Looking for specific content in many files at once
Finding files that contain (or don't contain) certain patterns
Extracting matching lines for analysis

Don't use when:

You need the full file content (use Read tool)
Simple glob pattern matching for filenames only (use Glob tool)
You need structured data extraction (consider jq, awk)

以下情况使用 ripgrep：

在代码库或目录中搜索文本模式
查找函数、变量或字符串的所有出现位置
搜索书籍、文档或大型文本文件
文件过大，无法完整读入上下文
同时在多个文件中查找特定内容
查找包含（或不包含）特定模式的文件
提取匹配行用于分析

以下情况不使用：

需要完整文件内容（使用读取工具）
仅对文件名进行简单 glob 模式匹配（使用 Glob 工具）
需要结构化数据提取（考虑使用 jq、awk）

Quick Reference

快速参考

Task	Command
Basic search	`rg "pattern" [path]`
Case insensitive	`rg -i "pattern"`
Smart case (auto)	`rg -S "pattern"`
Whole word only	`rg -w "word"`
Fixed string (no regex)	`rg -F "literal.string"`
Show context lines	`rg -C 3 "pattern"` (3 before & after)
Show line numbers	`rg -n "pattern"` (default in tty)
Only filenames	`rg -l "pattern"`
Files without match	`rg --files-without-match "pattern"`
Count matches	`rg -c "pattern"`
Only matching part	`rg -o "pattern"`
Invert match	`rg -v "pattern"`
Multiline search	`rg -U "pattern.*\nmore"`

任务	命令
基础搜索	`rg "pattern" [path]`
忽略大小写	`rg -i "pattern"`
智能大小写（自动适配）	`rg -S "pattern"`
仅匹配整词	`rg -w "word"`
固定字符串（不使用正则）	`rg -F "literal.string"`
显示上下文行	`rg -C 3 "pattern"` （前后各3行）
显示行号	`rg -n "pattern"` （终端环境下默认显示）
仅显示文件名	`rg -l "pattern"`
显示无匹配的文件	`rg --files-without-match "pattern"`
统计匹配次数	`rg -c "pattern"`
仅显示匹配部分	`rg -o "pattern"`
反向匹配	`rg -v "pattern"`
多行搜索	`rg -U "pattern.*\nmore"`

File Filtering

文件过滤

By File Type

按文件类型

Ripgrep has built-in file type definitions. Use

-t

to include,

-T

to exclude:

bash

undefined

Ripgrep 内置了文件类型定义。使用

-t

包含指定类型，

-T

排除指定类型：

bash

undefined

Search only Python files

仅搜索Python文件

rg -t py "def main"

Search only JavaScript and TypeScript

仅搜索JavaScript和TypeScript文件

rg -t js -t ts "import"

Exclude test files

排除测试文件

rg -T test "function"

List all known types

列出所有支持的文件类型

rg --type-list


**Common types:** `py`, `js`, `ts`, `rust`, `go`, `java`, `c`, `cpp`, `rb`, `php`, `html`, `css`, `json`, `yaml`, `md`, `txt`, `sh`

rg --type-list


**常见类型：** `py`, `js`, `ts`, `rust`, `go`, `java`, `c`, `cpp`, `rb`, `php`, `html`, `css`, `json`, `yaml`, `md`, `txt`, `sh`

By Glob Pattern

按Glob模式

bash

undefined

bash

undefined

Only .tsx files

仅搜索.tsx文件

rg -g "*.tsx" "useState"

Exclude node_modules (in addition to gitignore)

排除node_modules目录（在gitignore规则基础上额外排除）

rg -g "!node_modules/**" "pattern"

Only files in src directory

仅搜索src目录下的文件

rg -g "src/**" "pattern"

Multiple globs

多个Glob规则

rg -g ".js" -g ".ts" "pattern"

Case insensitive globs

忽略大小写的Glob规则

rg --iglob "*.JSON" "pattern"

undefined

rg --iglob "*.JSON" "pattern"

undefined

By File Size

按文件大小

bash

undefined

bash

undefined

Skip files larger than 1MB

跳过大于1MB的文件

rg --max-filesize 1M "pattern"

undefined

rg --max-filesize 1M "pattern"

undefined

Directory Control

目录控制

bash

undefined

bash

undefined

Limit depth

限制搜索深度

rg --max-depth 2 "pattern"

Search hidden files (dotfiles)

搜索隐藏文件（点文件）

rg --hidden "pattern"

Follow symlinks

跟随符号链接

rg -L "pattern"

Ignore all ignore files (.gitignore, etc.)

忽略所有忽略文件（.gitignore等）

rg --no-ignore "pattern"

Progressive unrestricted (-u can stack up to 3 times)

逐步解除限制（-u最多可叠加3次）

rg -u "pattern" # --no-ignore rg -uu "pattern" # --no-ignore --hidden rg -uuu "pattern" # --no-ignore --hidden --binary

undefined

rg -u "pattern" # --no-ignore rg -uu "pattern" # --no-ignore --hidden rg -uuu "pattern" # --no-ignore --hidden --binary

undefined

Context Options

上下文选项

bash

undefined

bash

undefined

Lines after match

显示匹配行之后的N行

rg -A 5 "pattern"

Lines before match

显示匹配行之前的N行

rg -B 5 "pattern"

Lines before and after

显示匹配行前后的N行

rg -C 5 "pattern"

Print entire file on match (passthrough mode)

匹配时打印整个文件内容（直通模式）

rg --passthru "pattern"

undefined

rg --passthru "pattern"

undefined

Output Formats

输出格式

bash

undefined

bash

undefined

Just filenames with matches

仅显示包含匹配的文件名

rg -l "pattern"

Files without matches

显示无匹配的文件名

rg --files-without-match "pattern"

Count matches per file

按文件统计匹配次数

rg -c "pattern"

Count total matches (not lines)

统计总匹配次数（不是行数）

rg --count-matches "pattern"

Only the matched text (not full line)

仅显示匹配的文本（不是整行）

rg -o "pattern"

JSON output (for parsing)

JSON格式输出（用于解析）

rg --json "pattern"

Vim-compatible output (file:line:col:match)

兼容Vim的输出格式（file:line:col:match）

rg --vimgrep "pattern"

With statistics

显示统计信息

rg --stats "pattern"

undefined

rg --stats "pattern"

undefined

Regex Patterns

正则表达式模式

Ripgrep uses Rust regex syntax by default:

bash

undefined

Ripgrep 默认使用 Rust 正则表达式语法：

bash

undefined

Alternation

分支匹配

rg "foo|bar"

Character classes

字符类

rg "[0-9]+" rg "[a-zA-Z_][a-zA-Z0-9_]*"

Word boundaries

单词边界

rg "\bword\b"

Quantifiers

量词

rg "colou?r" # 0 or 1 rg "go+gle" # 1 or more rg "ha*" # 0 or more rg "x{2,4}" # 2 to 4 times

rg "colou?r" # 0或1次 rg "go+gle" # 1或多次 rg "ha*" # 0或多次 rg "x{2,4}" # 2到4次

Groups

分组

rg "(foo|bar)baz"

Lookahead/lookbehind (requires -P for PCRE2)

正向预查/反向预查（需要-P参数启用PCRE2）

rg -P "(?<=prefix)content" rg -P "content(?=suffix)"

undefined

rg -P "(?<=prefix)content" rg -P "content(?=suffix)"

undefined

Multiline Matching

多行匹配

bash

undefined

bash

undefined

Enable multiline mode

启用多行模式

rg -U "start.*\nend"

Dot matches newline too

让点号匹配换行符

rg -U --multiline-dotall "start.*end"

Match across lines

跨多行匹配

rg -U "function\s+\w+([^)])\s{"

undefined

rg -U "function\s+\w+([^)])\s{"

undefined

Replacement (Preview Only)

替换（仅预览）

Ripgrep can show what replacements would look like (doesn't modify files):

bash

undefined

Ripgrep 可以显示替换后的效果（不会修改文件）：

bash

undefined

Simple replacement

简单替换

rg "old" -r "new"

Using capture groups

使用捕获组

rg "(\w+)@(\w+)" -r "$2::$1"

Remove matches (empty replacement)

移除匹配内容（空替换）

rg "pattern" -r ""

undefined

rg "pattern" -r ""

undefined

Searching Special Files

搜索特殊文件

Compressed Files

压缩文件

bash

undefined

bash

undefined

Search in gzip, bzip2, xz, lz4, lzma, zstd files

在gzip、bzip2、xz、lz4、lzma、zstd格式的文件中搜索

rg -z "pattern" file.gz rg -z "pattern" archive.tar.gz

undefined

rg -z "pattern" file.gz rg -z "pattern" archive.tar.gz

undefined

Binary Files

二进制文件

bash

undefined

bash

undefined

Include binary files

包含二进制文件

rg --binary "pattern"

Treat binary as text (may produce garbage)

将二进制文件视为文本（可能产生乱码）

rg -a "pattern"

undefined

rg -a "pattern"

undefined

Large Files

大文件

For files too large to read into context:

bash

undefined

对于过大无法读入上下文的文件：

bash

undefined

Search and show only matching lines

搜索并仅显示匹配行

rg "specific pattern" large_file.txt

Limit matches to first N per file

限制每个文件最多显示N个匹配结果

rg -m 10 "pattern" huge_file.log

Show byte offset for large file navigation

显示匹配内容的字节偏移量，方便大文件导航

rg -b "pattern" large_file.txt

Use with head/tail for pagination

结合head/tail进行分页

rg "pattern" large_file.txt | head -100

undefined

rg "pattern" large_file.txt | head -100

undefined

Performance Tips

性能优化技巧

Be specific with paths - Don't search from root when you know the subdir
Use file types -
```
-t py
```
is faster than
```
-g "*.py"
```
Use fixed strings -
```
-F
```
when you don't need regex
Limit depth -
```
--max-depth
```
when you know structure
Let gitignore work - Don't use
```
--no-ignore
```
unless needed
Use word boundaries -
```
-w
```
is optimized

指定具体路径 - 当你知道目标子目录时，不要从根目录开始搜索
使用文件类型参数 -
```
-t py
```
比
```
-g "*.py"
```
速度更快
使用固定字符串模式 - 不需要正则时使用
```
-F
```
限制搜索深度 - 了解目录结构时使用
```
--max-depth
```
保留gitignore规则 - 除非必要，否则不要使用
```
--no-ignore
```
使用单词边界 -
```
-w
```
参数经过优化，速度更快

Common Patterns

常见使用场景示例

Find function definitions

查找函数定义

bash

undefined

bash

undefined

Python

rg "def \w+(" -t py

JavaScript/TypeScript

rg "(function|const|let|var)\s+\w+\s*=" -t js -t ts rg "^\s*(async\s+)?function" -t js

Go

rg "^func\s+\w+" -t go

undefined

rg "^func\s+\w+" -t go

undefined

Find imports/requires

查找导入语句

bash

undefined

bash

undefined

Python

rg "^(import|from)\s+" -t py

JavaScript

rg "^(import|require()" -t js

Go

rg "^import\s+" -t go

undefined

rg "^import\s+" -t go

undefined

Find TODO/FIXME comments

查找TODO/FIXME注释

bash

rg "(TODO|FIXME|HACK|XXX):"

bash

rg "(TODO|FIXME|HACK|XXX):"

Find error handling

查找错误处理代码

bash

undefined

bash

undefined

Python

rg "except\s+\w+:" -t py

JavaScript

rg ".catch(|catch\s*(" -t js

undefined

rg ".catch(|catch\s*(" -t js

undefined

Find class definitions

查找类定义

bash

undefined

bash

undefined

Python

rg "^class\s+\w+" -t py

JavaScript/TypeScript

rg "^(export\s+)?(default\s+)?class\s+\w+" -t js -t ts

undefined

rg "^(export\s+)?(default\s+)?class\s+\w+" -t js -t ts

undefined

Search in books/documents

在书籍/文档中搜索

bash

undefined

bash

undefined

Find chapter headings

查找章节标题

rg "^(Chapter|CHAPTER)\s+\d+" book.txt

Find quoted text

查找引用文本

rg '"[^"]{20,}"' document.txt

Find paragraphs containing word

查找包含指定关键词的段落

rg -C 2 "keyword" book.txt

undefined

rg -C 2 "keyword" book.txt

undefined

Combining with Other Tools

与其他工具结合使用

bash

undefined

bash

undefined

Find files, then search

先查找文件，再在文件中搜索

rg --files | xargs rg "pattern"

Search and count by file

搜索并按文件统计排序

rg -c "pattern" | sort -t: -k2 -rn

Search and open in editor

搜索并在编辑器中打开文件

rg -l "pattern" | xargs code

Extract unique matches

提取唯一匹配结果

rg -o "\b[A-Z]{2,}\b" | sort -u

Search multiple patterns from file

从文件中读取多个模式进行搜索

rg -f patterns.txt

undefined

rg -f patterns.txt

undefined

Exit Codes

退出码

Code	Meaning
0	Matches found
1	No matches found
2	Error occurred

Useful for scripting:

bash

if rg -q "pattern" file.txt; then
    echo "Found"
fi

代码	含义
0	找到匹配结果
1	未找到匹配结果
2	发生错误

适用于脚本编写：

bash

if rg -q "pattern" file.txt; then
    echo "找到匹配"
fi

Common Mistakes

常见错误及解决方法

Mistake	Fix
Pattern has special chars	Use `-F` for fixed strings or escape: `rg "foo\.bar"`
Can't find hidden files	Add `--hidden` or `-uu`
Missing node_modules	Add `--no-ignore` (but it's usually right to skip)
Regex too complex	Try `-P` for PCRE2 with lookahead/lookbehind
Output too long	Use `-m N` to limit, or `-l` for just filenames
Binary file skipped	Add `--binary` or `-a` for text mode
Need to see full line	Remove `-o` (only-matching) flag

错误	解决方法
模式包含特殊字符	使用 `-F` 启用固定字符串模式，或转义特殊字符： `rg "foo\.bar"`
无法找到隐藏文件	添加 `--hidden` 或 `-uu` 参数
无法搜索node_modules目录	添加 `--no-ignore` 参数（但通常忽略该目录是合理的）
正则表达式过于复杂	尝试使用 `-P` 参数启用PCRE2，支持预查功能
输出内容过多	使用 `-m N` 限制匹配数量，或使用 `-l` 仅显示文件名
二进制文件被跳过	添加 `--binary` 或 `-a` 参数以文本模式处理
需要查看完整行	移除 `-o` （仅显示匹配部分）参数

When to Prefer Other Tools

何时优先使用其他工具

Task	Better Tool
Structured JSON queries	`jq`
Column-based text processing	`awk`
Stream editing/substitution	`sed` (actually modifies files)
Find files by name only	`fd` or `find`
Simple file listing	`ls` or `glob`
Full file content needed	Read tool

任务	更合适的工具
结构化JSON查询	`jq`
基于列的文本处理	`awk`
流编辑/替换（实际修改文件）	`sed`
仅按文件名查找文件	`fd` 或 `find`
简单文件列表	`ls` 或 `glob`
需要完整文件内容	读取工具