Gitee Sync Plus

一款为 Obsidian 打造的笔记同步插件：无需在电脑上安装 Git，直接把你的笔记仓库同步到 Gitee / GitHub / GitLab / Gitea。

English · 简体中文

✨ 功能特性

• 零本地 Git 依赖：插件通过各平台的 REST API 直接读写仓库，不需要本机安装 Git、也不依赖 git 命令行。
• 三向同步：把「本地仓库 / 远端仓库 / 上次成功同步时的状态」三方比对，能区分「这边改了」还是「那边改了」，并支持双向删除传播（本地删了、远端也删；反之亦然）。
• 多平台支持：一套配置在 Gitee、GitHub、GitLab、Gitea 之间自由切换，切换后端后首次同步会做一次全量对账并保留较新的版本。
• 冲突解决：同一文件两端都改了，默认按「修改时间较新者」胜出；也可在弹窗里手动选择「保留本地 / 使用远端 / 合并」。
• 差异对比（Diff）：可视化查看文件改动，支持并排 / 纵向布局、折叠未变更片段、按区块还原、一键采纳本地或远端版本、标记为已同步。
• Git 面板：类 IDE 的右侧边栏「源代码管理」视图 —— 列出本地 / 远端改动、暂存（Stage）、推送（Commit）、拉取（Pull）、放弃改动、查看差异。
• 令牌安全存储：访问令牌优先存入 Obsidian 钥匙串（SecretStorage），数据文件里不再保留明文；支持多套命名密钥（Profile）自由切换，并自动从旧版明文配置迁移。
• 自动化与时机：可设置「自动同步间隔（分钟）」「启动时同步」，也可随时手动触发。
• 提交策略可配：单独提交（每文件一条提交）或批量提交（所有变更合并为一次提交）；冲突合并策略可选「最新修改时间 / 全部远端 / 全部本地」。
• 统一排除规则：过滤逻辑全部收敛到 vault 根目录的 .gitignore，支持标准 gitignore 语法。
• 双向国际化：内置简体中文与英文界面。

兼容移动端（manifest 已声明 isDesktopOnly: false）。注意：令牌钥匙串依赖 Obsidian 1.11.4+ 的 SecretStorage；低于该版本时令牌会作为兜底写入 data.json（仍以明文存储，请务必为仓库设置私有 + 排除日志）。

📦 安装

方式一：BRAT（推荐，方便跟进更新）

1. 安装 BRAT 插件。
2. 命令面板运行 BRAT: Add a beta plugin。
3. 填入仓库地址：hellokunzai/obsidian-gitee-sync-plus。
4. 启用 Gitee Sync Plus 即可。

方式二：手动安装

1. 到 Releases 下载 main.js、manifest.json、styles.css 三个文件。
2. 放入 <你的 vault>/.obsidian/plugins/gitee-sync-plus/ 目录（没有就新建）。
3. 在 Obsidian 设置 → 第三方插件中启用 Gitee Sync Plus。

⚙️ 快速配置

打开 设置 → Gitee Sync Plus：

1. 存储后端：选择 Gitee / GitHub / GitLab / Gitea。
2. 访问令牌：点击「选择密钥」从 Obsidian 钥匙串中选取（或「添加密钥…」新建一个命名密钥并粘贴令牌）；也可用「测试」按钮校验令牌是否可用。
   • Gitee：设置 → 安全设置 → 私人令牌，勾选 projects 权限。
   • GitHub：Settings → Developer settings → Personal access tokens，勾选 repo 权限。
   • GitLab：Settings → Access Tokens，需要 api（或 read_repository + write_repository）权限。
   • Gitea：Settings → Applications → Generate Token（或实例的访问令牌页），需要仓库读写权限。
3. 用户名 / 组织 与 仓库名：填写仓库所属者（URL 中的 owner）与仓库名，建议使用一个专用的私有仓库。
4. 分支：填好上方信息后点击「刷新分支」自动拉取，或手动填写（Gitee 默认 master，其余默认 main）。
   • GitLab / Gitea 还需在「高级设置 / 对应字段」填写实例地址（托管版分别为 https://gitlab.com、https://gitea.com）。
5. （可选）同步设置：开启「同步按钮」（左侧栏 ribbon 快速同步）、「启动时同步」、设置「自动同步间隔」。
6. （可选）高级：开启「Git 面板按钮」、开启「调试日志」、按需调整「合并方式」「提交模式」。

配置完成后，点击状态栏的同步状态、左侧 ribbon 的同步按钮，或命令面板的 Sync now 即可开始同步。

💻 命令与入口

🗂️ Git 面板

通过 ribbon 按钮或命令打开右侧 Git 面板，它像 IDE 的源代码管理侧栏一样工作：

• 本地更改：下次同步会被推送的文件。可单独「暂存」「查看差异」「放弃改动」，或「全部暂存 / 放弃全部」。
• 远端更改：下次同步会被拉取 / 在本地删除的文件。
• 推送（Commit）：把暂存的本地改动上传到远端；批量模式下可在顶部填写提交说明。
• 拉取（Pull）：下载远端改动（同步的第一阶段）。
• 刷新：重新计算本地 / 远端差异。
• 点击任意文件可打开 差异对比 视图。

🔀 冲突解决

当某个文件自上次同步以来两端都发生了修改，同步拉取时会弹出冲突解决窗口：

1. 依次查看每个冲突文件，选择：
   • 保留本地：以本地版本为准；
   • 使用远端：以远端版本为准；
   • 合并…：进入合并编辑器，为每一个冲突区块选择一侧或「两者都保留」，结果可自由编辑后保存。
2. 也可用「全部保留本地 / 全部使用远端」一键处理。
3. 确认无误后点击 Confirm pull 完成拉取。

非交互式同步（如按钮、启动、定时）会根据「合并方式」设置自动裁决，无需手动介入。

差异对比视图内同样支持：并排 / 纵向布局切换、折叠未变更片段、按区块「还原 / 采纳本地 / 采纳远端」、「标记为已同步」（把该文件从本次待处理中移出，视为已一致）。

🚫 排除规则（.gitignore）

所有过滤逻辑统一由 vault 根目录的 .gitignore 控制（标准 gitignore 语法）。 在设置 → 排除目录 中编辑规则，失去焦点即保存，下次同步生效。

建议至少把以下内容排除，避免把插件自身状态与日志在设备间传来传去：

# 插件诊断日志（已记录同步计划与结果，不应参与同步）
_gitee-sync-plus-log.md

# 其它不应同步的内容（示例）
# .obsidian/
# Templates/

🔒 安全与隐私

• 令牌存于钥匙串：当运行环境支持时，访问令牌写入 Obsidian 钥匙串（secretStorage），data.json 中只保留密钥名、不保留明文值；打开设置页时会自动把旧版明文令牌迁移进钥匙串。
• 日志默认排除：诊断日志 _gitee-sync-plus-log.md 含同步明细，已在上述 .gitignore 示例中排除。
• 私有仓库：强烈建议使用一个专用的私有仓库存放笔记。
• 多密钥：可在钥匙串中维护多套命名密钥（例如区分个人 / 工作令牌），每个后端独立选择使用哪一套。

🛠️ 故障排查

🔗 与 Gitee Sync 的关系

本插件由社区插件 Gitee Sync 派生而来，并重写了同步引擎：将所有过滤条件统一收敛至 .gitignore 机制，同时支持 Gitee 与 GitHub 双平台（并已扩展至 GitLab、Gitea），且不再依赖本机 Git。

📄 许可证

MIT