# zipsynchronize

**Repository Path**: benechen/zipsynchronize

## Basic Information

- **Project Name**: zipsynchronize
- **Description**: 一个文件同步系统，创建并维护一种特殊的 zipsync 文件格式，用于存储压缩的文件夹内容，并支持高效的增量更新。A file synchronization system with efficient incremental updates.
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: zip, file-synchronize

## README

# zip\_sync

一个文件同步系统，创建并维护一种特殊的 zipsync 文件格式，用于存储压缩的文件夹内容，并支持高效的增量更新。

## 项目目标

- 创建一种特殊的 zipsync 文件格式，用于存储压缩的文件夹内容
- 支持将 zipsync 文件轻松加载到内存中，以便与系统文件夹信息进行比较
- 为 zipsync 文件格式实现索引功能，提高访问效率
- 在 zipsync 文件中保留完整的文件夹信息
- 在 zipsync 文件中以压缩方式存储文件
- 当文件夹内容局部修改时，支持对 zipsync 文件进行局部更新，而不必重写整个文件

## 文件格式

zipsync 文件格式是一种二进制格式，专为高效存储和增量更新而设计。它由四个主要部分组成：

1. **头部**（36字节）：包含魔术数字、版本信息和其他部分的偏移量
2. **索引**：存储文件路径、压缩信息和数据位置，用于快速查找
3. **压缩数据**：以压缩形式存储实际文件内容
4. **元数据**：存储全局信息和同步相关数据

详细规格请参阅 [ZIPSYNC\_FILE\_FORMAT\_SPEC.md](ZIPSYNC_FILE_FORMAT_SPEC.md)。

## 项目结构

```
zipsynchronize/
├── src/                  # 源代码
│   ├── compression.py    # 压缩/解压缩功能
│   └── zipsync.py        # 主要的 zipsync 实现
├── README.md             # 英文 README 文件
├── README_CN.md          # 中文 README 文件
└── ZIPSYNC_FILE_FORMAT_SPEC.md  # 文件格式规范
```

## 主要 Python 文件

### src/compression.py

提供使用 DEFLATE 算法的压缩和解压缩功能：

- `compress_data(data)`: 压缩二进制数据
- `decompress_data(data)`: 解压缩二进制数据
- `compress_file(file_path)`: 压缩文件
- `decompress_file(file_path)`: 解压缩文件

### src/zipsync.py

zipsync 系统的主要实现，包含以下类：

- `ZipsyncCreator`: 从系统文件夹创建 zipsync 文件
- `ZipsyncLoader`: 将 zipsync 文件加载到内存中以便访问
- `ZipsyncComparer`: 比较系统文件夹和 zipsync 文件
- `ZipsyncUpdater`: 增量更新现有的 zipsync 文件
- `ZipsyncSync`: 在系统文件夹和 zipsync 文件之间进行同步

## 使用方法

### 创建 zipsync 文件

```
python src/zipsync.py <源目录> <输出文件>
```

### 比较文件夹和 zipsync 文件

```
python src/zipsync.py compare <zipsync文件> <目录>
```

### 更新 zipsync 文件

```
python src/zipsync.py update <zipsync文件> <目录>
```

### 在文件夹和 zipsync 文件之间同步

```
python src/zipsync.py sync <zipsync文件> <目录> --direction <同步方向> --conflict <冲突解决策略>
```

#### 同步方向：

- `to_zipsync`: 从文件夹同步到 zipsync 文件
- `from_zipsync`: 从 zipsync 文件同步到文件夹
- `bidirectional`: 双向同步

#### 冲突解决策略：

- `newer`: 使用较新的文件
- `local`: 使用本地文件（文件夹）
- `remote`: 使用远程文件（zipsync）
- `prompt`: 提示用户选择

## 示例

### 从文件夹创建 zipsync 文件

```
python src/zipsync.py test_dir output.zsync
```

### 更新现有的 zipsync 文件

```
python src/zipsync.py update output.zsync test_dir
```

### 从 zipsync 文件同步到文件夹

```
python src/zipsync.py sync output.zsync test_dir/sync_test_dir --direction from_zipsync
```

## 性能

- 增量更新比完全重写文件快得多
- 压缩率与标准 ZIP 格式相当
- 系统可以处理包含数千个文件的文件夹
- 内存使用针对大型文件夹进行了优化

## 依赖

- Python 3.6+
- 标准库模块：`zlib`、`os`、`hashlib`、`struct`、`argparse`、`tempfile`

## 可执行文件

对于没有 Python 环境的用户，已打包好的可执行文件位于 `dist/main.exe`。

  <br />

## 许可证

本项目采用 MIT 许可证开源。