6. PinSlip Git 多设备同步

6. 同步（Git Sync）

多个设备想用同一批便签？开 Git 同步。
用你自己的 Git 仓库（GitHub / GitLab / cnb 等）做同步，自动 commit + pull + push。
更适合技术用户（Obsidian Git 同款人群），小白云同步在路上。

6.1 它是什么

PinSlip 的 Git 同步是可选的额外功能：

• 原理：在 vault 目录里维护一个 git 仓库，定期自动 commit + pull + push

• 去重：变更防抖 3 分钟无操作才触发 commit

• 冲突解决：diff3 三方合并（自动合并不同段落；同一行冲突写标准 markers）

• 过程：在 Go 服务里走 go-git 纯 Go 实现，不依赖本地 git 可执行文件

默认关闭，需要在「设置 → Git 同步」手动开启。

6.2 接入流程

准备

1. 在 GitHub / GitLab / cnb 等平台新建一个空仓库（推荐空仓库，不要勾选 README/license）

2. 创建一个有写权限的 Personal Access Token（PAT）：

   • GitHub：Settings → Developer settings → Personal access tokens → Fine-grained tokens

   • 勾选 Contents: Read and write

   • 复制 token（只显示一次）

在 PinSlip 中配置

设置 → Git 同步 → 填写：

保存后 PinSlip 自动初始化本地仓库、设置 remote、首次提交并推送。

凭据存放

• 写在 <vault>/.pinslip/git-sync.json

• <vault>/.pinslip/ 已在 .gitignore 里，token 永不会随笔记推到远端

• 设置界面里 token 字段留空 = 不修改

6.3 自动同步

同步循环

变更 → 等 3 分钟无新操作 → 自动 commit
  → 拉取 (fetch + merge)
  → 推送 (push)

• commit message：sync YYYY-MM-DD HH:mm (n files)

• 定时 push 间隔：默认 10 分钟（设置里 1~1440 分钟可调）

• 「立即同步」按钮可手动触发

• 退出应用前 5 秒窗口尽力 push 一次

失败处理

• 网络 / 认证失败 → 指数退避：1 分钟 → 5 分钟 → 15 分钟

• 状态面显示 lastError，方便排查

同步内容

6.4 多设备同步

新设备接入

1. 在新设备装 PinSlip

2. 选 vault 目录（要是空目录）

3. 设置 → Git 同步 → 填同一仓库 + 同一 Token

4. PinSlip 自动 clone → 重建索引 → 全部便签出现

多人协作

PinSlip 不锁文件：

• 多人同时编辑同一 vault → 存在最后写赢的风险

• 建议走分支 + PR 流程

同步状态

设置抽屉 → Git 同步区域显示：

• 上次同步时间

• 待推送 n 条

• 错误信息（如果有）

6.5 冲突解决

这是 Git 同步最重要的细节之一。

如何发生

• 两台机器同时修改了同一便签

• pull 时发现无法干净合并 → 写 markers 标记冲突

三种情况

1. 不同段落自动合并（最常见）

你在 A 段加了一行
另一个人改了 B 段

→ 自动合并成功，不打扰你

2. 同一行冲突（少见）

pinSlip 写入标准 git conflict markers：

<<<<<<< HEAD
我新加的这一行
=======
另一个人加的这一行
>>>>>>> origin/main

• 标题推导跳过标记行 → 文件名不会被 markers 污染

• 主界面便签列表顶部出现**「待解冲突」**醒目标识

• API 列表返回 conflicted: true

3. 二进制冲突（图片）

PinSlip 选择保留双方：

• 远端原名

• 本地 name-冲突-时间戳.ext

在便签里解决冲突

打开冲突便签 → 整换为琥珀冲突横幅：

• 等宽 textarea 原文编辑（不走 Markdown 渲染）

• 「全部用本地」 一键剥 markers（保留本地版本）

• 「全部用远端」 一键剥 markers（保留远端版本）

• 「保存解决」 手动落盘（不走 autosave，确保你看完再保存）

保存后 markers 消失 → 自动切回普通 Markdown 编辑器。

外部变更感知

• 外部编辑器（Obsidian / VS Code）改了磁盘上的文件 → PinSlip watcher 感知

• 你没在编辑 → 自动重载 + toast「已同步」

• 你在编辑（有改动） → 弹出横幅「载入最新 / 保留我的」让你知情选择

这是双向同步的体验保障：两台机器互不抢着改。

6.6 常见问题