syncmac

个人文件同步工具 v2.5.3

基于 rsync 的高效文件同步工具，专为 macOS 设计，支持本地备份、远程同步和实时进度显示。

特性

• 双向同步 - 通过别名（sb/sbr）轻松切换同步方向
• 实时进度 - ANSI 动画 spinner 显示扫描和同步状态
• 智能过滤 - 支持 DOTFILES 模式（仅同步 .* 隐藏文件和目录）和自定义排除规则
• 组合目标 - 支持预设的目标组合（kernel、all），一键同步多个目录
• Dry-run 模式 - 安全预演，避免意外数据损失
• 零依赖 UI - 使用 ANSI 转义码，仅需 Python 标准库，无需第三方 UI 框架
• 大文件进度 - 实时显示大文件传输百分比和速度
• 全局排除 - 自动排除 Caches、__pycache__、node_modules 等目录

依赖

• Python 3.8+
• rsync（macOS 自带）

安装

# 克隆项目
git clone https://github.com/yourusername/syncmac.git ~/Work/home1/feng/BIN/syncmac

# 设置可执行权限
chmod +x ~/Work/home1/feng/BIN/syncmac/syncmac.py

# 创建别名（推荐）
cd ~/bin
ln -s ~/Work/home1/feng/BIN/syncmac/syncmac.py sb     # 正向同步（本地 → 备份）
ln -s ~/Work/home1/feng/BIN/syncmac/syncmac.py sbr    # 反向同步（备份 → 本地）

使用方法

基本用法

# 同步默认目标（dot）
python syncmac.py

# 同步指定目标
python syncmac.py -t doc

# 预演模式（不实际执行）
python syncmac.py -n -t work

# 列出所有可用目标
python syncmac.py -l

# 使用别名
sb -t kernel             # 本地 → 备份
sbr -t teaching          # 备份 → 本地

命令行选项

选项	说明
-n, --dry-run	预演模式，不实际执行
-q, --quiet	安静模式，减少输出
-v, --verbose	详细模式，显示调试信息
-t, --tgt	指定同步目标（默认: dot）
-l, --list	列出所有可用的同步目标
-from	源路径（可选）
-to	目标路径（可选）
--version	显示版本号

同步别名

别名	同步方向	说明
sb / syncmac-backup	本地 → 备份	备份到外部磁盘
sbr / syncmac-restore	备份 → 本地	从备份磁盘恢复

同步目标

组合目标

名称	包含目标	说明
kernel	dot, doc, init, lib, pic, res, work	核心数据
all	kernel, journal, movie, opt, elib, teaching	全部数据

单个目标

名称	源路径	说明
dot	~/	DOTFILES 模式，仅同步 .* 文件和目录
doc	~/Documents	文档目录
init	~/Init	初始化脚本
lib	~/Library	用户库（排除 Mobile Documents, CloudStorage）
pic	~/Pictures	图片目录
res	~/Research	研究资料
work	~/Work	工作目录
journal	/JOURNALS	日志目录
movie	/Movies	电影目录
opt	/opt	可选软件
elib	/RDS Library	电子图书馆
teaching	/Teaching	教学材料
fengh	~/fengh	用户目录

DOTFILES 模式

dot 目标使用特殊的 DOTFILES 模式，仅同步隐藏文件和目录：

• 同步所有 .* 文件
• 递归同步所有 .* 目录
• 不同步任何普通子目录（Documents、Work 等）
• 保留软链接：ln -s 创建的软链接会被保留为链接，不会拷贝内容
• 实时显示扫描进度

优化：直接扫描 .* 条目，避免遍历整个目录树，扫描速度提升约 70 倍。

配置

编辑 syncmac.py 中的配置常量：

VERSION = "2.5.3"
DEFAULT_HOME = "fengh"                      # 默认用户名
DEFAULT_UDIR = "/Users"                     # 用户目录根路径
DEFAULT_UDISK = "/Volumes/BACKUP/MAC"       # 备份磁盘挂载点

GLOBAL_EXCLUDES = [                          # 全局排除规则
     "Caches",
     "__pycache__",
     "node_modules",
]

输出示例

syncmac v2.5.0
  目标: dot
  源: /Users/fengh
  目标: /Volumes/BACKUP/MAC

⠙ 正在扫描目录... (1523 个文件)
✓ 扫描完成 (1523 个文件, 0.2s)
→ 同步: dot
  源: /Users/fengh/
  目标: /Volumes/BACKUP/MAC/fengh

⠋ 正在同步... (0 个文件, 已检查 0.5s)
✓ 同步完成 (0 个文件, 全部最新, 0.5s)
✓ 完成: dot

故障排除

rsync code 23

部分文件无法传输（非致命错误）：

• 运行中的应用锁定了文件
• 云存储服务超时
• 符号链接冲突

权限错误

确保有源路径的读取权限和目标路径的写入权限。

InterruptedError (errno 4)

macOS 下某些系统目录（如 CrashReporter）在信号中断时可能导致 os.listdir() 抛出 InterruptedError。这是非致命错误，工具会自动跳过该目录继续扫描。

版本历史

• v2.5.3 (2026-04-23) - 优化显示和同步流程 - 改进：优化终端显示和同步流程

• v2.5.2 (2026-04-23) - 优化显示信息 - 改进：继续优化终端显示效果

• v2.5.1 (2026-04-24) - 修复多行显示问题 - 修复：解决大文件传输时偶尔出现多行"正在同步..."的问题 - 原理：在状态变化时使用 force=True 强制更新显示，减少与后台 spinner 线程的竞争窗口

• v2.5.0 (2026-04-23) - 简化显示逻辑 - 修复：回到最简单的方案，每次都清除并重新打印所有内容 - 改进：分离主状态行和文件列表区域的显示管理 - 效果：代码简洁，逻辑清晰，易于维护

• v2.3.x - 显示阶段分隔优化（完整空行分隔、单行动态更新等）

• v2.2.x - ANSI 转义码修复、大文件进度、全局排除规则

许可证

内部使用

作者

Hao Feng (F1) © 2020-2026, RDS