# dirsync **Repository Path**: cjl2385/dirsync ## Basic Information - **Project Name**: dirsync - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-07 - **Last Updated**: 2026-11-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # dirsync 通用文件夹对比/同步工具:列出两个目录的差异,按明确方向选择性同步,带 TUI 与 JSON 配置 ## 核心语义 **先定方向,再谈差异**。每次对比/同步都有显式方向: ``` 源 /path/A ──────同步──────▶ 目标 /path/B ``` | 动作 | 判定 | 执行 | |------|------|------| | 复制新增 | 源有、目标无 | 复制 源 → 目标 | | 覆盖更新 | 两边都有但不同 | 复制 源 → 目标(覆盖) | | 多余删除 | 目标有、源无 | 以源为基准,从目标删除 | | (一致) | 相同 | 不显示 | - 复制永远是 源 → 目标;删除永远以源为基准删目标 - 随时按 `d` 换方向:扫描事实不变,动作标签即时反转(比如手机上新下载的歌推回电脑) - 对比用「大小 + 修改时间」,mtime 容差默认 2 秒(FAT/exFAT 精度);复制保留源 mtime - 端点支持 `adb:` scheme 访问 Android 设备(见下节),其余路径一律视为本地目录 - `sync.trashDir` 空字符串 = 默认 `~/.dirsync-trash`,按 `<时间戳-唯一批次>/<目标目录名>/<相对路径>` 分层存放;仅实际执行删除计划时创建,回滚直接拷回;备份目录必须位于两个同步端点之外 - 删除默认移入备份目录(可回滚),可配置为直接删除 - 源和目标必须是目录,不能相同或互相嵌套;本地与 ADB 的目录根符号链接会解析后扫描,子树中的符号链接不参与对比 - 本地文件操作由 `os.Root` 限制在根内;ADB 在操作前拒绝路径链中的符号链接,但 shell 检查不提供对其他进程并发替换路径的原子隔离,执行时不要同时调整设备目录或链接 - 执行前重新检查两端仍为有效目录;先完成删除阶段,再执行复制,删除失败会阻止依赖该路径的复制,不影响无关文件 - 本地备份也通过受约束的复制、提交、删除完成(不再使用同盘 rename 快路径);复制可取消,取消时保留原文件 ## 安装与使用 ```sh go build -o dist/dirsync ./cmd/dirsync # 编译本机版本(dist/ 已忽略,不入库) bun run build:all # 编译 Linux amd64、macOS arm64、Windows amd64 ``` ```sh dirsync # 启动 TUI(主界面,可在界面里维护全部配置) dirsync diff <源> <目标> # 打印差异与执行计划(退出码 0 无差异 / 1 有差异 / 2 出错) dirsync apply <源> <目标> --yes # 脚本化执行(--dry-run 预览、--delete trash|direct) dirsync config path|init # 显示 / 初始化配置文件 ``` TUI 内可以:新建/编辑/删除同步对(带目录浏览器)、改全局设置(删除模式、备份目录、 mtime 保留、并发数、容差、主题、执行确认),全部写回 config.json,无需手改文件 ## 配置 查找顺序:`--config` 参数 > `DIRSYNC_CONFIG` 环境变量 > `~/.config/dirsync/config.json` (全平台统一位置,`$XDG_CONFIG_HOME` 可覆盖,便于查找与跨机器同步) 本地端点、备份目录和配置文件路径支持 `~` 与 `~/...` 展开为当前用户家目录,不支持 `~用户名` `adb:` 路径不展开。完整示例见 [config.example.json](config.example.json) **默认忽略(无需配置,无条件生效)**:`*.tmp` `*.temp` `*.swp` `*.part` `*.download`、 macOS 的 `.DS_Store` `._*` `.localized` `__MACOSX/` `.Spotlight-V100/` `.fseventsd/` `.Trashes/`、 Windows 的 `Thumbs.db` `desktop.ini` `ehthumbs.db` `$RECYCLE.BIN/` `System Volume Information/`、 Android/网络存储的 `.thumbnails/` `@eaDir/` `lost+found/` pair 的 `ignore` 字段只写增量规则(规则语义:`*.tmp` 按文件名匹配、`dir/` 剪枝整个目录、也可匹配完整相对路径) ```json { "pairs": [ { "name": "phone-music", "a": { "label": "电脑", "path": "~/Music" }, "b": { "label": "手机", "path": "adb:/storage/emulated/0/Music" }, "defaultDirection": "b-to-a", "ignore": ["*.part"] } ], "compare": { "mode": "size-mtime", "mtimeToleranceSec": 2 }, "sync": { "deleteMode": "trash", "trashDir": "", "preserveMtime": true, "concurrency": 4 }, "ui": { "theme": "dark", "confirmBeforeApply": true } } ``` ## 手机怎么连(重要) 两种方式,按需选: ### 1. adb 后端(推荐,三平台统一) 端点路径写 `adb:` 前缀即可,无需任何挂载工具: ```sh dirsync diff ~/Music adb:/storage/emulated/0/Music # 默认设备 dirsync diff ~/Music adb://SERIAL/storage/emulated/0/Music # 多台设备时指定序列号 ``` - 依赖 Google platform-tools、设备的 `shell_v2` 能力及 `sha256sum` 命令;缺少校验能力时在执行同步前报错,不降级为不校验的传输 - 手机开启一次「开发者选项 → USB 调试」,之后插线即用;也支持 Wi-Fi 调试(`adb tcpip`) - 文件字节只走原生 `adb pull` / `adb push`,不通过 `shell` / `exec-out` 的 stdout 传输;不对二进制做换行转换 - 下载先保存到私有临时目录,与下载前取得的远端大小和 SHA256 一致后才交给目标写入;上传先校验远端临时文件,再替换正式目标。校验失败不会覆盖正式目标,也不会删除待备份的原件 - 下载额外占用一份临时文件空间(每个并发任务一份);下载和校验期间复制进度可能暂不增长。取消/关闭会清理本机临时文件,断连时远端临时文件只能尽力清理 - 校验保证传输字节一致,不判断源文件本身是否可播放;执行同步时应暂停两端会修改文件的程序 - 三平台(Windows/macOS/Linux)同一套代码 - 配置文件里直接写在 `path` 字段:`"b": {"label": "手机", "path": "adb:/storage/emulated/0/Music"}` - 注意:MTP 与 adb 不能同时占用手机,用 adb 后端时手机选「仅充电」即可 #### 安装 adb 不同系统的包名不同: ```sh # Arch Linux / Manjaro(也可用 paru -S android-tools) sudo pacman -S android-tools # Debian / Ubuntu sudo apt install android-sdk-platform-tools # Fedora sudo dnf install android-tools # macOS(Homebrew) brew install --cask android-platform-tools # Windows(PowerShell / winget) winget install --id Google.PlatformTools --exact ``` 也可从 [Android 官方页面](https://developer.android.com/tools/releases/platform-tools)下载对应系统的 Platform-Tools,并将解压目录加入 PATH。安装后运行 `adb version` 验证;手机启用 USB 调试并连接后,运行 `adb devices`,在手机上确认授权,设备显示 `device` 即已连接 ### 2. 挂载成普通路径 | 平台 | 现状 | 建议 | |------|------|------| | Linux | gvfs/jmtpfs/go-mtpfs 可把 MTP 挂载成真实目录 | 直接用挂载路径 | | Windows | 资源管理器里的 MTP 设备不是文件系统路径,程序读不到 | adb 后端;或手机端 SMB/FTP 挂载为网络驱动器 | | macOS | Finder 不支持 Android;OpenMTP 不暴露路径 | adb 后端;或 MacDroid / go-mtpfs 挂载 | 任何「能以路径访问」的形式(挂载、网络共享、另一块磁盘、两个本地目录)都可以直接用 ## 开发 ```sh go test ./... # 隔离目录测试;本机存在已上传的音频原件时额外只读核对已知哈希 bun scripts/smoke-test.ts # 端到端冒烟(自动创建/清理临时测试环境) bun scripts/make-test-env.ts # 单独创建可恢复的测试环境,打印根目录 bun scripts/make-test-env.ts --clean # 清理 ``` 架构:`internal/config`(JSON 读写与归一化)→ `internal/storage`(存储抽象 + 本地实现, 预留 MTP 后端)→ `internal/scan`(忽略规则遍历)→ `internal/diff`(对称事实 + 方向化计划) → `internal/sync`(并发执行、备份删除、进度、取消)→ `internal/tui`(Bubble Tea v2 界面)