企业官网建设流程全解析

如何快速上手tgrep：从安装到毫秒级代码搜索的完整入门指南

【免费下载链接】tgrepTrigram-indexed grep with a client/server architecture for fast regex search in large codebases locally项目地址: https://gitcode.com/gh_mirrors/tg/tgrep

tgrep 是一款基于三元组（trigram）索引的 grep 搜索工具，采用客户端/服务器架构，专为大型代码库的毫秒级正则搜索设计。它已在 18 组真实仓库基准测试中的 17 组里跑赢 ripgrep，最高提速 51.9 倍，并被集成进 GitHub Copilot CLI 提供高速代码检索。本指南带你从安装到常用搜索命令，一步步上手 tgrep。

一、3 种方式一键安装 tgrep

根据你的环境任选其一，安装后只需一个tgrep命令。

方式 1：Homebrew 安装（macOS / Linux，最省事）

brew install tgrep

方式 2：从源码安装（需要 Rust 工具链）

git clone https://gitcode.com/gh_mirrors/tg/tgrep cd tgrep cargo install --path tgrep-cli --locked

方式 3：使用预编译二进制

下载对应平台的压缩包（Linux / macOS / Windows），解压后将可执行文件复制到PATH中的目录即可。各平台命令示例见 README.md 的 Installation 章节。

💡 装完执行tgrep --version确认版本号，一切就绪。

二、30 秒快速体验：从建索引到搜索

tgrep 的核心工作流只有两条命令：先启动服务器（自动建索引），再搜索。

第 1 步：启动服务（后台运行，首次会自动构建索引）

tgrep serve .

第 2 步：在另一个终端直接搜索

tgrep -- "fn main" . # 客户端自动发现并连接服务器 tgrep status . # 查看索引与刷新状态

第 3 步：不想常驻服务？手动建一次磁盘索引

tgrep index .

索引默认存放在.tgrep/目录，记得把它加入.gitignore。没有索引时，tgrep 会自动退化为全文件系统扫描，功能不受影响，只是速度回到普通 grep 水平。

三、毫秒级搜索：常用命令速查

tgrep 兼容 ripgrep 的命令行习惯，老rg用户几乎零成本迁移：

tgrep -- "TODO|FIXME" . # 正则 alternation tgrep -i -- "error" . # 忽略大小写 tgrep -F -- "Vec<T>" . # 按字面量搜索 tgrep -l -- "MyStruct" . # 只输出匹配的文件名 tgrep -t rust -C 3 -- "pattern" . # 只看 Rust 文件，带 3 行上下文 tgrep --json -- "pattern" . # ripgrep 兼容的 JSON 输出 tgrep --stats -- "pattern" . # 查看查询计划与耗时 tgrep --no-index -- "pattern" . # 强制读当前文件，绕过索引

几个新手常踩的点：

• 模式以-开头时，务必用--隔开，例如tgrep -F -- -serve .；
• 想强制搜索最新内容（索引可能滞后）时加--no-index；
• 退出码与 ripgrep 一致：0有匹配、1无匹配、2出错，方便脚本判断。

全部 60 多个参数说明见 README.md 的 CLI Flags 表格。

四、理解 tgrep 为什么这么快

一句话原理：索引时把每个文件拆成所有重叠的 3 字节三元组并排序存储，查询时先用三元组反查出"可能命中的候选文件"，再用正则引擎并行验证——跳过 99% 无关文件，这就是毫秒级的来源。

tgrep index . # 一次性：把三元组倒排索引写入 ./.tgrep tgrep serve . # 每次会话：保持索引温热，监听文件变化 tgrep "pattern" . # 每次搜索：自动找服务器，毫秒级返回

搜索时按此优先级自动降级，命令完全不变：

1. 有服务器 → 走 TCP 查询，最快；
2. 有磁盘索引但无服务器 → 直接读.tgrep/；
3. 什么都没有 → 像 grep 一样扫全盘。

三元组的核心提取逻辑在 tgrep-core/src/trigram.rs，把 3 个字节压缩进一个u32，最多约 1670 万个无冲突的唯一三元组。

五、性能有多强：基准数据一览

官方基准只计时"索引已建好后的搜索"，且每次查询都启动全新客户端进程（含进程启动 + TCP 往返）。2026 年 8 月的完整扫描结果：

六个仓库的几何平均提速为Windows 14.6x、macOS 8.61x、Linux 2.82x。索引构建内存也受控：最大的 Chromium（50 万文件）峰值内存不到 470 MiB。完整方法论见 BENCHMARKS.md。

六、给 AI 编码代理的进阶玩法 🤖

如果你用 Codex 或 pi 这类编码代理，tgrep 提供一键集成的 MCP 搜索工具，让 AI 在仓库里享受同样的毫秒级检索：

bash install-agent.sh # 交互式选择代理与安装范围

安装后代理获得tgrep_search_code和tgrep_find_files两个工具，并带会话级索引预热。详细参数（freshness、max_results、file_types等）见 scripts/agent/README.md。代理侧的心智模型与降级策略总结在 AGENTS.md。

七、常见问题快速排查

八、项目结构导览

想深入源码时，按目录入手即可：

写在最后

tgrep 的定位非常清晰：把 ripgrep 的熟悉手感 + 预建三元组索引 + 常驻服务器组合起来，让你在大仓库里搜代码时不再等待。安装一条命令、体验两条命令，今天的指南到这里就够你上路了。祝搜索愉快！🚀

【免费下载链接】tgrepTrigram-indexed grep with a client/server architecture for fast regex search in large codebases locally项目地址: https://gitcode.com/gh_mirrors/tg/tgrep