# 🚀 ls-plus 完整使用指南

## 📦 快速开始

### 第一步：编译项目
```bash
# 进入项目目录
cd ls-plus

# 构建项目
cargo build --release
```

### 第二步：基础使用
```bash
# 查看帮助（了解所有功能）
./target/release/ls-plus --help

# 列出当前目录
./target/release/ls-plus

# 列出指定目录
./target/release/ls-plus /Users/你的用户名/Documents
```

## 🎯 核心功能

### 基础目录列表
```bash
# 显示隐藏文件
./target/release/ls-plus -a

# 详细信息显示（长格式）
./target/release/ls-plus --format long

# 按时间排序
./target/release/ls-plus -t

# 只显示目录
./target/release/ls-plus --file-type dir

# 树形视图
./target/release/ls-plus tree
```

### 🏷️ 目录描述功能（新功能！）
为任何目录添加自定义描述，让目录结构更清晰：

```bash
# 为目录添加描述
./target/release/ls-plus describe set "这是项目源代码目录" src
./target/release/ls-plus describe set "测试用例和集成测试" tests

# 查看目录描述
./target/release/ls-plus describe get src

# 列出所有描述
./target/release/ls-plus describe list

# 搜索描述
./target/release/ls-plus describe search "测试"

# 删除描述
./target/release/ls-plus describe remove src

# 清理无效描述（删除不存在目录的描述）
./target/release/ls-plus describe cleanup
```

**在目录列表中查看描述**：
```bash
# 默认格式：描述显示在目录名后
./target/release/ls-plus
# 输出：src (这是项目源代码目录)

# 长格式：描述单独一行显示
./target/release/ls-plus --format long
# 输出：
# drwxr-xr-x      320 Aug 05 20:28 src
#           📝 这是项目源代码目录
```

## ⚙️ 配置管理

### 基础配置
```bash
# 查看默认配置
./target/release/ls-plus config show

# 设置默认显示图标
./target/release/ls-plus config set display.show_icons true

# 设置目录优先显示
./target/release/ls-plus config set display.directories_first true

# 重置配置
./target/release/ls-plus config reset

# 编辑配置文件
./target/release/ls-plus config edit
```

## 💡 实用技巧

### 创建别名（强烈推荐）
在你的 shell 配置文件中添加：
```bash
# 在 ~/.bashrc 或 ~/.zshrc 中添加
alias lsp='/path/to/ls-plus/target/release/ls-plus'

# 然后你就可以直接使用
lsp -a                                    # 显示隐藏文件
lsp --format long                         # 长格式显示
lsp tree                                  # 树形视图
lsp config show                           # 查看配置
lsp describe set "我的项目" .             # 添加描述
```

### 常用组合命令
```bash
# 显示所有文件的详细信息，按时间排序
./target/release/ls-plus -at --format long

# 显示目录树，限制深度，包含隐藏文件
./target/release/ls-plus tree -d 3 -a

# 搜索图片文件
./target/release/ls-plus --file-type image

# 为项目目录快速添加描述
./target/release/ls-plus describe set "前端源码目录" frontend
./target/release/ls-plus describe set "后端API目录" backend
./target/release/ls-plus describe set "数据库脚本" database
```

### 项目组织最佳实践
```bash
# 为常见目录添加标准描述
lsp describe set "源代码目录" src
lsp describe set "测试用例" tests
lsp describe set "文档目录" docs
lsp describe set "构建输出" target
lsp describe set "静态资源" assets
lsp describe set "配置文件" config
```

## 📁 数据存储位置

### 配置文件
- **macOS/Linux**: `~/.config/ls-plus/config.toml`
- **Windows**: `%APPDATA%/ls-plus/config.toml`

### 目录描述数据库
- **macOS/Linux**: `~/.config/ls-plus/descriptions.json`
- **Windows**: `%APPDATA%/ls-plus/descriptions.json`

## 🔧 开发和测试

### 开发环境设置
```bash
# 运行测试
cargo test

# 代码格式化
cargo fmt

# 代码检查
cargo clippy

# 运行调试版本
cargo run -- --help
cargo run -- describe set "测试描述" .
```

### 测试覆盖
```bash
# 运行所有测试（包括描述功能测试）
cargo test

# 只运行描述功能测试
cargo test test_describe
```

## 📊 功能状态

### ✅ 已完全实现的功能
- **基础文件列表** - 支持多种排序和过滤选项
- **目录描述系统** - 完整的CRUD操作和搜索功能
- **配置管理** - 持久化配置系统
- **多种显示格式** - 默认、长格式、树形、网格、JSON
- **命令行界面** - 完整的CLI参数解析
- **错误处理** - 用户友好的错误信息
- **测试框架** - 12个集成测试用例

### 🚧 部分实现的功能
- **Git 集成** - 接口已定义，待完善实现
- **图标显示** - 基础框架已建立
- **颜色主题** - 基础颜色支持，可扩展

### 🎯 使用场景
1. **项目管理** - 为项目目录添加说明，提高团队协作效率
2. **学习记录** - 为学习资料目录添加笔记
3. **文件整理** - 为个人文件夹添加备注
4. **代码文档** - 自动化项目结构文档

### 🔮 未来计划
- 插件系统支持
- 更多文件类型识别
- 性能优化
- 国际化支持
- 云端同步描述数据