# 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-04-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: zip, file-synchronize

## README

# zip_sync

A file synchronization system that creates and maintains a special zipsync file format to store compressed folder contents with efficient incremental updates.

## Project Goals

- Create a special zipsync file format for storing compressed folder contents
- Enable easy loading of zipsync files into memory for comparison with folder information
- Implement indexing capabilities for the zipsync file format
- Preserve complete folder information in the zipsync file
- Store files in compressed form within the zipsync file
- Support incremental updates to the zipsync file when folder contents are modified locally

## File Format

The zipsync file format is a binary format designed for efficient storage and incremental updates. It consists of four main sections:

1. **Header** (36 bytes): Contains magic number, version information, and offsets to other sections
2. **Index**: Stores file paths, compression information, and data positions for quick lookup
3. **Compressed Data**: Stores actual file content in compressed form
4. **Metadata**: Stores global information and synchronization-related data

For detailed specifications, see [ZIPSYNC_FILE_FORMAT_SPEC.md](ZIPSYNC_FILE_FORMAT_SPEC.md).

## Project Structure

```
zipsynchronize/
├── src/                  # Source code
│   ├── compression.py    # Compression/decompression functionality
│   └── zipsync.py        # Main zipsync implementation
├── README.md             # This README file
└── ZIPSYNC_FILE_FORMAT_SPEC.md  # File format specification
```

## Main Python Files

### src/compression.py

Provides compression and decompression functionality using the DEFLATE algorithm:

- `compress_data(data)`: Compresses binary data
- `decompress_data(data)`: Decompresses binary data
- `compress_file(file_path)`: Compresses a file
- `decompress_file(file_path)`: Decompresses a file

### src/zipsync.py

Main implementation of the zipsync system with the following classes:

- `ZipsyncCreator`: Creates zipsync files from system folders
- `ZipsyncLoader`: Loads zipsync files into memory for access
- `ZipsyncComparer`: Compares system folders with zipsync files
- `ZipsyncUpdater`: Updates existing zipsync files incrementally
- `ZipsyncSync`: Synchronizes between system folders and zipsync files

## Usage

### Create a zipsync file

```
python src/zipsync.py <source_directory> <output_file>
```

### Compare a folder with a zipsync file

```
python src/zipsync.py compare <zipsync_file> <directory>
```

### Update a zipsync file

```
python src/zipsync.py update <zipsync_file> <directory>
```

### Synchronize between a folder and a zipsync file

```
python src/zipsync.py sync <zipsync_file> <directory> --direction <sync_direction> --conflict <resolution_strategy>
```

#### Sync directions:
- `to_zipsync`: Sync from folder to zipsync file
- `from_zipsync`: Sync from zipsync file to folder
- `bidirectional`: Sync in both directions

#### Conflict resolution strategies:
- `newer`: Use the newer file
- `local`: Use the local file (folder)
- `remote`: Use the remote file (zipsync)
- `prompt`: Prompt user for selection

## Examples

### Create a zipsync file from a folder

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

### Update an existing zipsync file

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

### Sync from zipsync file to folder

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

## Performance

- Incremental updates are significantly faster than full file rewriting
- Compression ratio is comparable to standard ZIP format
- The system can handle folders with thousands of files
- Memory usage is optimized for large folders

## Dependencies

- Python 3.6+
- Standard library modules: `zlib`, `os`, `hashlib`, `struct`, `argparse`, `tempfile`

## Executable File

For users without Python environment, a pre-packaged executable file is available at `dist/dist\zipsync.exe`.

### Command-line Usage with dist\zipsync.exe

```
dist\zipsync.exe <source_directory> <output_file>
```

#### Compare a folder with a zipsync file

```
dist\zipsync.exe compare <zipsync_file> <directory>
```

#### Update a zipsync file

```
dist\zipsync.exe update <zipsync_file> <directory>
```

#### Synchronize between a folder and a zipsync file

```
dist\zipsync.exe sync <zipsync_file> <directory> --direction <sync_direction> --conflict <resolution_strategy>
```

## License

This project is open-source under the MIT License.