tree++ 1.0.0 参数说明

July 31, 2026 · View on GitHub

tree++ 是仅支持 Windows 的命令行程序。

语法

treepp [<PATH>] [<OPTIONS>...]

PATH 默认为当前目录，可以放在参数之前、之间或之后，最多只能指定一个路径。使用 -- 终止参数解析：

treepp /F -- -switch-like-directory

三种参数风格可以混用：

/F、/DU 等 CMD 参数不区分 ASCII 大小写；
-f、-H 等短参数区分大小写；
--files 等长参数区分大小写，带值的参数也支持 --option=value。

除 --include 和 --exclude 外，每个参数最多出现一次。 --auto-exclude 与 --no-auto-exclude 冲突。

执行与输出模式

默认是流式文本模式：每次读取并排序一个目录，在遍历过程中输出完整行；当 stdout 是交互式终端时会定期刷新，不在内存中保留整棵树。

--batch 会在内存中构造可见结果，启用有上限的 Rayon 线程池、目录累计大小和结构化格式。默认线程数是 min(可用逻辑处理器数, 8)，且至少为 1。

默认格式是文本。JSON、YAML、TOML 必须使用 --batch。

完整参数表

等价参数	值	含义
`--help` `-h` `/?`	—	显示帮助并退出
`--version` `-v` `/V`	—	显示版本并退出
`--files` `-f` `/F`	—	包含文件
`--full-path` `-p` `/FP`	—	每个条目显示完整路径
`--size` `-s` `/S`	—	显示文件字节数
`--human-readable` `-H` `/HR`	—	显示易读文件大小；隐含 `/S`
`--date` `-d` `/DT`	—	显示最后修改时间
`--disk-usage` `-u` `/DU`	—	显示目录递归字节总数；隐含 `/S`，需要 `/B`
`--ascii` `-a` `/A`	—	使用 ASCII 连接线
`--no-indent` `-i` `/NI`	—	不显示连接符
`--reverse` `-r` `/R`	—	反转确定性顺序
`--level` `-L` `/L`	非负整数	限制可见递归深度
`--include` `-m` `/M`	glob	包含匹配文件；可重复
`--exclude` `-I` `/X`	glob	排除匹配的文件或目录名称；可重复
`--gitignore` `-g` `/G`	—	应用继承的 `.gitignore` 规则
`--auto-exclude` `/AE`	—	启用开发目录排除预设
`--no-auto-exclude` `/NAE`	—	显式保持预设关闭
`--all` `-k` `/AL`	—	包含带 Windows 隐藏属性的条目
`--report` `-e` `/RP`	—	追加可见条目统计和耗时
`--no-win-banner` `-N` `/NB`	—	不获取、不渲染原生 banner
`--silent` `-l` `/SI`	—	不写 stdout 和成功通知；需要真实输出文件
`--output` `-o` `/O`	文件或 `-`	同时写文件，或显式选择 stdout
`--format` `/FMT`	`text`、`json`、`yaml`、`toml`	选择输出格式
`--errors` `-E` `/ERR`	`warn`、`strict`、`ignore`	选择可恢复扫描错误策略
`--batch` `-b` `/B`	—	启用批处理
`--thread` `-t` `/T`	正整数	设置批处理扫描线程；需要 `/B`

文本布局

默认 Unicode 连接线采用原生四列宽布局：

├───
└───
│

/A 使用 +---、\---、| ；/NI 保留层级空格但去掉连接符。文件先于子目录输出，名称使用确定性的 Windows 不区分大小写排序；/R 反转这个顺序。

不指定 /F 时，文件不可见，也不计入 /RP 文件数。/DU 仍会读取计算累计大小所需的后代，但 /L 继续限制可见节点、结构化 children 和统计数。

默认显示原生 banner。每次运行只从 %SystemRoot%\System32\tree.com 获取一次，并使用当前 Windows OEM 代码页严格解码；探测使用保证不存在的路径，不写文件系统。获取、解码或解析失败会以输出错误码 3 终止；/NB 可完全跳过探测。

深度、匹配和可见性

根目录深度是 0：

/L 0 只显示根以及请求的 header/report；
/L 1 显示直接子项；
更大值按相应层数显示后代。

glob 按 ASCII 不区分大小写匹配条目名称：

