# tree.sh — 目录树生成脚本

一个用纯 Bash 编写的轻量级目录树生成工具，支持忽略配置、递归遍历、文件列表、Markdown 导出和统计信息。无需安装任何依赖，开箱即用。

**版本：** 1.0.0

---

## 功能特性

| 功能 | 说明 |
|------|------|
| **目录树生成** | 使用 `├──` / `└──` 字符生成标准树形结构，目录在前、文件在后，按字母排序 |
| **文件列表** | 可选生成完整文件列表（`-f`），显示所有文件的绝对路径 |
| **忽略配置** | 内置 30+ 种常见忽略模式（`.git`、`node_modules`、`__pycache__` 等），支持 `.treeignore` 自定义 |
| **深度限制** | 通过 `-d` 参数限制递归深度，避免过深遍历 |
| **Markdown 导出** | 默认保存为 `tree_output.md`，也可自定义输出路径 |
| **统计信息** | 自动统计目录数、文件数和总大小（自动转换为 B / KB / MB / GB） |
| **循环检测** | 基于 inode 检测符号链接循环，防止无限递归 |
| **权限处理** | 对无权限目录显示 `[Permission denied]`，不会中断执行 |

---

## 环境要求

- **操作系统：** Linux 或 macOS
- **Shell：** Bash 4.0 或更高版本
- **依赖：** 无（仅使用 Bash 内置命令和 `stat`、`awk`、`basename`、`dirname`、`mkdir` 等标准工具）

检查 Bash 版本：

```bash
bash --version
```

---

## 安装方法

**零安装。** 直接下载或克隆脚本后即可运行：

```bash
chmod +x tree.sh
./tree.sh -p /path/to/target
```

也可以将脚本放到 PATH 中的某个目录，方便全局调用：

```bash
sudo cp tree.sh /usr/local/bin/tree.sh
tree.sh -p /path/to/target
```

---

## 使用方法

### 基本用法

```bash
# 生成当前目录的树形结构
./tree.sh

# 生成指定目录的树形结构
./tree.sh -p /home/user/project

# 使用相对路径
./tree.sh -p ../some-project
```

### 命令行选项

| 选项 | 简写 | 说明 | 默认值 |
|------|------|------|--------|
| `--path <路径>` | `-p` | 指定目标目录 | 当前目录 (`.`) |
| `--output <文件>` | `-o` | 指定 Markdown 输出文件 | `tree_output.md` |
| `--depth <N>` | `-d` | 限制递归深度（正整数） | 无限制 |
| `--files` | `-f` | 同时生成文件列表 | 关闭 |
| `--no-stats` | `-s` | 不显示统计信息 | 显示 |
| `--help` | `-h` | 显示帮助信息 | — |
| `--version` | `-v` | 显示版本信息 | — |

### 常用示例

```bash
# 生成当前目录的完整树（含文件列表和统计）
./tree.sh -f

# 只查看前 2 层目录结构
./tree.sh -d 2

# 生成项目树并保存到自定义文件
./tree.sh -p /var/www/myapp -o project-tree.md

# 深度 3 + 文件列表 + 保存
./tree.sh -p ./src -d 3 -f -o src-tree.md

# 仅终端输出，不保存 Markdown 文件（重定向）
./tree.sh -p . -s > /dev/null

# 查看帮助
./tree.sh -h

# 查看版本
./tree.sh -v
```

---

## 配置说明

### 内置忽略列表

脚本默认忽略以下目录和文件类型：

**版本控制：**
- `.git`、`.svn`、`.hg`

**包管理 & 缓存：**
- `node_modules`、`__pycache__`、`.cache`、`.tox`、`.eggs`

**构建产物：**
- `dist`、`build`、`.next`、`.nuxt`、`.output`、`.vercel`、`.terraform`、`.vagrant`

**IDE & 编辑器：**
- `.idea`、`.vscode`

**编译产物：**
- `*.pyc`、`*.pyo`、`*.egg-info`、`*.swp`、`*.swo`、`*.swn`、`*.class`、`*.o`、`*.so`、`*.dylib`

**系统文件：**
- `.DS_Store`

