# 目录树生成脚本 (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` 显示两层，以此类推。