234 lines
6.3 KiB
Markdown
234 lines
6.3 KiB
Markdown
# 目录树生成脚本 (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+ 即可直接使用：
|
||
|
||
```cmd
|
||
python --version
|
||
```
|
||
|
||
如果显示 Python 3.8 或更高版本，即可开始使用。
|
||
|
||
## 使用方法
|
||
|
||
### 基本语法
|
||
|
||
```cmd
|
||
python tree_gen.py [路径] [选项]
|
||
```
|
||
|
||
### 命令行选项
|
||
|
||
| 选项 | 简写 | 说明 | 默认值 |
|
||
|------|------|------|--------|
|
||
| `path` | — | 目标目录路径 | 当前目录 (`.`) |
|
||
| `--output` | `-o` | Markdown 输出文件路径 | `tree_output.md` |
|
||
| `--depth` | `-d` | 最大递归深度（整数） | 无限制 |
|
||
| `--files-only` | `-f` | 仅显示文件树 | 关闭 |
|
||
| `--dirs-only` | `-D` | 仅显示目录树 | 关闭 |
|
||
| `--ignore` | `-i` | 忽略配置文件路径 | 自动检测 |
|
||
| `--help` | `-h` | 显示帮助信息 | — |
|
||
|
||
### 常用示例
|
||
|
||
```cmd
|
||
:: 生成当前目录的目录树
|
||
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` 文件，每行一个规则：
|
||
|
||
```text
|
||
# 注释行（以 # 开头）
|
||
# 精确匹配目录或文件名
|
||
build/
|
||
dist/
|
||
*.log
|
||
.env
|
||
|
||
# 通配符模式（支持 * ? [ 等 glob 语法）
|
||
*.tmp
|
||
test_*.py
|
||
```
|
||
|
||
规则说明：
|
||
- 以 `#` 开头的行为注释，会被忽略
|
||
- 空行会被忽略
|
||
- 以 `/` 结尾的条目会被当作目录处理（尾部斜杠会被去除后匹配）
|
||
- 包含 `*`、`?`、`[` 的条目按通配符（glob）模式匹配
|
||
- 其他条目按精确名称匹配
|
||
|
||
## 使用示例
|
||
|
||
### 示例 1：基本目录树
|
||
|
||
```cmd
|
||
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：限制深度
|
||
|
||
```cmd
|
||
python tree_gen.py -d 1 C:\Projects\my-app
|
||
```
|
||
|
||
输出：
|
||
|
||
```
|
||
my-app/
|
||
├── src/
|
||
├── tests/
|
||
├── README.md
|
||
└── requirements.txt
|
||
```
|
||
|
||
### 示例 3：仅文件树
|
||
|
||
```cmd
|
||
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：仅目录树
|
||
|
||
```cmd
|
||
python tree_gen.py -D .
|
||
```
|
||
|
||
输出：
|
||
|
||
```
|
||
my-app/
|
||
├── src/
|
||
│ ├── utils/
|
||
│ └── models/
|
||
└── tests/
|
||
```
|
||
|
||
### 示例 5：自定义输出文件
|
||
|
||
```cmd
|
||
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` 显示两层，以此类推。
|