本文提供 Obsidian Git Sync 插件的完整使用指南，从安装配置到日常操作，帮助你轻松为 Obsidian 笔记添加 Git 版本控制。
📋 目录
安装插件
方法 1: 手动安装
- 前往 Releases 下载最新版本的压缩包文件
- 在 Obsidian 库插件目录中解压缩：
你的库/.obsidian/plugins/git-sync/ - 重启 Obsidian 并在设置中启用插件
方法 2: 从源码构建（高级用户）
# 克隆仓库
git clone https://github.com/icecome/obsidian-plugin-git-sync.git
cd obsidian-plugin-git-sync
# 安装依赖
npm install
# 构建
npm run build
# 开发模式（监视文件变化）
npm run dev
开启并初始化仓库
安装完成后，需要开启插件并初始化 Git 仓库：
开启插件
- 启动 Obsidian
- 点击左侧文件浏览器底部的设置图标，选择第三方插件，关闭安全模式，然后下滑找到"Git Sync"插件，开启它。
- 在设置左侧第三方插件菜单项内找到"Git Sync"插件，点击它；
- 选择认证方式。
认证配置
插件支持三种认证方式，根据你的需要选择：
方式 1: Git 凭据管理器
优点：无需手动输入密码，系统自动管理凭据
设置步骤：
- 在插件设置中选择"认证方式"为"凭据管理器"
- 系统会自动使用：
- Windows: Windows Credential Manager
- macOS: osxkeychain
- Linux: cache 或 libsecret
方式 2: SSH 密钥
优点：更安全，无需密码
设置步骤：
- 在插件设置中选择"认证方式"为"SSH 密钥"
- 点击"生成新密钥"按钮
- 选择密钥类型（Ed25519(推荐) 或 RSA）
- 复制生成的公钥，添加到你的 Git 平台（GitHub、GitLab 等），右上角个人头像——settings——SSH and GPG keys——New SSH Key
方式 3: HTTPS 手动输入
优点：简单直接 缺点：每次同步需要输入密码
设置步骤：
- 在插件设置中选择"认证方式"为"HTTPS 手动输入"
- 每次同步时会弹出输入框，输入你的 Git 账号和密码
配置根目录并初始化、添加远程仓库
- 建议在 Obsidian 根目录下创建一个新的文件夹，用于存放 Git 仓库。
- 打开插件设置，将"根目录"设置为新创建的文件夹路径，示例：“根目录/新文件夹名/"。
- 点击"初始化仓库"按钮，初始化 Git 仓库。
- 点击远程仓库 URL 右侧的输入框，添加你的远程 Git 仓库 URL，应用并更新。地址示例如
git@github.com:changan0827/blog.git。（这里推荐使用 SSH 地址，通常 HTTPS 地址被屏蔽，同步拉取困难。） - 分支默认为 main，如有不同，一并更改，应用并更新。
日常操作指南
执行同步
- 点击左侧边栏的 Git 图标
- 点击"立即同步"按钮
- 系统会自动：
- 检查文件更改
- 创建提交
- 拉取远程更改
- 推送到远程仓库
查看更改历史
- 点击左侧边栏的 Git 图标
- 弹出的弹窗下方即为“仓库状态”，显示当前分支、仓库和提交更改信息
处理冲突
如果遇到文件冲突：
- 插件会显示冲突文件列表
- 手动编辑冲突文件，解决冲突
- 保存文件后，再次执行同步
自动同步设置
启用自动同步
- 在插件设置中找到"启用自动同步"选项
- 勾选此选项
- 设置"同步间隔”（建议 5-15 分钟）
自动同步的工作原理
- 系统会在后台定期检查文件更改
- 当检测到更改时，自动创建提交并推送
- 同步过程不会影响你的正常编辑
状态栏使用
插件会在 Obsidian 状态栏显示 Git 仓库状态：
🌿 main- 当前分支为 main🌿 main [+2 ~1 -1]- 有 2 个新增、1 个修改、1 个删除的文件🌿 main ⚠️- 未配置远程仓库🌿 main 🔄- 正在同步中
点击状态栏可以快速打开 Git 面板。
快捷命令
插件提供以下快捷命令，可通过 Obsidian 命令面板（Ctrl+P 或 Cmd+P）访问：
Git Sync: 立即同步- 提交并推送更改Git Sync: 拉取远程更改- 拉取远程更新Git Sync: 推送到远程- 推送本地提交Git Sync: 查看仓库状态- 显示详细状态Git Sync: 初始化仓库- 初始化新的 Git 仓库
常见问题解决
SSH 连接失败
解决方案：
- 运行设置中的"SSH 详细诊断"
- 检查 SSH 密钥权限：
chmod 600 ~/.ssh/id_ed25519（Windows 不需要操作） - 确保公钥已添加到 Git 平台
- 尝试创建
~/.ssh/config文件指定密钥路径
HTTPS 认证失败
解决方案：
- 运行设置中的"检查凭据"
- 确保凭据管理器已配置
- 尝试清除凭据后重新输入
同步冲突
解决方案：
- 打开冲突文件
- 手动解决冲突（查找
<<<<<<<、=======、>>>>>>>标记） - 保存文件后重新同步
最佳实践
1. 定期备份
- 在使用插件前，对重要笔记进行完整备份
- 定期检查 Git 提交历史，确保数据安全
2. 合理设置同步间隔
- 频繁编辑时：5-10 分钟
- 偶尔编辑时：15-30 分钟
- 避免设置过短的间隔，以免影响性能
3. 使用分支管理
- 为不同项目或主题创建分支
- 定期合并分支，保持主分支整洁
4. 忽略不需要版本控制的文件
在仓库根目录创建 .gitignore 文件，添加：
# Obsidian 生成文件
.obsidian/workspace
.obsidian/plugins/
.obsidian/themes/
# 系统文件
.DS_Store
Thumbs.db
# 临时文件
*.tmp
*.temp
5. 定期拉取远程更改
- 多设备使用时，定期拉取远程更改
- 避免长时间不同步导致冲突
配置选项详解
| 选项 | 说明 | 推荐设置 |
|---|---|---|
| 认证方式 | 选择 SSH 或凭据管理器 | 凭据管理器（推荐） |
| 远程仓库 URL | Git 远程仓库地址 | 你的 Git 仓库地址 |
| 分支名称 | 默认分支 | main |
| 启用自动同步 | 定时自动同步 | 开启 |
| 同步间隔 | 自动同步间隔（分钟） | 10 |
| 推送前拉取 | 推送前先拉取远程更改 | 开启 |
| 提交信息模板 | 自定义提交信息 | 自动同步: {{date}} |
高级技巧
1. 使用自定义提交信息
在设置中修改"提交信息模板"，暂时支持以下变量：
{{date}}- 当前日期时间{{changes}}- 更改的文件数量{{branch}}- 当前分支名称
2. 手动控制同步
如果需要更精细的控制：
- 关闭自动同步
- 使用快捷命令手动执行同步操作
- 可以在重要修改后立即同步
3. 多仓库管理
如果你的 Obsidian 库包含多个项目：
- 在不同目录初始化不同的 Git 仓库
- 为每个仓库配置不同的远程地址
- 分别管理和同步
小结
通过本指南，你已经掌握了 Obsidian Git Sync 插件的完整使用方法：
- ✅ 安装配置 - 从安装到初始化的完整步骤
- ✅ 认证设置 - 三种认证方式的配置方法
- ✅ 日常操作 - 同步、查看历史、处理冲突
- ✅ 自动同步 - 配置定时自动备份
- ✅ 状态监控 - 通过状态栏了解仓库状态
- ✅ 快捷操作 - 使用命令面板快速执行操作
- ✅ 问题解决 - 常见问题的解决方案
- ✅ 最佳实践 - 版本控制的最佳使用方法
现在，你可以安全、便捷地为你的 Obsidian 笔记添加 Git 版本控制，保护你的知识资产，实现多设备同步，并随时追踪笔记的变化历史。
相关资源：