# rsync

**Repository Path**: extrame/rsync

## Basic Information

- **Project Name**: rsync
- **Description**: 鉴于在windows下面部署和使用rsync遇到了太多的问题，使用ssh不对啊，ssh-agent无法正确的使用windows缓存的key啊之类的，我打算用golang翻译一个
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-04-15
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# rsync — rsync 的 Go 实现

> **⚠️ 警告：本项目是 rsync 的 Go 语言重写版本，尚未实现完整功能。请勿在生产环境中使用，使用需谨慎！**

## 项目简介

本项目是一个用纯 Go 语言重新实现的 rsync 工具，旨在提供跨平台的文件同步能力。它兼容 rsync 协议，可以与原生 rsync 服务端进行通信。

**Go Module**: `gitee.com/extrame/rsync`

## 快速安装

### 使用 go install（推荐）

```bash
# 直接安装到 $GOPATH/bin 或 $HOME/go/bin
go install gitee.com/extrame/rsync/cmd/rsync@latest
```

安装完成后，即可在命令行使用 `rsync` 命令。

### 从源码编译

```bash
git clone https://gitee.com/extrame/rsync.git
cd rsync
make
```

## 当前状态

本项目处于**开发阶段**，核心协议栈已基本可用，但功能不完整。目前主要用于学习和研究 rsync 协议的实现。

## 已实现功能

### 核心协议
- ✅ rsync 协议版本 31/32 握手
- ✅ Multiplexed 数据帧编解码
- ✅ 文件列表（file list）生成与解析
- ✅ 增量校验和匹配（delta transfer）
- ✅ Token 流编解码（literal tokens 和 match tokens）
- ✅ MD5 文件校验和

### 压缩支持
- ✅ `-z` 压缩传输（DEFLATED_DATA 块格式）
- ✅ 压缩 token 流的发送与接收
- ✅ 每个文件独立压缩状态重置

### 传输模式
- ✅ 本地文件同步
- ✅ SSH 远程同步
- ✅ Go sender ↔ C receiver（cgo 桥接）
- ✅ Go sender ↔ rsync 3.x server（SSH 模式）

### 命令行选项
- ✅ `-r` 递归同步
- ✅ `-a` archive 模式（-rlptgoD）
- ✅ `-z` 压缩传输
- ✅ `-v` 详细输出
- ✅ `-u` 更新模式（跳过较旧文件）
- ✅ `-n` 干运行模式
- ⚠️ `--delete` 删除多余文件（仅客户端模式生效，见下方说明）
- ✅ `--checksum` 基于校验和跳过

## 未实现功能

### 协议层
- ❌ Delta Transfer 算法（LZ4 压缩的增量传输）
- ❌ 批处理模式（batch mode）
- ❌ 硬链接保留
- ❌ ACL 支持
- ❌ xattr 扩展属性支持
- ❌ 增量递归（inc_recurse）

### 压缩算法
- ❌ zstd 压缩支持
- ❌ lz4 压缩支持
- ❌ 压缩算法协商（compress list）

### 校验和算法
- ❌ xxh128/xxh3/xxh64 校验和
- ❌ SHA1 校验和
- ❌ 自定义校验和选择（--checksum-choice）

### 网络功能
- ❌ rsync daemon 模式（rsyncd）
- ❌ IPv6 支持
- ❌ 带宽限制（--bwlimit）
- ❌ 断点续传（--partial, --append）

### 高级选项
- ❌ 包含/排除规则的完整语法（filter rules）
- ❌ 备份选项（--backup, --backup-dir）
- ❌ inplace 更新
- ❌ 符号链接处理选项（--copy-links, --links 已部分实现）
- ❌ 设备文件和特殊文件支持
- ❌ 统计信息（--stats）
- ❌ 进度条（--progress 已声明但未实现）
- ❌ `--delete` 接收端删除逻辑（见下方说明）

### `--delete` 功能缺失说明