/M 只限制文件；目录仍会遍历，以便发现匹配后代；
/X 排除匹配文件以及匹配目录的整个子树；
多个 /M 之间是 OR，多个 /X 之间也是 OR；
/G 通过同一扫描管线加载并继承 .gitignore 规则。

带 Windows 隐藏属性的条目默认被排除，使用 /AL 才显示。目录 reparse point 和符号链接在其余规则允许时会显示，但不会递归，以避免循环。

/AE 按名称（不区分 ASCII 大小写）排除以下目录：

.git .hg .idea .mypy_cache .next .node .nuxt .pytest_cache
.ruff_cache .svn .venv .vscode __pycache__ build dist
node_modules target venv

此预设默认关闭，只作用于目录，不作用于同名文件。

扫描错误策略

可恢复错误包括打开/迭代目录、读取目录项或 metadata，以及读取、解析、构建 .gitignore 规则失败。

策略	行为	只有可恢复错误时的退出码
`warn`（默认）	继续，保留排序后的诊断，并向 stderr 写警告	0
`strict`	遇到第一条诊断立即停止	2
`ignore`	继续，不保留诊断详情	0

warn 和 ignore 都会令结构化文档中的 complete 为 false。大小溢出等不可恢复扫描错误不受策略影响，始终退出 2。

文本警告只写 stderr。结构化输出保存稳定的诊断记录；warn 下也会向 stderr 报告。人类可读诊断中的控制字符会被转义。

输出目标

不指定 --output 时只写 stdout。指定真实输出路径时，同一内容默认同时写 stdout 和文件；加 /SI 后只写文件。--output - 显式选择 stdout，不能与 /SI 组合。

未指定 --format 时，真实输出路径根据 .json、.yml、.yaml、 .toml 推断格式，其他扩展名均为文本。显式 --format 优先于扩展名。

文件输出采用事务流程：

创建缺失的父目录；
在目标目录创建唯一临时文件，写入、刷新并同步；
全部成功后才以临时文件原子替换目标；
扫描自动排除输出目标和活动临时文件，包括指向同一文件的等价路径。

因此渲染、序列化或文件写入失败时，已有目标文件保持不变。流式 stdout 中已经被观察到的前缀无法回滚。

文件提交成功后，程序向 stderr 写 output: <path>。/SI 会隐藏这条通知，但不会隐藏扫描警告或致命错误。结构化 stdout 不会被通知污染。

结构化输出

JSON、YAML、TOML 序列化同一个递归 treepp.pretty.v2 文档，并以一个换行结束：

schema
complete
diagnostics[]
summary?                 # 使用 /RP 时存在
root
  type = directory
  name
  path                   # 根始终存在
  modified?              # /DT
  disk_usage?            # /DU
  children[]
    type = directory | file
    name
    path?                # 后代使用 /FP 时存在
    modified?            # /DT
    disk_usage? | size?  # 目录 /DU；文件 /S 或 /HR
    children[]?          # 仅目录

v2 不提供旧 schema 兼容开关。可选字段直接省略，不序列化为 null；所有格式中的字节数都是整数；时间为 UTC RFC 3339、毫秒精度；node 顺序与文本一致，并遵守 /R。

TOML 整数不能超过 i64::MAX；越界属于输出错误，不会替换已有目标文件。

常用示例

# 原生风格文件树，不探测 banner
treepp C:\src /F /NB

# 两个包含 glob、一个排除目录、隐藏条目和深度 3
treepp C:\src /F /AL /L 3 /M *.rs /M *.toml /X target

# 可见目录累计大小和统计，使用四个批处理线程
treepp C:\src /B /F /DU /RP /T 4

# stdout 输出纯 JSON
treepp C:\src /B /F /S /DT /RP --format json

# 只原子写入 YAML 文件
treepp C:\src /B /F --format yaml /O reports\tree.yaml /SI

# 第一条可恢复扫描错误即失败
treepp C:\src /F --errors strict

限制汇总

/DU 需要 /B；
JSON、YAML、TOML 需要 /B；
/T 需要 /B，且必须大于 0；
/L 接受 0 或正整数；
/SI 需要真实输出文件，与 /O - 冲突；
/AE 与 /NAE 冲突；
只有 /M、/X 可重复；
只能指定 0 或 1 个路径。

退出码

代码	含义
0	成功，包括仅发生可恢复错误的 `warn`/`ignore` 扫描
1	CLI 或配置错误
2	扫描或匹配失败
3	渲染、banner、序列化、stdout/stderr 或文件输出失败