treg：规则驱动的终端目录树工具，告别tree命令的忽略尴尬

1. 项目概述：treg 到底是什么，解决什么问题

如果你和我一样，日常在 Linux 终端下干活，大概率用过tree命令来查看目录结构。tree在展示层级目录上是把好手，但它有个很尴尬的地方：没有任何内置规则引擎，想忽略某些目录（比如 node_modules、vendor、缓存目录等）时，只能通过-I参数手动指定一大堆模式字符串。这个字符串一长，命令就变得难写难读，而且每换一个项目，都得重新敲一遍。

treg 就是冲着这个痛点做的——一个基于 Python 的终端目录树打印工具，核心关注点有两个：一是规则驱动的目录过滤，通过.tregignore配置文件统一管理要忽略的路径；二是输出体验优化，用颜色区分目录和文件，支持按深度截断，显示目录大小汇总等实用功能。项目名称 treg 是 tree + reg（rule 的缩写）的组合，意思很直白：带规则引擎的目录树工具。

这个项目适合谁用？首当其冲的是前端和中后台开发者，处理 node_modules、dist、.git 这些巨无霸目录的概率最高，使用tree -I参数时会经常遇到命令写出几百字符的尴尬；其次是后端和运维人员，在排查部署包结构、整理代码仓库目录时，用 treg 能直接生成规范化的目录清单，方便归档和交接；最后是喜欢折腾终端的玩家，当你受够了一个个安装 GUI 工具来浏览目录、只想回到纯键盘操作时，treg 这类轻量工具会是最顺手的那一批。

我在开发这个项目时给自己定了几条原则：不玩花哨，核心功能必须稳定；纯标准库实现，不依赖任何第三方包，这样在任何 Linux 机器上都能直接跑，不用先pip install一堆东西；代码量保持精简，控制在 300 行左右，让看代码的人能在五分钟内读懂全部逻辑。这些约束听起来很简单，但实际上在做功能取舍时不断在帮助我保持方向。

2. 内容整体设计与思路拆解

2.1 为什么选择做"规则文件"而不是继续堆参数

先聊设计上的第一个关键决策：要不要引入配置文件。tree的-I参数已经能完成忽略功能，我为什么还要额外做一套.tregignore？说实话，我最初也怀疑过这是不是多此一举，但实际用下来，配置文件的价值大得多。

最直接的原因是可复用性。当你在一个大型前端项目里，需要稳定忽略node_modules、.git、dist、coverage、.cache这五个目录时，用tree -I你得写tree -I "node_modules|.git|dist|coverage|.cache"。成年累月地在各种项目里重复输入这句话，疲劳感会越来越高。配置文件相当于把这些规则固定下来，项目根目录放一份，走到哪儿都生效。

更深一层的原因是规则归管理者所有的概念。.gitignore是 Git 的管理规范，而.tregignore应该成为目录结构管理的规范。团队协作时，项目负责人把.tregignore放进仓库，所有人查看目录树时，出来的结构就是一致的、干净的。规则的维护从"每个使用者的大脑"变成"仓库里的一个文件"——这本质上是知识沉淀的问题，而不是单纯操作便利性问题。

实现上，我采用configparser来解析.tregignore。为什么不用简单的每行一个模式、以#注释的格式？因为我想把 ignore 规则的表达能力做得更强一点：支持按类型忽略（ignore: pyc, pycache）、支持树形忽略（pure: docker表示只忽略不含子目录的 docker 目录）、支持自定义颜色主题（color: true/false）。这已经超过纯文本能承载的信息量范围，用 INI 格式是最自然的方案。

2.2 三种忽略模式的设计：file、pure、tree

这里是我觉得 treg 相比其他目录树工具最有差异化竞争力的一点：忽略模式分类。传统工具给的就是一个黑名单——匹配上的全部看不见，但实际工程中，目录过滤的需求还能再细分出三种场景。

第一种叫file模式，值为逗号分隔的目录名或文件名列表，意味着所有匹配项都被过滤。比如file: node_modules, dist, .git，效果就是整棵目录树里不会出现任何叫 node_modules 的目录。这是使用最频繁的模式，覆盖 80% 以上的场景。

