tree-generator/Releases/v1.0.0/docs

目录树生成脚本 (tree_gen.py)

一个轻量级的 Python 命令行工具，用于生成目录树结构和文件列表，支持忽略配置、深度限制、多种输出格式，专为 Windows 平台优化。

功能特性

编号	功能	说明
F013	路径输入	支持命令行传入目标目录路径，兼容相对路径和绝对路径
F014	忽略配置	自动加载 .treeignore / .gitignore，内置 .git、node_modules、__pycache__ 等常见忽略项
F015	递归遍历	递归扫描子目录，生成完整树形结构，自动检测符号链接循环
F016	目录树生成	使用 ├── └── 字符绘制树形结构，缩进正确，目录名带 / 后缀
F017	文件树生成	列出所有文件（含目录），带完整路径和文件大小
F018	终端输出	终端直接显示格式化的树形结构和统计信息，自动处理 UTF-8 编码
F019	Markdown 保存	默认保存为 tree_output.md，包含目录结构代码块、文件列表表格和统计信息
F020	统计信息	显示目录数、文件数、总大小（自动格式化为 B/KB/MB/GB）

环境要求

• 操作系统: Windows 10/11（也兼容 Linux/macOS）
• Python: 3.8 或更高版本
• 依赖: 仅使用 Python 标准库，零第三方依赖

安装方法

无需安装。确保系统已安装 Python 3.8+ 即可直接使用：

python --version

如果显示 Python 3.8 或更高版本，即可开始使用。

使用方法

基本语法

python tree_gen.py [路径] [选项]

命令行选项

选项	简写	说明	默认值
path	—	目标目录路径	当前目录 (.)
--output	-o	Markdown 输出文件路径	tree_output.md
--depth	-d	最大递归深度（整数）	无限制
--files-only	-f	仅显示文件树	关闭
--dirs-only	-D	仅显示目录树	关闭
--ignore	-i	忽略配置文件路径	自动检测
--help	-h	显示帮助信息	—

常用示例

:: 生成当前目录的目录树
python tree_gen.py

:: 生成指定目录的目录树
python tree_gen.py C:\Users\Documents\project

:: 使用相对路径
python tree_gen.py ..\src

:: 限制深度为 2 层
python tree_gen.py -d 2 .

:: 仅显示文件树，输出到 files.md
python tree_gen.py -f -o files.md .

:: 仅显示目录树
python tree_gen.py -D .

:: 使用自定义忽略配置文件
python tree_gen.py -i my_ignore.txt .

:: 组合使用：限制深度 + 仅文件 + 自定义输出
python tree_gen.py -d 3 -f -o output.md C:\Projects

配置说明

忽略配置加载优先级

脚本按以下优先级加载忽略配置：

1. 命令行指定：通过 -i 参数指定的配置文件
2. .treeignore：目标目录下的 .treeignore 文件
3. .gitignore：目标目录下的 .gitignore 文件（作为备选）
4. 内置默认列表：以上均不存在时使用

内置默认忽略列表

以下目录和文件默认被忽略，无需额外配置：

目录: .git, .svn, .hg, node_modules, bower_components,
      __pycache__, .pytest_cache, .idea, .vscode,
      dist, build, target, venv, .venv, env

文件: .DS_Store, Thumbs.db, *.pyc

.treeignore 文件格式

在目标目录下创建 .treeignore 文件，每行一个规则：

# 注释行（以 # 开头）
# 精确匹配目录或文件名
build/
dist/
*.log
.env

# 通配符模式（支持 * ? [ 等 glob 语法）
*.tmp
test_*.py

规则说明：

• 以 # 开头的行为注释，会被忽略
• 空行会被忽略
• 以 / 结尾的条目会被当作目录处理（尾部斜杠会被去除后匹配）
• 包含 *、?、[ 的条目按通配符（glob）模式匹配
• 其他条目按精确名称匹配

使用示例

示例 1：基本目录树

python tree_gen.py C:\Projects\my-app

输出：

my-app/
├── src/
│   ├── main.py
│   ├── utils/
│   │   ├── helper.py
│   │   └── config.py
│   └── models/
│       └── user.py
├── tests/
│   ├── test_main.py
│   └── test_utils.py
├── README.md
└── requirements.txt

==================================================
  目录数: 4
  文件数: 7
  总大小: 12.3 KB
==================================================

示例 2：限制深度

python tree_gen.py -d 1 C:\Projects\my-app

输出：

my-app/
├── src/
├── tests/
├── README.md
└── requirements.txt

示例 3：仅文件树

python tree_gen.py -f .

输出：

my-app/
├── src/main.py
├── src/utils/helper.py
├── src/utils/config.py
├── src/models/user.py
├── tests/test_main.py
├── tests/test_utils.py
├── README.md
└── requirements.txt

示例 4：仅目录树

python tree_gen.py -D .

输出：

my-app/
├── src/
│   ├── utils/
│   └── models/
└── tests/

示例 5：自定义输出文件

python tree_gen.py -o project_tree.md C:\Projects\my-app

生成 project_tree.md，包含：

• 目录结构（代码块格式）
• 文件列表（Markdown 表格，含路径和大小）
• 统计信息

注意事项

1. 编码问题：脚本自动配置终端 UTF-8 编码。如果终端显示乱码，请确保 Windows 终端支持 UTF-8（Windows 10 1903+ 默认支持）。
2. 权限限制：遇到无权限访问的目录时，脚本会输出警告并跳过，不会中断执行。
3. 符号链接：脚本自动检测并跳过符号链接循环，避免无限递归。
4. 大目录性能：扫描包含大量文件的目录时可能需要较长时间，建议使用 -d 参数限制深度。
5. Markdown 输出：默认使用 UTF-8 with BOM 编码保存，确保 Windows 上的 Markdown 编辑器正确识别。
6. 忽略配置：内置忽略列表始终生效，配置文件中的规则是追加而非替换。
7. 路径格式：支持 Windows 路径格式（C:\path\to\dir 或 C:/path/to/dir）和相对路径（.\、..\）。
8. 深度参数：-d 1 表示只显示根目录的直接子项，-d 2 显示两层，以此类推。