release: v1.0.0

2026-05-16 17:34:32 +08:00
commit 2f521deff8
15 changed files with 4718 additions and 0 deletions
--- a/Releases/v1.0.0/docs/QUICKSTART.md
+++ b/Releases/v1.0.0/docs/QUICKSTART.md
@@ -0,0 +1,99 @@
+# tree.sh 快速入门
+
+> 版本 1.0.0 | 纯 Bash 目录树生成工具
+
+## 1 分钟上手
+
+### 安装
+
+```bash
+# 下载脚本
+chmod +x tree.sh
+
+# 可选：安装到系统 PATH
+sudo cp tree.sh /usr/local/bin/tree.sh
+```
+
+### 基本使用
+
+```bash
+# 生成当前目录的树
+./tree.sh
+
+# 生成指定目录的树
+./tree.sh -p /path/to/project
+
+# 生成树 + 文件列表
+./tree.sh -p . -f
+
+# 限制深度为 2 层
+./tree.sh -p . -d 2
+
+# 保存到指定文件
+./tree.sh -p . -o my-tree.md
+```
+
+### 输出示例
+
+```
+my-project/
+├── src/
+│   ├── main.sh
+│   └── utils/
+│       └── helpers.sh
+├── tests/
+│   └── test_main.sh
+├── README.md
+└── tree_output.md
+
+Statistics:
+  Directories: 4
+  Files:       5
+  Total size:  8.42 KB
+```
+
+## 常用场景
+
+| 场景 | 命令 |
+|------|------|
+| 查看项目结构 | `./tree.sh -p ./project` |
+| 生成文档用树 | `./tree.sh -p . -f -o README-tree.md` |
+| 只看前 2 层 | `./tree.sh -p . -d 2` |
+| 排除日志文件 | 创建 `.treeignore`，写入 `*.log` |
+
+## 自定义忽略规则
+
+在目标目录创建 `.treeignore`：
+
+```bash
+# .treeignore
+*.log
+tmp
+coverage
+*.bak
+```
+
+## 命令行选项速查
+
+| 选项 | 说明 |
+|------|------|
+| `-p <路径>` | 目标目录 |
+| `-o <文件>` | 输出 Markdown 文件 |
+| `-d <N>` | 最大深度 |
+| `-f` | 包含文件列表 |
+| `-s` | 不显示统计 |
+| `-h` | 帮助 |
+| `-v` | 版本 |
+
+## 退出码
+
+| 码 | 含义 |
+|----|------|
+| 0 | 成功 |
+| 1 | 参数错误 |
+| 2 | 路径无效 |
+| 3 | 写入失败 |
+
+---
+
+详细文档请查看 [README.md](README.md)
--- a/Releases/v1.0.0/docs/README.md
+++ b/Releases/v1.0.0/docs/README.md
@@ -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` 显示两层，以此类推。