release: v1.0.0
This commit is contained in:
233
README.md
Normal file
233
README.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# 目录树生成脚本 (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` 显示两层，以此类推。
|
||||
Reference in New Issue
Block a user