大约两个月前我带着一个真实的检索需求开始在命令行里折腾一个新工具最后它被命名为 treg。当时我需要在公司的遗留代码库里找出所有出现过HZ_ERR_TIMEOUT的地方代码库有十几个模块、两万多文件里面还混着.min.js、.svg、打包产物和构建目录。用grep -r硬搜当然也能搜可结果里一半是压缩文件里的噪声一半是构建目录里的旧副本真正有用的调用点被淹没在几千条输出里。之后我试过ripgrep搜索速度确实快但还是要反复写排除参数而且我希望匹配结果能按调用链的顺序聚合输出而不是按文件路径机械排一遍。于是我开始自己写一个检索工具在目录树范围内用正则表达式筛选目标文件、控制遍历深度、跳过不需要的目录再把命中结果按业务需要格式化输出。这就是 treg名字取 tree目录树加 regex正则表达式两个词的缩写。treg 不是什么颠覆性的东西它解决的问题很具体当你面对的是一棵树而不是一个文件当搜索的行为不是“查一次就结束”而是反复在一个动态变化的目录结构里查找、对比、统计那么通用命令行工具就总会有那么几处不顺手。这篇内容围绕 treg 的定位、命令行设计、内部管线、选型理由、性能优化以及开发过程中踩过的真实问题展开。如果你也有写命令行工具的想法或者你经常需要在代码库里做精确检索这应该是一篇能直接抄作业的记录。1. 从一次糟糕的检索经历说起treg 要解决的真实问题1.1 grep -r 的四个具体痛点那次检索任务让我把grep -r的痛点从头到尾体验了一遍前后折腾了大概一个下午最后痛感集中在四件事上。第一排除规则写得比关键字还长。项目里要排除node_modules、dist、build、vendor、.git还要排除各种二进制资源目录grep -r配合--exclude-dir一条条写换一个目录要查历史命令才能想起上次用的参数。更麻烦的是它不支持像一个忽略文件那样集中管理。第二输出没有层级和组织感。grep -r默认把文件名放在每一行前面大量结果混杂在一起时很难看出某个文件下哪些行是成组出现的。我想要的是“按文件聚合再按行号增序排列”的结构必要时带上上下文这样看到一个命中就能顺带判断周围逻辑。第三大目录下容易卡顿。grep -r本质是 fork 出多个进程并行跑但在机械盘上、在大量小文件场景下没有预筛选机制就意味着每个文件都要从头扫一遍。那次在接近 5 万个文件的目录里搜一次耗时超过半分钟文件系统缓存一冷就奔着一分钟去。第四处理非文本文件时不透明。默认情况下grep会直接扫描二进制内容结果终端里突然冒出一串乱码和匹配行既污染输出也拖慢速度。虽然可以加-I参数但很多人根本不会主动加。那天搜索完我把命中的行导入到临时脚本里做了二次聚合才得到真正需要的调用点列表。这明显不正常检索应该是一次性的、快照式的、结果直接可用而不是搜索完还要自己做一遍数据清洗。1.2 已经有 rg 了为什么还要自己写我承认ripgrep在速度和默认忽略规则上做得相当好尤其是它自动读取.gitignore这个行为非常贴心已经解决了我上面提到的大部分问题。但我当时的诉求里有一个 rg 默认不提供的点匹配结果的分组与聚合方式。我想按照调用链顺序扫描整个调用栈先看到入口函数所在的文件再根据行号把调用点按深度缩进排列。rg 的输出是扁平的如果要看调用拓扑我要么用-A/-B手动补上下文要么写脚本再做一次解析。另外我的需求会持续演化和变更。今天要排除构建目录明天要按时间范围过滤日志文件后天还要对匹配结果做统计。与其每次给 rg 拼参数、给结果接管道不如做一个完全围绕自己场景设计的专用工具。它不必在所有指标上超过 rg只要在自己的应用场景里顺手、可控、能嵌入脚本就算有价值。这其实也是很多开发者写小工具的真实出发点不是为了证明自己比开源工具更聪明而是为了掌握一个小工具的全部逻辑让它长成自己需要的样子。1.3 treg 的设计基调从最开始我就给 treg 定了几个原则。首先是正则表达式为一等公民用户传入的第一个参数永远是 pattern。其次是目录树为默认搜索上下文不传路径时读取当前目录而不是从 stdin 读取。第三是默认输出必须结构化每行包含文件路径、行号、匹配文本但整体按文件分组展示。第四是支持程序化输出--json输出来后可以被脚本直接消费。最后还有一条很私人的原则默认安静出错才发声。没有命中时treg 不该打印一行“没有匹配结果”而是安静退出让脚本根据退出码判断结果。2. treg 的命令行设计与使用案例2.1 安装与最小可用场景treg 用 Go 写的安装方式就是用go install没有运行时依赖下载下来的二进制可以直接拷到服务器上用。在开发机上安装我习惯直接跑go install github.com/yourname/treglatest安装完成后最简单的用法是treg HZ_ERR_TIMEOUT ./legacy这条命令会在./legacy目录下递归搜索包含HZ_ERR_TIMEOUT的文本文件并把结果按文件分组输出。输出长这样legacy/module_a/service.go: 47: if err HZ_ERR_TIMEOUT { 52: return HZ_ERR_TIMEOUT legacy/module_a/client.go: 120: if errors.Is(err, HZ_ERR_TIMEOUT) {先输出文件路径换行后缩进列出命中的行号与内容。默认不带上下文想要上下文就加--context 3。2.2 常用参数全览我整理了一张参数表都是我在实际使用中真正高频依赖的参数说明示例--glob只搜索匹配该 glob 的文件可重复指定--glob *.go--exclude-glob反选过滤通常用于排除构建产物--exclude-glob *.min.js--ignore-dir目录名匹配即跳过可重复--ignore-dir dist--max-depth限制目录遍历深度0 表示不限制--max-depth 3--context每条命中前后显示的行数--context 2--ignore-case忽略大小写--ignore-case--fixed-strings把 pattern 当普通字符串处理--fixed-strings ab--json以 JSON 格式输出结构化结果--json--threads并行 worker 数量默认是 CPU 核数的 4 倍--threads 8--no-follow-symlink不跟随符号链接应对循环目录--no-follow-symlink--quiet不输出内容只根据是否命中设置退出码--quiet这些参数不是拍脑袋加的。--max-depth来自一次搜索构建缓存目录翻车的经历--fixed-strings来自我们经常在配置里搜包含、*等特殊字符的 key--no-follow-symlink则直接对应后文要讲的符号链接死循环事故。2.3 三个使用场景的完整命令第一个场景在 Go 项目里找到所有还没清理的调试日志。这类日志通常带有DEBUG标记而且最好排除_test.go文件里的测试样例treg log\.(Printf|Println).*DEBUG ./src --glob *.go --exclude-glob *_test.go --context 1第二个场景在日志目录里按时间正则抓某个错误码的上下文。线上的日志文件名带日期内容里每行开头是时间戳可以用正则精确限定treg 2025-06-1[0-5] .*ERR_AUTH ./logs/ --glob app-*.log --context 5 --ignore-case第三个场景统计某个函数在混合代码库里的所有调用点输出给脚本做序列化跟踪。这里直接上 JSONtreg func initSession ./services --glob *.go --json --context 0 calls.json拿到的 JSON 可以继续丢给jq做统计比如按目录统计命中次数jq group_by(.path) | map({path: .[0].path, count: length}) calls.json这些例子都指向同一个核心行为先用目录树缩小范围再用正则精确匹配最后用结构化输出对接下游。treg 把所有参数都放在命令层方便脚本化也方便在 shell 历史里复用。3. 目录树检索的核心管线从文件遍历到命中输出3.1 遍历阶段剪枝、忽略规则与符号链接处理treg 的第一个阶段是遍历目录树。这里我故意没有直接使用filepath.WalkDir的标准逻辑而是在它外面包了一层自制的剪枝控制。遍历时有一个很重要的规则先判断目录是否应该跳过再递归进入。如果忽略判断放在进入目录之后数据量一上来就会产生大量无意义系统调用。treg 的处理顺序是对当前目录先检查--ignore-dir、.gitignore以及--max-depth如果命中立即吞掉整个子树不再继续读取目录项。--max-depth的实现不是简单地统计路径分隔符数量而是记录从根路径开始经过的目录层级。比如treg test . --max-depth 2那么当前目录本身是第一层它下面的子目录是第二层子目录的内容不会被扫描。这样控制起来比较直观不会出现“明明传了一个绝对路径深度计数器从 0 开始导致结果和预期不符”的问题。符号链接的处理是个经典坑位。treg 默认会跟随符号链接目录但要记录已经访问过的真实路径对应的设备号和 inode。这样当两个目录互为符号链接指向时循环会被检测到不会无限递归。inode 检测的具体做法是调用os.Stat拿到syscall.Stat_t对比Dev和Ino字段跟 Go 标准库的filepath.EvalSymlinks相比这个方法更轻量不需要解析完整符号链接路径。3.2 匹配阶段文本识别、正则语义与逐行扫描进入匹配阶段前treg 要先判断一个文件是否值得读。这里我实现了三道筛选文件名 glob 筛选、大小上限筛筛选、二进制文件识别。前两个很直观二进制识别的处理逻辑值得一提。treg 会读取文件头部 8KB 数据计算其中 NUL 字节的比例以及 UTF-8 合法性。如果 NUL 字节比例超过 1%或者连续无效 UTF-8 序列出现多次就判定为二进制文件。这个阈值最早是从git的启发式里借鉴的实测下来在混合代码库中表现良好。它带来的直接好处是默认扫描不会再把图片、字体、序列化文件里的乱码匹配结果吐出来。真正的匹配过程是逐行进行的不是把整个文件一次性读入再处理。逐行最大的好处是内存占用稳定即使在几百 MB 的日志文件上也能保持极低的峰值内存。treg 内部用bufio.Reader按行读取每行去掉末尾换行符后交给正则引擎匹配。这里有一个大家容易忽略的性能细节如果 pattern 里完全没有正则元字符或者用户主动加了--fixed-stringstreg 会走字符串查找快路径而不是编译正则后跑 NFA。快路径用的是bytes.Contains在大文件上比正则引擎快上一个数量级。这个优化成本极低但收益非常明显。正则语义方面我选用了 Go 标准库regexp。它使用的是 RE2 语法不支持回溯引用比如\1但换来了一个关键承诺匹配时间与输入长度成线性关系不存在灾难性回溯把 CPU 打满的情况。这个取舍在后文的踩坑部分会有详细展开。3.3 输出阶段靠近“人”的格式设计输出阶段是整个工具最容易被低估的部分。命令行工具的体验差异一半来自搜索效率另一半来自结果呈现。默认情况下treg 把结果按文件分组组内按行号排序。同一个文件存在多条命中时文件路径只出现一次之后是缩进列表。这样的设计在终端里阅读效率最高因为眼睛可以先扫文件再逐行看命中内容。多数通用工具的做法是每一行都带上完整路径虽然方便脚本处理但人眼在终端里扫描时噪音很大。输出的时候还要处理一个细节匹配行的终端着色。treg 在 TTY 模式下用 ANSI 转义序列把命中文本标红但检测到输出被重定向到文件或管道时自动禁用颜色。这个逻辑很简单但避免了把一堆转义字符写进脚本日志的低级错误。JSON 输出结构由几个字段组成{ path: legacy/module_a/service.go, line: 47, column: 10, text: if err HZ_ERR_TIMEOUT {, context_before: [], context_after: [] }退出码遵循 Unix 惯例有命中返回 0没有命中返回 1发生错误返回 2。这个设计配合--quiet模式可以直接当作条件判断用if treg HZ_ERR_TIMEOUT ./legacy --quiet; then echo 发现残留错误码引用 fi4. 实现中的关键选型为什么是 Go 而不是 Python 或 Rust4.1 Go 的静态编译与分发优势treg 之所以用 Go 实现第一个理由听起来很实际分发容易。编译出来的二进制文件没有任何运行时依赖glibc 版本、系统库通通不相关直接scp到服务器上就能跑。这对“要在生产日志目录里做检索”这个场景至关重要因为很多服务器上根本不会给你装 Python 环境更别提ripgrep、fzf这类第三方工具。Python 写这种工具的优点是开发速度快、正则表达式语法完整但它的缺点是要部署就得带解释器或虚拟环境要么就得依赖一堆带manylinux后缀的 wheel折腾起来一点都不省心。另外Python 的os.walk遍历大目录时的性能比 Go 的filepath.WalkDir要差文件数量达到几万级别时感知非常明显。Rust 也很好性能甚至更好但我在这个项目上的目标不是追求极限性能而是快速迭代、易读、易维护。Go 的 goroutine 模型和标准库让我在实现并发扫描时少操了很多心。4.2 goroutine 让“遍历匹配聚合”管道特别好写treg 的并发结构是三段式管道遍历协程负责产出文件路径一组 worker 协程负责消费路径并执行匹配聚合协程负责收集结果并按文件分组输出。如果用 Go 的通道来表达核心逻辑简化之后大概是jobs : make(chan string, 256) results : make(chan matchResult, 256) go walkTree(root, jobs) for i : 0; i workerCount; i { go func() { for path : range jobs { matches, ok : searchFile(path, pattern) if ok { results - matchResult{path: path, matches: matches} } } }() }通道缓冲是为了避免遍历太快、匹配太慢时造成极端阻塞。实际测试中缓冲大小对吞吐的敏感度不高256 到 1024 之间表现都稳定。这套并发模型的优点是代码写起来直白不会出现手工管理线程池时常见的挂起问题。选型时我也考虑过直接把并发放在遍历阶段也就是多个协程同时遍历不同子树。后来放弃了因为文件系统的元数据读取本身并不是瓶颈真正的耗时在文件内容匹配上。多个协程同时 walk 反而会增加目录缓存争抢。4.3 RE2 引擎带来的安全性收益前面提到Go 标准库的regexp使用 RE2 语法不支持回溯引用。很多写脚本出身的人第一次用会觉得别扭比如有些人习惯用(https?:\/\/)?(www\.)?example\.com来同时匹配带或不带前缀的 URL这在 RE2 里完全没问题但如果想写([^]).*?\1来匹配对称 HTML 标签RE2 就不干了。我选择 RE2 最直接的理由是安全性。treg 会被我频繁用在几万甚至十几万文件的大目录上如果用户不小心写出了一个灾难性回溯的正则工具表现出的症状是整个进程 CPU 飙到 100%搜索像卡死一样没有输出。在服务器上如果碰到这种场景可能还要连累同一台机器上的其他任务。RE2 保证了匹配时间是线性的最坏情况下也只是慢而不会指数爆炸。这个安全感非常重要它让 treg 作为常驻脚本一部分使用时不需要额外加重试和超时保护。如果未来要支持 PCRE 系特性我大概率会引入一个带超时控制的独立引擎而不是直接替换现有路径。5. 实测性能与优化路径一次 10 万文件的扫描实验5.1 实验环境与基线数据treg 的目标场景是大目录所以我在一个接近真实的混合代码库里做了基线测试。这个目录里有 10.2 万个文件总大小约 2.8GB包含 Go、TypeScript、Java 代码也包括大量打包产物、图片和日志文件。实验环境是同一台 Linux 服务器CPU 8 核 16 线程内存 32GBNVMe 磁盘文件系统缓存先清理过。搜索的 pattern 是一个比较常见的字符串ERROR结果对比如下工具耗时最大内存命中行数grep -r46.8s约 300MB18422rg0.9s约 90MB18422treg优化前14.2s约 280MB18422treg优化后2.1s约 45MB18422解释一下grep -r的耗时主要来自每个文件都启动完整正则搜索且没有并行调度rg是标杆它在扫描和搜索上做了大量底层优化优化前的 treg 是初版逻辑串行读取文件内存大是因为一次读整个文件优化后通过并发和逐行扫描把指标大幅压低。5.2 瓶颈定位walk 和 match 的相对耗时优化不是盲目进行的我给它加过pprof做 CPU 分析。数据很明确目录遍历本身只占不到 5% 的耗时而 88% 的时间花在文件读取和正则匹配上。这说明问题不在 walk而在每个文件的处理方式。顺着这个结论我把优化方向定为减少每个文件上的无效工作。这里有两个路子。一是避免读取不可能匹配的文件也就是 glob 预筛选二是让匹配本身更快包括走固定字符串快路径以及让多个核心并行处理不同文件。对于固定字符串快路径效果立竿见影。初版我对每个文件都调用regexp.MatchString哪怕 pattern 只是普通字符串。后来加了检测逻辑如果 pattern 中不包含任何正则元字符或者用户显式指定--fixed-strings就直接用bytes.Contains。在同一目录上单测速度提升了 5 到 8 倍这在日志检索场景里体验相当明显。5.3 三步优化并发、预筛、复用缓冲区三步优化是从最容易改的先做起。第一步是加并发 worker让文件匹配跑满所有 CPU 核心。这个改动并不复杂上文已经展示过通道模型实测效果是把耗时从十几秒压到 4 秒左右。第二步是修正二进制文件检测策略。初版在匹配阶段才对文件头部做 NUL 字节检查这导致所有二进制文件都先被读了一遍。优化后遍历阶段就把“是否是二进制”标记好匹配阶段直接跳过大量图片、字体文件不再参与匹配。第三步是复用缓冲区。初版为每个文件新建bufio.Reader和临时切片文件数量上来后 GC 压力非常大。优化后改为从sync.Pool获取可复用的缓冲切片每处理完一个文件就归还。最大内存从约 280MB 降到了 45MB同时 GC 停顿明显变少。还有一个小优化值得一提如果文件大小超过了一定阈值默认 100MBtreg 会自动改为流式读取并分块匹配而不是逐行缓冲。这个阈值防止了单文件吞噬所有 worker 内存的情况。6. 踩坑实录开发 treg 过程中遇到的那些问题6.1 符号链接导致的目录死循环第一个真正的坑来自符号链接。开发中我用 treg 扫描/tmp下的一个临时项目结果程序跑了十几分钟都没有结束。当时第一反应是比赛谁先找出问题于是加了--max-depth 5发现还是不停。查看堆栈后定位到问题目录里有一个符号链接指向了上层目录filepath.WalkDir默认会跟随符号链接于是遍历逻辑在a和b两个目录之间反复横跳每次跳转路径还会变长一点直到路径长度超过系统限制抛错。解决办法是建立一个“已访问目录”集合用设备号和 inode 做唯一标识。每进入一个真实目录之前先检查它的 inode 是否已经出现过。这样做之后即使有两个不同路径指向同一目录也只会扫描一次。我在设计时把--no-follow-symlink做成可选参数但默认开启 inode 去重所以正常场景下根本不会走到死循环。6.2 二进制文件里冒出的一堆“命中”第二坑是二进制文件误匹配。初版没有做任何文本类型判断结果用 treg 搜索一个关键字的时突然匹配出大量路径打开看内容却是一堆乱码。原因是一些压缩包和序列化文件里恰好有目标字符串的字节序列。为了解决这个问题我首先在文件头部做了 NUL 字节检测这已经过滤了绝大多数二进制文件。但测试时发现某些 UTF-16 编码的日志文件也会被误判。后来我把二进制识别逻辑改成多条件综合判断NUL 比例、无效 UTF-8 序列比例、以及文件扩展名黑名单。这个方案比较实用代价是每类文件多读了最多 8KB 的数据换取默认场景下输出足够干净。这个设计也带来一个取舍如果用户确实想搜索二进制内容可以用--search-binary显式开启。我不会完全禁止搜索二进制文件因为某些场景下匹配自定义结构头部确实有用只是默认情况下不应该让它弄脏输出。6.3 用户正则把 CPU 打到 100% 的隐患第三坑来自用户行为。有次我在一个相当大的目录里搜索treg 突然没有任何输出CPU 却居高不下。第一直觉以为是死锁查了一会儿才发现问题出在正则语义上。初版为了兼容更多表达式我引入过一个支持回溯的第三方正则库。用户写了一个类似(a)b的 pattern这种表达式在回溯引擎上会出现灾难性回溯输入越长耗时越是指数增长。在大日志文件上它直接把这个进程变成了 CPU 杀手。这次事故让我下定决心把默认引擎切回 Go 标准库的 RE2。RE2 不会发生灾难性回溯最坏情况也只是线性时间。如果有人确实需要 PCRE 的特性可以显式编译一个带 PCRE 后端的版本但必须在命令行设置超时。我认为对于终端检索场景线性时间的安全感比少数高级语法重要得多。6.4 读入大文件导致的内存毛刺最后一个坑是在测试一个 4GB 的日志文件时发现的。初版为了简化实现用的是os.ReadFile把整个文件读进内存再按\n分割。结果在那个大文件上treg 的 RSS 直接冲到了 6GB 以上虽然机器内存够用但其他服务已经明显受影响了。教训很直接永远不要假设文件大小在可控范围内。修复方案是把读文件逻辑改为bufio.Scanner按行扫描并为大文件单独调大初始缓冲区。这样做之后处理 4GB 文件时峰值内存稳定在 100MB 左右速度也没有明显下降因为文件系统会自行优化顺序读场景。我把“流式处理”定成了一个原则任何可能面对用户文件的逻辑默认都必须支持流式读取而不是一次加载。7. 下一步从命令行工具走向常驻检索服务7.1 增量索引缓存目前的 treg 每次搜索都完整遍历目录树这在文件数量较小的项目里没有问题但到了几十万文件的规模即使遍历只占 5% 的耗时绝对时间仍不可忽略。我打算加入一个可选的索引缓存层第一次扫描时记录下每个文件的路径、修改时间、文件大小和 inode后续扫描时只处理发生变化的部分。这个设计很像备份工具里的增量逻辑。索引文件会存放在.treg_cache里并使用文件签名校验避免目录本身出现损坏。如果用户改了文件内容但是修改时间被保留了可以通过文件大小加内容哈希做二次校验不过这会增加额外 IO所以哈希默认只在索引命中时才执行。7.2 TUI 交互模式命令行的缺点是搜索完成后如果想要交互式跳转体验不够流畅。很多检索场景其实需要“看到结果后再以某个文件为起点继续深入”。我计划增加一个可选的 TUI 模式在终端里展示结果列表后支持用方向键在文件之间跳转按回车直接查看文件内的上下文。这个想法并不新鲜fzf和vim的 quickfix 指令都类似。但把它内嵌到 treg 里可以让用户在同一工具内完成“搜索 - 浏览 - 重新搜索”的循环不需要在 shell、编辑器、终端之间切换。技术上可以用 Go 的tview或者纯 ANSI 控制序列实现我倾向于后者少一层 GUI 框架依赖。7.3 文件监听更进一步我还想增加一个--watch模式。进入这种模式后treg 会基于索引缓存监听目录变化当用户新增、删除、修改文件时只对受影响文件重新执行搜索增量更新结果。这个工具会变成一个“常驻搜索服务”适合用于实时观察日志中新增的错误码或持续跟踪某个接口调用频率。实现文件监听不能只依赖fsnotify因为目录树可能重新挂载缓存索引也需要预热恢复。更稳妥的方案是周期性扫描加事件驱动触发结合事件负责精准通知扫描负责兜底覆盖。最后再分享一点个人体会做这类工具最值得投入的地方不是炫技式的算法而是对真实使用场景的洞察。treg 从最初只有几个参数的雏形到现在的并发管线、二进制过滤、结构化输出每一步都是在实际检索过程中被“难用”逼出来的。如果你也想写一个属于自己习惯的命令行工具我的建议是先用最短路径把最小用例跑通然后每次使用过程中遇到不舒服的地方就记录成下一个功能。工具会慢慢长成你手指记忆的一部分这种掌控感是用别人的工具替代不了的。