# Obsidian Git 插件配置与踩坑记录

> 2026-06-16 配置完成

## 环境

- 本机：macOS，Obsidian vault 路径 `~/Documents/obsidian`
- 远程仓库：Gogs on princess (84.235.240.199:3080)
- 仓库地址：`ssh://git@84.235.240.199:2222/zhensolid/obsidian.git`
- 账号：`zhensolid` / `zhensolid@vip.qq.com`

## 插件设置

| 配置项 | 值 | 说明 |
|--------|-----|------|
| autoSaveInterval | 10 | 每 10 分钟自动 commit |
| autoPushInterval | 10 | 每 10 分钟自动 push |
| autoPullInterval | 10 | 每 10 分钟自动 pull |
| autoBackupAfterFileChange | **true** | 编辑文件后立即 commit |
| pullBeforePush | true | 推送前先拉取 |
| disablePush | false | |
| differentIntervalCommitAndPush | true | commit 和 push 独立间隔 |

## Git 配置

```bash
# 用户信息（在仓库目录下）
git config user.name "zhensolid"
git config user.email "zhensolid@vip.qq.com"

# 推送策略
git config push.default current

# 分支
git branch -M master
git branch --set-upstream-to=origin/master master
```

## .gitignore

```
.DS_Store
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.trash/
```

## 坑 1：LiveSync 远程干扰

LiveSync 插件会在 git 配置里留下一个叫 `obsidian` 的 remote，指向 SSH Gogs。git 插件会混淆，报错：

```
fatal: The upstream branch of your current branch does not match
```

**解决**：`git remote remove obsidian`

## 坑 2：分支名不匹配

Gogs 默认分支是 `master`，本地可能是 `main`。报错：

```
error: src refspec main does not match any
```

**解决**：`git branch -M master`

## 坑 3：non-fast-forward 拒绝

远程仓库已有内容时，直接 push 会报：

```
[rejected] (non-fast-forward)
hint: Updates were rejected because the tip of your current branch is behind
```

**解决**：

```bash
git pull origin master --allow-unrelated-histories --no-rebase
# 解决冲突
git add .
git commit -m "merge"
git push origin master
```

## 坑 4：Gogs 推送超时

HTTP 和 SSH 推送都会超时/卡住。这是 Gogs 服务端问题，插件配置没问题。需要在 princess 上检查：

- Gogs 容器日志
- 反向代理超时配置
- Git HTTP 后端是否正常

## 坑 5：data.json 不保存

插件在 Obsidian UI 里配置后，`data.json` 不会立刻写盘。需要：

1. 在插件设置里随便改一个选项再改回来
2. 或者关闭/重启 Obsidian

## 快速恢复命令

```bash
cd ~/Documents/obsidian

# 如果 .git 被误删
git init
git remote add origin ssh://git@84.235.240.199:2222/zhensolid/obsidian.git
git config user.name "zhensolid"
git config user.email "zhensolid@vip.qq.com"
git config push.default current
git branch -M master
git pull origin master --allow-unrelated-histories --no-rebase
```

## 验证清单

- [ ] `git remote -v` 只有一个 origin
- [ ] `git branch` 显示 master
- [ ] `git log --oneline` 有提交记录
- [ ] `.obsidian/plugins/obsidian-git/data.json` 存在
- [ ] `autoBackupAfterFileChange` 为 true
- [ ] 编辑一个文件后，Obsidian 状态栏显示 commit 成功