Obsidian GitHub Sync
Automated synchronization of Obsidian vault with GitHub repository using git with conflict detection.
Features
- - Automatic sync:
git pull --rebase → commit → push - Conflict detection: Detects and flags merge conflicts
- Configurable: Environment variable based configuration
- Notification: Optional conflict notifications
- Safe: Uses rebase to maintain clean history
Quick Start
1. Set Environment Variables
CODEBLOCK0
2. Run Initial Sync
CODEBLOCK1
3. Setup Auto-sync (Cron)
CODEBLOCK2
Scripts
obsidian-sync.sh
Main synchronization script. Located at scripts/obsidian-sync.sh.
What it does:
- 1. Checks for uncommitted changes and commits them
- Pulls from GitHub with INLINECODE2
- Pushes to GitHub
- Creates conflict flag if rebase fails
Environment Variables:
- -
OBSIDIAN_VAULT_DIR (required): Path to Obsidian vault - INLINECODE4 (required): GitHub repository URL
- INLINECODE5 (optional): Git user name
- INLINECODE6 (optional): Git user email
- INLINECODE7 (optional): Log file path (default:
/tmp/obsidian-sync.log) - INLINECODE9 (optional): Conflict flag path (default:
/tmp/obsidian-sync-conflict.flag)
check-conflict.sh
Conflict checking script. Located at scripts/check-conflict.sh.
What it does:
- - Checks if conflict flag file exists
- Outputs conflict details if found
- Returns exit code 1 on conflict, 0 on clean state
Workflow
Normal Sync Flow
CODEBLOCK3
Conflict Flow
CODEBLOCK4
Handling Conflicts
When conflicts occur:
- 1. Check conflict flag file location (default:
/tmp/obsidian-sync-conflict.flag) - Navigate to vault directory
- Resolve conflicts using standard git workflow:
CODEBLOCK5
Configuration Reference
See references/setup-guide.md for detailed setup instructions including:
- - SSH key configuration
- Multi-device sync best practices
- Troubleshooting guide
- Cron setup examples
Integration Examples
With OpenClaw
CODEBLOCK6
With Systemd (Linux)
Create ~/.config/systemd/user/obsidian-sync.service:
CODEBLOCK7
Create ~/.config/systemd/user/obsidian-sync.timer:
CODEBLOCK8
Enable:
CODEBLOCK9
Best Practices
- 1. Close Obsidian during sync to avoid file lock issues
- Commit regularly in Obsidian to reduce conflict chances
- Sync before switching devices
- Use
.gitignore to exclude Obsidian's cache files:
CODEBLOCK10
License
MIT
Obsidian GitHub 同步
使用 Git 实现 Obsidian 仓库与 GitHub 存储库的自动同步，并具备冲突检测功能。
功能特性
- - 自动同步：git pull --rebase → 提交 → 推送
- 冲突检测：检测并标记合并冲突
- 可配置：基于环境变量的配置方式
- 通知机制：可选的冲突通知功能
- 安全可靠：使用变基操作保持提交历史整洁
快速开始
1. 设置环境变量
bash
export OBSIDIANVAULTDIR=/path/to/your/obsidian-vault
export GITHUBREMOTEURL=git@github.com:username/repo.git
2. 运行初始同步
bash
./scripts/obsidian-sync.sh
3. 设置自动同步（定时任务）
bash
每天凌晨3点执行
0 3
* /path/to/scripts/obsidian-sync.sh
上午9点检查冲突
0 9
* /path/to/scripts/check-conflict.sh
脚本说明
obsidian-sync.sh
主同步脚本。位于 scripts/obsidian-sync.sh。
功能说明：
- 1. 检查未提交的更改并自动提交
- 使用 --rebase 从 GitHub 拉取更新
- 推送到 GitHub
- 若变基失败则创建冲突标记文件
环境变量：
- - OBSIDIANVAULTDIR（必填）：Obsidian 仓库路径
- GITHUBREMOTEURL（必填）：GitHub 存储库 URL
- GITUSERNAME（可选）：Git 用户名
- GITUSEREMAIL（可选）：Git 用户邮箱
- SYNCLOGFILE（可选）：日志文件路径（默认：/tmp/obsidian-sync.log）
- CONFLICTFLAGFILE（可选）：冲突标记文件路径（默认：/tmp/obsidian-sync-conflict.flag）
check-conflict.sh
冲突检查脚本。位于 scripts/check-conflict.sh。
功能说明：
- - 检查冲突标记文件是否存在
- 若存在则输出冲突详情
- 存在冲突时返回退出码 1，无冲突时返回 0
工作流程
正常同步流程
用户在 Obsidian 中修改笔记
↓
定时任务在凌晨3点运行 obsidian-sync.sh
↓
自动提交本地更改
↓
git pull --rebase origin master
↓
git push origin master
↓
同步完成 ✓
冲突处理流程
同步运行
↓
pull --rebase 失败（远程存在分歧更改）
↓
创建冲突标记文件
↓
退出并报错
↓
早晨 check-conflict.sh 检测到标记文件
↓
通知用户
↓
用户手动解决冲突
↓
重新运行同步
冲突处理
当发生冲突时：
- 1. 检查冲突标记文件位置（默认：/tmp/obsidian-sync-conflict.flag）
- 导航到仓库目录
- 使用标准 Git 工作流程解决冲突：
bash
cd $OBSIDIANVAULTDIR
git status # 查看冲突文件
编辑文件解决冲突
git add -A # 暂存已解决的文件
git rebase --continue # 完成变基
git push origin master # 推送解决后的状态
配置参考
详细设置说明请参阅 references/setup-guide.md，包括：
- - SSH 密钥配置
- 多设备同步最佳实践
- 故障排除指南
- 定时任务设置示例
集成示例
与 OpenClaw 集成
bash
添加同步定时任务
openclaw cron add --name obsidian-sync \
--cron 0 3
* \
--command /path/to/obsidian-sync.sh
添加冲突检查
openclaw cron add --name obsidian-check \
--cron 0 9
* \
--command /path/to/check-conflict.sh
与 Systemd 集成（Linux）
创建 ~/.config/systemd/user/obsidian-sync.service：
ini
[Unit]
Description=Obsidian 仓库 Git 同步
[Service]
Type=oneshot
Environment=OBSIDIANVAULTDIR=/path/to/vault
Environment=GITHUBREMOTEURL=git@github.com:user/repo.git
ExecStart=/path/to/obsidian-sync.sh
创建 ~/.config/systemd/user/obsidian-sync.timer：
ini
[Unit]
Description=每天凌晨3点运行 Obsidian 同步
[Timer]
OnCalendar=--* 03:00:00
Persistent=true
[Install]
WantedBy=timers.target
启用：
bash
systemctl --user daemon-reload
systemctl --user enable obsidian-sync.timer
systemctl --user start obsidian-sync.timer
最佳实践
- 1. 同步时关闭 Obsidian，避免文件锁定问题
- 在 Obsidian 中定期提交，减少冲突发生概率
- 切换设备前先同步
- 使用 .gitignore 排除 Obsidian 的缓存文件：
gitignore
Obsidian
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/plugins/*/data.json
.trash/
许可证
MIT