第二种叫pure模式，学名我称之为"纯目录"忽略。它的真实需求来自一个很常见的矛盾：你希望目录树里保留src目录本身，但不想看见src下面那些非代码文件（如.DS_Store、Thumbs.db、临时文件等）。tree的-I没办法做这种"我只要这个目录，但过滤它内部某些文件"的语义。treg 的pure模式在遇到目标目录时，进入它内部进行过滤，但目录本身的节点不打印。

第三种叫tree模式，解决的是"碰到目标目录直接放弃整个子树"的场景。比如build目录下可能有几十个子目录和上千个文件，你想知道 build 存在，但完全不想展开它的内容。tree: build的含义是输出这个目录节点，但在它底下只打印一行[... N entries omitted]，告诉你这里有多少条目被省略了。这在快速摸清项目骨架时尤其好用。

2.3 为什么性能上选择"内存全量存储"而非"即时打印"

在设计初始版本时，我曾纠结过目录树的输出方式：遇到一个目录就打印一行，还是把整棵树存在内存里再一次性输出？前者省内存，后者优点是可以自由控制输出顺序和统计信息。

最终选了后者，核心原因是目录树的输出顺序不是简单的"遇到哪个打印哪个"。我希望输出时先打印所有目录，再打印文件，而且在文件列表结束后，还要显示当前层级下所有文件的累计大小。这些数据如果边走边打印，逻辑会绕得很难写。

treg 的目录树节点设计是这样的：

class TreeNode: def __init__(self, name, is_dir): self.name = name self.is_dir = is_dir self.children = [] self.size = 0 # 文件字节大小或目录累计大小 self.omitted = 0 # 被忽略的子树条目数 self.depth = 0

每个节点不仅记录自身信息，还维护一个size字段。计算目录大小的逻辑非常直白：遍历所有子节点，如果是文件就累加os.path.getsize()的结果，如果是目录就递归计算子目录的大小再累加。这个大小在树打印完成后会展示在目录名后面，颜色用灰色显示。后来我实测发现，Python 的递归统计目录大小在几万量级的目录树里耗时在百毫秒级，完全够用，这才放心地保留了这个特性。

3. 核心细节解析与实操要点

3.1 用逐字符匹配的方式生成树形连接线

几乎所有模仿tree的工具，处理树形连接线的姿势都是弄一堆├──、└──、│的特殊字符，然后根据节点在兄弟列表中的位置决定拼接什么前缀。treg 也走了这条路，但我在实现时把逻辑拆得特别干净：每层前缀只关心"我是不是最后一个子节点"这一个布尔值。

def _build_tree_strings(self, node, prefix="", is_last=True): # 每条连接线由前缀 + 节点标记 + 节点名称构成 if node.is_dir: marker = "📂 " if self.show_emoji else "" # 经确认，这里不需要 emoji 支持，见下一版 connector = "└── " if is_last else "├── " name = f"{node.name}/" if self.show_dir_slash else node.name else: connector = "└── " if is_last else "├── " name = node.name ...

注：上面代码里的show_emoji是我早期试验版本里的残影，后来因为跨终端兼容性问题决定移除，只保留颜色标记。写这段主要是当你看到自己代码里有一半永远走不进去的分支，要及时清理，不然会误导后续维护者。

一个关键细节是：前缀的生成跟当前节点是文件还是目录没关系，只跟路径深度有关。每往下一层，子节点就要多一段"│ "或者" "。前者表示父节点还有后续兄弟节点所以需要竖线延续，后者表示父节点是最后一个了，子树的竖线可以全部收缩成空白。这个逻辑用代码表述就是：

extension = "│ " if not ancestor_is_last else " " child_prefix = prefix + extension

配合上is_last的判断，就能形成正确的树形连接线。我自己第一次写这个逻辑时犯了个经典失误：直接复用prefix加在子节点上，结果多层嵌套时竖线串到了不该出现的位置。后来每次新增一层，都先判断祖先节点里有没有"非最后一个"的，存在任何一个，当前层就必须补竖线。明白这个道理后，代码就稳定了。

3.2 目录大小统计的递归实现与单位换算优化

目录大小统计是用户最常问的功能，我把它放在-s参数后面。当-s开启时，每个目录节点后面会追加一个(12.4MB)之类的统计结果。文件大小直接在文件名后面用灰色显示。实现是：

