DiffPy - 目录差异比对工具

一个用于比较两个目录结构和内容差异的 Python 工具。

功能特性

• 🔍 结构差异检测: 找出只在源目录或目标目录存在的文件/目录
• 📄 内容差异检测: 使用 MD5 哈希比较相同路径文件的内容差异
• 🚫 智能忽略: 自动忽略 .gitignore 中指定的文件和 .git 目录
• 📊 详细报告: 生成人类可读的差异报告文件
• 🎨 美观输出: 使用 Rich 库提供彩色终端输出和进度条

使用方法

uv run main.py <源目录> <目标目录> <输出目录>

参数说明

• 源目录: 要比较的第一个目录路径
• 目标目录: 要比较的第二个目录路径
• 输出目录: 差异报告的输出目录

使用示例

# 比较两个项目目录
uv run main.py ./project1 ./project2 ./diff_output

# 比较备份目录
uv run main.py /backup/2023-01-01 /backup/2023-01-02 ./backup_diff

输出说明

程序会在输出目录中生成以下内容：

1. 差异报告文件

directory_diff_report.txt 文件包含：

• 只在源目录存在的文件/目录: 列出仅在源目录中存在的文件
• 只在目标目录存在的文件/目录: 列出仅在目标目录中存在的文件
• 内容不同的文件: 列出两个目录都存在但内容不同的文件，包含文件哈希值
• 统计信息: 各类差异的数量统计
• 输出目录结构说明: 说明差异文件的组织方式

2. 差异文件目录结构

输出目录/
├── directory_diff_report.txt          # 差异报告文件
├── source_only/                       # 只在源目录存在的文件
│   └── [保持原目录结构]
├── target_only/                       # 只在目标目录存在的文件
│   └── [保持原目录结构]
└── content_different/                 # 内容不同的文件
    ├── source/                        # 源目录版本
    │   └── [保持原目录结构]
    ├── target/                        # 目标目录版本
    │   └── [保持原目录结构]
    └── diff/                          # VSCode diff 格式文件
        └── [保持原目录结构]

3. 文件复制说明

• 所有差异文件都会按照原始目录结构复制到对应的子目录中
• 内容不同的文件会同时复制源版本和目标版本，便于对比
• 使用 shutil.copy2 保持文件的元数据（时间戳、权限等）

4. VSCode diff 格式

• diff/ 目录中的文件采用 Git merge 冲突格式
• 可以在 VSCode 中直接打开查看差异，支持语法高亮和差异显示
• 格式说明：

  <<<<<<< SOURCE (文件路径)
  源文件内容
  =======
  目标文件内容
  >>>>>>> TARGET (文件路径)
  

• VSCode 会自动识别这种格式并提供：
  • 语法高亮显示
  • 差异区域高亮
  • 接受/拒绝更改的选项

忽略规则

• 自动忽略 .git 目录
• 读取并应用源目录和目标目录中的 .gitignore 文件规则
• 支持标准的 gitignore 模式匹配

技术实现

• 使用 pathspec 库处理 .gitignore 规则
• 使用 hashlib 计算文件 MD5 哈希进行内容比较
• 使用 pathlib.Path 进行跨平台路径操作
• 使用 rich 库提供美观的终端输出