# PyDirectoryComparison

**Repository Path**: J_Sky/PyDirectoryComparison

## Basic Information

- **Project Name**: PyDirectoryComparison
- **Description**: PyDirectoryComparison 是一个功能强大的目录同步工具，旨在帮助用户轻松管理和同步两个目录之间的文件。无论是备份照片、同步工作文档，还是保持多个设备间的文件一致性，本工具都能提供可靠的解决方案。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://www.suiyan.cc
- **GVP Project**: No

## Statistics

- **Stars**: 9
- **Forks**: 3
- **Created**: 2018-01-09
- **Last Updated**: 2026-01-25

## Categories & Tags

**Categories**: filemanager

**Tags**: None

## README

# PyDirectoryComparison v2.0

一个基于Python、Tkinter构建的可视化目录文件同步工具，支持双向同步、文件比较、预览等功能。

## 项目简介

PyDirectoryComparison 是一个功能强大的目录同步工具，旨在帮助用户轻松管理和同步两个目录之间的文件。无论是备份照片、同步工作文档，还是保持多个设备间的文件一致性，本工具都能提供可靠的解决方案。

### 适用场景
- 📸 **照片备份**：将相机或手机的照片备份到电脑
- 💼 **文档同步**：在工作电脑和移动设备间同步文档
- 🔄 **版本管理**：比较不同版本的文件差异
- 📦 **项目备份**：备份项目文件到多个位置
- 🎯 **数据迁移**：在不同存储设备间迁移数据

### 核心优势
- 🔒 **安全可靠**：预览模式确保操作可控
- ⚡ **高效快速**：优化的比较和同步算法
- 🎨 **界面友好**：直观的图形化操作界面
- 🧪 **测试完善**：50+测试用例保证质量
- 📝 **日志完整**：详细记录所有操作历史

### 界面预览

![界面截图](gui.png)

## 功能特性

### ✨ 核心功能
- **目录比较**：递归比较两个目录的结构差异
- **文件同步**：支持单向和双向同步
- **进度显示**：实时显示同步进度
- **预览模式**：在实际执行前预览操作

### 🎯 新增功能
- **双向同步**：支持左→右、右→左、双向三种同步模式
- **智能比较**：按文件内容和修改时间比较文件
- **冲突检测**：识别两边都修改过的文件
- **结果筛选**：按状态筛选显示差异文件
- **删除多余**：可选择删除目标目录中多余的文件
- **详细统计**：显示文件数量、大小等统计信息
- **操作日志**：记录所有操作历史

### 🛠️ 技术改进
- **架构分离**：GUI与业务逻辑完全分离
- **错误处理**：完善的异常处理机制
- **路径处理**：使用pathlib替代字符串操作
- **类型提示**：完整的类型注解
- **可配置**：支持自定义忽略规则

## 安装

### 环境要求
- Python 3.7+

### 依赖
本项目仅使用Python标准库，无需安装额外依赖：
- tkinter（GUI）
- pathlib（路径处理）
- filecmp（文件比较）
- shutil（文件复制）
- os（系统操作）

## 使用方法

### 启动程序
```bash
python main.py
```

### 基本操作
1. 选择源目录（左边）和目标目录（右边）
2. 点击"开始比较"按钮
3. 查看比较结果（概览、文件差异、目录差异）
4. 选择同步方向和选项
5. 点击"开始同步"执行同步

### 同步选项
- **同步方向**：
  - 左 → 右：将左边独有的和修改过的文件同步到右边
  - 右 → 左：将右边独有的和修改过的文件同步到左边
  - 双向：同步两边独有的文件
- **删除多余文件**：删除目标目录中多余的文件
- **预览模式**：只显示将要执行的操作，不实际执行

## 项目结构

```
PyDirectoryComparison/
├── main.py                 # 程序入口
├── config.py              # 配置文件
├── run_tests.py           # 测试运行脚本
├── core/                  # 核心业务逻辑
│   ├── __init__.py
│   ├── models.py          # 数据模型
│   ├── comparator.py      # 目录比较器
│   └── synchronizer.py    # 目录同步器
├── gui/                   # GUI界面
│   ├── __init__.py
│   └── main_window.py     # 主窗口
└── tests/                 # 测试模块
    ├── __init__.py
    ├── test_utils.py      # 测试工具
    ├── test_models.py     # 数据模型测试
    ├── test_comparator.py # 比较器测试
    ├── test_synchronizer.py # 同步器测试
    └── test_integration.py # 集成测试
```

## 代码架构

### 核心模块（core/）
- **models.py**：定义数据模型（FileInfo、DirectoryInfo、ComparisonResult等）
- **comparator.py**：负责目录比较逻辑
- **synchronizer.py**：负责文件同步逻辑

### GUI模块（gui/）
- **main_window.py**：主窗口实现，包含所有UI组件和事件处理

### 设计原则
- GUI与业务逻辑完全分离
- 使用数据类（dataclass）定义数据模型
- 回调机制实现进度更新
- 类型提示提高代码可读性

## 配置

在`config.py`中可以修改以下配置：
- 默认忽略的文件和目录模式
- 窗口大小
- 日志配置
- 性能参数

## 测试

项目包含完整的测试套件，确保功能的准确性和稳定性。

### 运行测试

```bash
# 运行所有测试
python run_tests.py

# 运行特定模块测试
python run_tests.py --module test_models
python run_tests.py --module test_comparator
python run_tests.py --module test_synchronizer
python run_tests.py --module test_integration

# 运行特定测试类
python run_tests.py --module test_comparator --class TestDirectoryComparator

# 运行特定测试方法
python run_tests.py --module test_synchronizer --class TestDirectorySynchronizer --method test_sync_left_to_right

# 详细输出
python run_tests.py -v

# 静默输出
python run_tests.py -q
```

### 测试覆盖

- **单元测试**：数据模型、比较器、同步器
- **集成测试**：完整同步流程、增量同步、性能测试
- **边界测试**：空目录、深层目录、特殊字符
- **错误处理**：权限问题、不存在路径等

详细测试文档请参考 [tests/README.md](tests/README.md)

## 注意事项

1. **文件比较**：程序会比较文件内容，对于大文件可能需要较长时间
2. **删除操作**：开启"删除多余文件"选项时请谨慎操作
3. **预览模式**：建议首次使用时先使用预览模式查看将要执行的操作
4. **备份**：重要数据请先备份再同步

## 更新日志

### v2.0.0 (2026-01-20)
- 重构代码架构，分离GUI和业务逻辑
- 添加双向同步功能
- 添加预览模式
- 添加进度显示
- 添加冲突检测
- 添加结果筛选功能
- 添加详细统计信息
- 改进错误处理
- 使用pathlib替代字符串操作
- 添加类型提示

### v1.0.0 (2018-01-10)
- 初始版本
- 基本的目录比较和单向同步功能

## 作者

J.sky <bosichong@qq.com>

## 许可证

本项目采用 MIT 许可证。

## 相关链接

- 博客：http://www.suiyan.cc