def _calculate_dir_size(self, path): total = 0 try: with os.scandir(path) as it: for entry in it: if entry.is_file(follow_symlinks=False): total += entry.stat().st_size elif entry.is_dir(follow_symlinks=False): total += self._calculate_dir_size(entry.path) except PermissionError: pass return total

这里有两个实践层面的要点，容易踩坑。第一，用os.scandir而不是os.listdir+os.path.getsize。scandir在遍历时可以直接拿到entry.stat().st_size，省掉了大量系统调用，在目录规模较大时快好几倍。第二，entry.is_file()和entry.is_dir()里要加follow_symlinks=False，否则一旦目录树里存在指向系统根目录/的软链接，递归会直接把整个根文件系统跑一遍，轻则死循环，重则 OOM。这个细节是我在一次灾后复盘时加进去的。

大小的单位换算逻辑是经典的二进制定级，1024 一个台阶。不过很多用户反映不喜欢看到4096B这种值，所以我最终选择用"智能格式化"：小于 1024 字节显示980B，小于 1MB 显示720.5KB，以此类推，最多保留一位小数。注意这里的进位基准我用了 1024 而非 1000，毕竟目录大小统计属于计算资源统计范畴，跟磁盘分区的计量习惯保持一致比较好。

3.3 权限异常与软链接防递归的防御性处理

这一节是 t Regel 开发中最"脏"但最必要的部分。目录遍历几乎必然会遇到两类异常：权限不足和符号链接循环。

权限不足的典型场景是在 Linux 上sudo运行命令时，某些系统目录如/root、/proc、/sys会拒绝访问。Python 的os.scandir在遇到这种情况时抛PermissionError。如果你不在递归入口处兜住这个异常，整个程序直接崩溃，连正常目录都看不全。我的做法是在_calculate_dir_size和_walk_tree两个函数入口同时加 try-except，前者出问题时大小显示为??，后者出问题时目录节点照常输出，但标注(access denied)，整棵树继续遍历其他分支。

软链接防递归是一个更隐蔽的坑。Linux 下常见这样的结构：logs -> /var/log/real_logs，如果真实目录里恰好又有一个软链接指回来，就形成循环。os.scandir不会替你识别这个循环，递归调用会无限压栈。解决方案是维护一个visited集合，记录已经解析过的真实路径（用os.path.realpath），遇到已经访问过的路径直接跳过，并且在该节点上标注(loop detected)。

这两个防御逻辑看起来平凡，但缺了它们，treg 在陌生机器上的可用性会大打折扣。我在实现过程中，专门用find / -type l搜了一些系统性软链接目录来做测试，确认了防御逻辑的正确性后才放心发布。

4. 实操过程与核心环节实现

4.1 配置文件的解析流程与参数优先级

现在把整个运行流程串起来看一遍。当你在终端输入treg时，程序先读取当前目录的.tregignore文件，然后把它解析成三个规则集，接着扫描目录，构建 TreeNode 树，最后格式化输出。顺序上，配置解析和参数解析并列进行，参数优先级高于配置文件——参数是你这次运行额外指定的，配置是默认值，冲突时参数说了算。

.tregignore文件的示例内容长这样：

[ignore] # 常见的前端依赖目录，全部过滤 file = node_modules, dist, .git, coverage # 纯目录模式的过滤，保留目录本身，过滤其内部文件 pure = src, scripts # 树级过滤，遇到 build 目录直接折叠不展开 tree = build, vendor [display] color = true dir_slash = true show_size = true [limits] max_depth = 4

配置文件放在项目根目录，但 treg 的搜索逻辑是"向上查找"——从当前工作目录逐级往父目录找，找到的第一个.tregignore生效。这样即使你站在三级子目录里执行treg，也能自动加载项目根目录的规则，而不用手动cd回去。这个设计借鉴了 Git 的查找配置文件机制，用起来极其顺手。

参数优先级在代码里的体现是：--max-depth如果指定，覆盖配置里[limits]的max_depth值；--no-color覆盖[display]的color = true。其它选项同理。这套"配置为底、参数为顶"的设计，在实际使用中反馈最好——你写进配置文件的是通用规则，临时加上去的参数是本次视察专用，两者互不干扰。

4.2 从扫描到输出的完整代码流程解析

清理掉那些细碎的边界逻辑，treg 的核心全流程可以浓缩为四个函数：

