[!info] related notes

• 上层架构: Obsidian 同步、版本控制与发布架构
• Git 基础: Git, Git MOC
• 发布: Obsidian 静态发布方案选择
• Obsidian: Obsidian MOC

用 Obsidian Git 管理 Vault 版本与异步同步

核验日期：2026-09-30。插件设置名称会变化，具体 UI 以当前插件文档为准。

目标与成功状态

完成后至少能验证：

Vault 是一个正常 Git repository
→ 修改 Markdown 后可看到 diff
→ commit 能产生历史
→ push 到 remote
→ 另一台设备 pull 后得到相同文件
→ 制造一次冲突后能人工解决

这里的核心是 Git version control + async synchronization。

它不是实时协同编辑系统。

先理解 Git 在这里负责什么

Git 能提供：

• change history；
• commit；
• diff；
• remote backup copy；
• pull/push；
• merge/conflict；
• rollback。

但不要把它等同于：

• 实时 Sync；
• 自动无冲突文件系统；
• 完整灾备；
• 云盘式逐字同步。

Obsidian Git 官方文档也明确强调：Git/GitHub 不是 live syncing service，更适合异步版本协作。

1. Desktop 前置条件

Desktop 环境先确认：

git --version

Windows 需要真正安装 Git；只装 GitHub Desktop 不能代表所有插件调用路径都能使用系统 Git。

Linux/macOS 同样先保证命令行 Git 可用。

2. 安装插件

在 Obsidian：

Settings
→ Community plugins
→ Browse
→ Git
→ Install
→ Enable

插件当前主仓库是 Vinzent03/obsidian-git。

3. 新 Vault：初始化 Git

如果目录还不是 repository：

git init
git status

先创建最小 .gitignore。

通常应考虑忽略：

• OS 临时文件；
• 编辑器缓存；
• 不希望跨设备共享的 workspace 状态；
• 体积很大的生成文件。

不要机械忽略整个 .obsidian/。

如果你希望多设备共享：

• 插件列表；
• theme；
• CSS snippets；
• 某些 settings；

其中一部分配置可能正应该进入版本控制。

4. 已有 remote：clone

在 Desktop 可以：

• terminal git clone；
• 或插件提供的 clone workflow。

clone 完成后直接把 repository 目录作为 Vault 打开。

验证：

git status
git remote -v

5. Remote 与认证

GitHub 可以使用 HTTPS + credential helper / token，或 SSH。

不要：

• 把 token 写入 Markdown；
• 把 credential 文件提交进 Vault；
• 把 PAT 硬编码进 remote URL 长期保存。

认证问题应该由 Git credential manager / OS keychain / SSH agent 负责。

6. 最小工作循环

手工理解一次：

git pull --ff-only
git status
git diff
git add .
git commit -m "notes: update ..."
git push

然后再开启插件自动化。

先理解手工语义，才能在自动同步失败时知道卡在哪一步。

7. 自动 Commit / Pull / Push

插件可以定时执行自动 commit-and-sync，也可以在 Obsidian 启动时 pull。

自动化前先决定：

• commit interval；
• pull interval；
• 是否自动 push；
• commit message；
• 冲突时是否停止；
• 是否希望每个小改动都进入历史。

默认建议：

自动化可以减少操作，但不要隐藏 Git failure。

如果 pull/merge 失败，应显式提示并停止继续覆盖。

8. 多设备安全循环

更稳定的心智模型：

Device A
pull
→ edit
→ commit/push

Device B
pull
→ edit
→ commit/push

风险最大的场景：

A 和 B 都长期离线
→ 同时改同一笔记
→ 双方产生 diverged history

这时需要 merge，而不是“谁最后 push 谁覆盖”。

9. 冲突怎么处理

出现冲突时：

git status

找到 both modified 文件。

文件中可能出现：

<<<<<<< HEAD
local content
=======
remote content
>>>>>>> branch

正确流程：

1. 理解两侧修改；
2. 编辑成最终正确内容；
3. 删除 conflict markers；
4. git add；
5. commit；
6. push；
7. 再打开 Obsidian 验证笔记没有结构损坏。

不要把“Accept Current/Incoming”当作无需理解内容的按钮。

10. 移动端边界

当前插件在 Android/iOS 使用 JavaScript Git 实现，而不是系统原生 Git。

官方文档明确列出移动端限制，包括：

• 不支持 SSH authentication；
• repository 大小受内存限制；
• 没有 rebase merge strategy；
• 不支持 submodules；
• clone/pull 在大 Vault 上可能崩溃或极慢。

因此对于较大的 Thought Forest 类 Vault：

不要把 Obsidian Git mobile 当作和 Desktop 一样可靠的默认同步层。

可以考虑专用同步工具负责移动端，再由 Desktop Git 负责版本历史。

11. 大附件

Git 很适合 Markdown，但大量：

• PDF；
• video；
• archive；
• 大图片；

会快速扩大 repository history。

优先问：

• 这些资产是否需要 Git versioning？
• 能否放 object storage？
• 是否需要 Git LFS？

不要等 repository 数 GB 后才处理历史。

12. 恢复验证

版本控制真正有价值，要能恢复。

至少演练一次：

恢复单文件

git log -- path/to/note.md
git restore --source=<commit> -- path/to/note.md

查看历史差异

git log -p -- path/to/note.md

新设备恢复

clone remote
→ open folder as Vault
→ enable required plugins
→ verify links/assets/settings

常见失败

authentication failed

先在终端验证 Git remote auth，再看插件。

push rejected

通常 remote 有你本地没有的 commit：

pull/reconcile
→ resolve conflict if needed
→ push

自动同步不断制造冲突

减少多端并行编辑同一文件；适当提高同步频率；重要 session 开始前先 pull。

“同步成功”但另一台设备没有插件配置

检查 .obsidian/ 中你实际 track/ignore 了什么。

验证清单

• Desktop Git CLI 正常；
• Vault 是 repository；
• remote 正确；
• credential 未进入仓库；
• 手工 pull/commit/push 正常；
• 插件自动化失败时可见；
• 多设备能恢复；
• 已演练一次 merge conflict；
• 大附件策略明确；
• 移动端没有假设成 Desktop Git 等价环境。

无提示执行检查

1. 从一个空 Vault 建立 Git remote；
2. 两台目录模拟 Device A/B；
3. 完成一次异步同步；
4. 人为制造同一行冲突并解决；
5. 恢复一个被误删笔记；
6. 解释 Sync、Git history、remote copy、backup 的区别；
7. 说明为什么大型移动端 Vault 不能默认依赖 Obsidian Git。

官方资料

• https://github.com/Vinzent03/obsidian-git
• https://github.com/Vinzent03/obsidian-git/tree/master/docs