`--delete` 选项当前**仅在作为客户端连接远程真实 rsync server 时生效**，删除操作由远程 `rsync --server` 进程完成。已实现的协议层支持包括：

- 解析 `--delete` 命令行参数并传递到协议层
- 在 SSH 模式下向远程 server 发送 `--delete` 选项
- 发送 filter list 终止标记（server receiver 在 `--delete` 启用时才会读取）
- 文件列表中目录条目标记 `XMIT_TOP_DIR`，供 server 端 generator 识别

**未实现的部分**：本项目自身的 receiver/server 端（[receiver.go](lib/rsync/receiver.go)、[server.go](lib/rsync/server.go)）没有删除逻辑。当目标端为本项目的原生 server 时，`--delete` 不会真正删除目标侧多余的文件。需要在 generator 阶段比对本地已有文件与接收到的 file list，删除本地存在但 file list 中不存在的文件。

## 项目结构

```
rsync/
├── cmd/
│   ├── rsync/             # 主 CLI 入口
│   ├── cgo_reverse_test/  # cgo 反向测试
│   ├── ssh_test/          # SSH 模式测试
│   └── ...                # 其他测试入口
├── lib/
│   ├── cli/               # 命令行解析
│   ├── checksum/          # 校验和实现（MD4/MD5）
│   ├── compress/          # 压缩工具
│   ├── flist/             # 文件列表处理
│   ├── match/             # 匹配算法
│   ├── remote/            # 远程连接
│   ├── rsync/             # 核心协议实现
│   │   ├── compressed.go    # 压缩 token 流
│   │   ├── flist_reader.go # 文件列表读取
│   │   ├── multiplex.go    # 多路复用
│   │   ├── receiver.go     # 接收端
│   │   ├── sender.go       # 发送端
│   │   └── ...
│   └── ssh/               # SSH 连接库
├── cgo/                   # C 代码桥接
└── Makefile
```

## 基本用法

```bash
# 本地同步
rsync -avz /path/to/source/ /path/to/dest/

# SSH 远程同步
rsync -avz /path/to/source/ user@host:/path/to/dest/

# 干运行（不实际传输文件）
rsync -avzn /path/to/source/ /path/to/dest/

# 删除目标多余文件
rsync -avz --delete /path/to/source/ /path/to/dest/

# 查看版本
rsync --version
```

## 作为 Go 库使用

```go
import (
    "gitee.com/extrame/rsync/lib/rsync"
)

opts := &rsync.RsyncOptions{
    Archive:     true,
    Compress:    true,
    Source:      []string{"/path/to/source/"},
    Destination: "/path/to/dest/",
}

sync := rsync.NewRsync(opts)
if err := sync.Sync(); err != nil {
    panic(err)
}
```

## 测试

```bash
# 运行所有测试
go test ./...

# 运行压缩相关测试
go test ./lib/rsync/... -v -run TestCompressed
```

## 技术栈

- **Go 1.26**
- **cobra** — 命令行框架
- **zlib** — 压缩库（通过 CGO 桥接）

## 与原生 rsync 的兼容性

| 场景 | 状态 | 说明 |
|------|------|------|
| Go sender → C receiver | ✅ 可用 | 通过 cgo 桥接 |
| Go sender → rsync 3.x server | ✅ 基本可用 | SSH 模式，支持压缩 |
| C sender → Go receiver | ⚠️ 部分支持 | 基本功能可用 |
| rsync daemon 模式 | ❌ 不支持 | |

## 许可证

本项目基于与 rsync 相同的许可证发布。

## 贡献

欢迎贡献代码！请确保通过现有测试，并为新功能添加测试用例。

## 路线图

1. **v0.2** — 完善压缩支持，添加 zstd/lz4
2. **v0.3** — 实现 Delta Transfer 算法
3. **v0.4** — 完善过滤器规则和高级选项
4. **v0.5** — 性能优化和兼容性提升