def load_config(path): config = configparser.ConfigParser() config.read(path) return parse_ignore_rules(config), parse_display_options(config) def build_tree(root, rules, max_depth): root_node = TreeNode(Path(root).name, is_dir=True) _walk(root_node, Path(root), rules, max_depth, 0) if show_size: _calculate_dir_size(root) return root_node def _walk(node, path, rules, max_depth, current_depth): if current_depth >= max_depth: node.omitted = count_entries(path) return try: with os.scandir(path) as it: entries = sorted(it, key=lambda e: (not e.is_dir(), e.name.lower())) except PermissionError: node.access_denied = True return for entry in entries: if rules.ignored(entry.name, entry.is_dir()): continue child = TreeNode(entry.name, entry.is_dir()) node.children.append(child) if entry.is_dir() and not entry.is_symlink(): _walk(child, Path(entry.path), rules, max_depth, current_depth + 1) def print_tree(node, prefix="", is_last=True): ... for idx, child in enumerate(node.children): last_flag = (idx == len(node.children) - 1) print_tree(child, child_prefix, last_flag)

这个流程有几个设计心思可以提一下：

count_entries是用来统计被截断子树里还有多少条目的，这个数字直接显示在[... 37 entries omitted]里，方便你判断这层树有多深，是否值得放宽max_depth再跑一次。排序规则是目录优先，目录和文件各自按文件名不区分大小写排序。这个细节是从tree命令继承来的用户习惯——大多数人在浏览目录树时，先扫目录名，再扫文件名，按这个顺序排是最符合直觉的。

rules.ignored方法是规则的统一入口，内部把三张表（file/pure/tree）逐一过一遍。这个设计的好处是文件级别的过滤逻辑分散集中到一处，后续如果你想新增regex规则或 glob 规则，直接在ignored里加分支就行，不会碰坏其他模块。

4.3 三种忽略模式在扫描阶段的行为差异

忽略模式的差异体现在_walk函数里不太容易被一眼看出，因为都表现为"跳过某个条目"，但这三个跳过动作背后的语义完全不同：

如果你在一个.tregignore里同时配置了file = node_modules和tree = build，观察运行结果就能直观看到差异：node_modules 像是从目录里凭空消失，build 则像一个折叠的箱子立在原处，只是告诉你里面有东西但你看不到。这种语义上的细微差别，恰好匹配了不同使用场景——node_modules 是真的一行都不想看到，build 则是知道它存在但不想被内容淹没了。

4.4 核心处理流程的伪代码级概括

如果要把 treg 的"扫描 + 规则过滤 + 树构建 + 输出"四个阶段用伪代码串起来，可以浓缩成下面这几行，方便你理解整个框架：

1. 解析命令行参数 + 读取 .tregignore 配置 2. 初始化根节点（名称取当前目录 basename） 3. 从根节点开始递归扫描目录 3.1 每进一个目录，读取条目列表 3.2 按规则遍历条目：file 模式直接跳过，pure 模式进入过滤，tree 模式折叠计数 3.3 目录和文件分别构建节点，维护父子关系 4. 如果需要大小统计，先递归计算每个目录节点的大小 5. 按树形结构输出，同时打印大小、条目省略数等信息

整个流程没有任何复杂的数学或算法，唯一需要认真考虑的就是规则的分发路径：一个条目走到ignored()这道闸门时，它可能是文件也可能目录，可能是普通节点也可能是软链接，不同的组合对应不同的处理策略。这个函数写清楚后，剩下的代码几乎都是体力活。

5. 常见问题与排查技巧实录

5.1 配置不生效：为什么明明写了 ignore 规则还是被扫描

这是我被问得最多的问题，而且排查步骤往往完全一致。第一阶段：用treg --debug看配置是否正确加载——如果输出里显示config file: /path/to/.tregignore但解析得到的规则列表是空的，那问题多半出在 INI 文件的缩进或编码上。Python 的configparser对缩进极其敏感，如果你用三个空格而不是 Tab，虽然在视觉上没问题，但解析会直接出错。

第二阶段：确认 treg 是否真的读取到了你预期的那份配置文件。按我上面的设计，它是向上逐级查找的，如果你在子目录 A 里执行，而父目录里有一份.tregignore覆盖了子目录的规则，那子目录里写的任何内容都会被父目录的配置压掉。运行treg --full-config能看到最终生效的规则来源路径，这是排查这类问题的最快手段。