### 自定义忽略配置

在目标目录下创建 `.treeignore` 文件，每行一个忽略模式：

```bash
# .treeignore 示例
# 注释以 # 开头

# 忽略特定目录
logs
tmp
*.log

# 忽略特定文件类型
*.bak
*.tmp
*.orig

# 忽略特定名称
.env.local
coverage
```

**规则：**
- 空行和以 `#` 开头的行会被忽略（作为注释）
- 支持精确匹配（如 `logs`）和 glob 通配符（如 `*.log`）
- 忽略模式会追加到内置列表之后，不会覆盖内置规则

---

## 使用示例

### 示例 1：基本目录树

```bash
$ ./tree.sh -p ./my-project
```

**终端输出：**
```
my-project/
├── src/
│   ├── main.sh
│   ├── utils/
│   │   ├── helpers.sh
│   │   └── validators.sh
│   └── config.sh
├── tests/
│   ├── test_main.sh
│   └── test_utils.sh
├── README.md
└── tree_output.md

Files:
  /home/user/my-project/src/main.sh
  /home/user/my-project/src/utils/helpers.sh
  /home/user/my-project/src/utils/validators.sh
  /home/user/my-project/src/config.sh
  /home/user/my-project/tests/test_main.sh
  /home/user/my-project/tests/test_utils.sh
  /home/user/my-project/README.md
  /home/user/my-project/tree_output.md

Statistics:
  Directories: 4
  Files:       8
  Total size:  12.34 KB
```

### 示例 2：限制深度

```bash
$ ./tree.sh -p ./my-project -d 2
```

**输出：**
```
my-project/
├── src/
│   ├── main.sh
│   ├── utils/
│   └── config.sh
├── tests/
│   ├── test_main.sh
│   └── test_utils.sh
├── README.md
└── tree_output.md
```

### 示例 3：生成 Markdown 文件

```bash
$ ./tree.sh -p ./my-project -f -o my-tree.md
```

**生成的 `my-tree.md` 内容：**
```markdown
# Directory Tree

Path: `./my-project`

```
my-project/
├── src/
│   ├── main.sh
│   ├── utils/
│   │   ├── helpers.sh
│   │   └── validators.sh
│   └── config.sh
├── tests/
│   ├── test_main.sh
│   └── test_utils.sh
├── README.md
└── tree_output.md
```

## Files

  /home/user/my-project/src/main.sh
  ...

## Statistics

- **Directories:** 4
- **Files:** 8
- **Total size:** 12.34 KB
```

### 示例 4：结合 .treeignore 使用

```bash
# 创建 .treeignore
echo -e "*.log\ntmp\ncoverage" > .treeignore

# 运行脚本（自动加载 .treeignore）
./tree.sh -p .
```

---

## 注意事项

1. **路径必须存在且为目录**：如果指定的路径不存在或不是目录，脚本会报错退出（退出码 2）。

2. **深度参数必须为正整数**：`-d` 参数必须传入大于 0 的整数，否则报错退出（退出码 1）。

3. **符号链接循环检测**：脚本基于 inode 检测循环引用。如果检测到循环，会显示 `[cycle detected, skipped]` 并跳过，不会无限递归。

4. **权限问题**：遇到无权限读取的目录时，会显示 `[Permission denied]` 并继续处理其他目录，不会中断整个流程。

5. **输出文件目录自动创建**：如果 `-o` 指定的输出路径中的目录不存在，脚本会自动创建。

6. **Markdown 文件始终生成**：脚本每次运行都会同时输出到终端和保存 Markdown 文件（默认 `tree_output.md`）。终端输出和 Markdown 内容一致。

7. **大小写敏感**：忽略模式匹配区分大小写。

8. **隐藏文件**：以 `.` 开头的隐藏文件/目录会被正常遍历（除非被忽略规则匹配）。

9. **退出码**：
   - `0`：成功
   - `1`：参数错误
   - `2`：路径无效
   - `3`：写入失败

---

## 项目信息

- **项目 ID：** PROJ-20260509011
- **功能覆盖：** F013–F020（8 个功能全部测试通过）