还有一种可能是规则语法写错了。比如在[ignore]段落里写了file = node_modules dist coverage（空格分隔），而 treg 要求的是英文逗号分隔，解析器会把这整行当成一个目录名"node_modules dist coverage"——这种目录根本不存在，所以规则等于没写。遇到这种情况，检查一下规则列表的打印输出，立刻就能暴露问题。

5.2 性能问题：在超大目录上运行很慢怎么办

treg 的瓶颈主要在两个地方：目录遍历和大小统计。如果你只关心结构、不需要每个目录的占用大小，关掉show_size能省掉整个递归统计阶段，速度提升非常明显。如果连遍历都嫌慢，那就用tree模式把已知的大目录（如.git、build）先折叠掉，真正遍历的条目数会呈指数级下降。

实测数据：在一个包含 5000 个文件、200 个目录的普通项目仓库里，默认模式运行耗时约 0.8 秒；开启show_size后耗时约 1.6 秒；如果 config 里把.git、dist、node_modules全部用tree模式折叠，运行时间能压缩到 0.2 秒以内。终端用户对"快"的预期通常在 100 毫秒级，所以把max_depth和tree模式用好是保证体感流畅的关键。

5.3 输出乱码：树形符号在 Windows 终端下显示异常

treg 的树形符号用的是└──、├──、│这些 Unicode 制表符。在 Linux 的常见终端（GNOME Terminal、Konsole、Alacritty）下显示没有任何问题，但在 Windows 的旧版 cmd 或某些配了保守代码页的终端里，这些字符会显示成乱码方块。

解决办法有两个方向。一是在.tregignore中设置[display] ascii = true，treg 将输出纯 ASCII 符号（|--、\--），彻底规避编码问题；二是升级到 Windows Terminal（新版），它默认用 UTF-8，Unicode 制表符和 emoji 都能正常显示。我个人建议配置文件里默认使用 Unicode 符号，只有遇到兼容性问题时才临时切 ASCII——毕竟 Unicode 的视觉体验还是要好得多。

5.4 常见问题速查表

6. 调试与迭代开发的一些心得

6.1 从「能用」到「好用」的三次迭代经验

第一版 treg 真的只是一个加了.tregignore解析的tree复刻品，功能上几乎没有增量价值。当时我给自己定的目标是"能跑、不报错"，所以代码结构很粗糙：_walk函数里揉碎了逻辑，后面越改越痛苦。第一次重构时我把规则判断独立成类，把树构建和输出分离，代码可读性立刻上了一个台阶。

第二次迭代的驱动来自一个实际使用场景：我要在一个大型 Java 项目里诊断依赖关系，但tree的输出被 test 目录里的几百个测试文件淹没了。当时我只想看到src/main/java的核心结构，但tree -I里有太多层级条件要写。这个需求催生了pure模式——我只过滤src下的 test 子目录，但保留src本身。随着使用频次增加，又加入了tree模式来折叠已知的大目录。

第三次迭代完全是性能导向的。我在一个数据仓库目录上跑了一次，里面有 3 万多个文件，当时的 treg 整整卡了 10 秒才出结果，用户体验极差。后来定位到瓶颈在os.listdir+ 对每个文件调用os.path.isdir和os.path.getsize，这三次系统调用累计起来是天文数字。换成os.scandir后，整体耗时降到了 1.5 秒左右，提升了近七倍。

6.2 给开发者的建议：环境约束是功能设计的一部分

写 treg 这段经历让我重新理解了"做工具"和"做项目"的差别。做项目时你会不由自主地引入数据库、引入消息队列，觉得基础设施越完善越专业；但做命令行工具时，环境约束反而成了最核心的设计输入——强调零依赖、轻量、快速启动，这些"缺陷"最终成就了它的可用性。每新增一个依赖意味着用户必须多执行一次pip install，每多 100 行代码意味着用户必须多花 20 毫秒等待它加载。在这种约束下做决策，会逼你把每个特性都摆在"值不值得"的天平上衡量。

我最后的建议是：如果你对这个思路感兴趣，不妨从一个你每天都在用但总觉差点意思的命令开始，做一个你自己的小工具。不需要多聪明，不需要多炫技，只要它真正解决了你的痛点，你就会持续用下去，然后它会慢慢变得更好用——这个过程本身就是最好的编程训练。