---
title: Obsidian Git 操作手册
tags:
  - Obsidian
  - Git
  - 本机用法备忘
date: 2026-08-31
---

# Obsidian Git 操作手册

> 适用对象：第一次使用 Git 的 Obsidian 用户，以及以后接手维护本机配置的人。  
> 适用 Vault：`/Users/ar/Downloads/Syn/Ob/Ob.temp`  
> 本机核查日期：2026-08-31

## 先看结论

Obsidian Git 已经安装并连接到远程仓库，但**当前不能不检查就直接点“一键提交并同步”**。

原因是当前仓库积累了大量未提交变化，其中包括很多删除项。Git 不会判断这些删除是不是你真正想要的；一旦把它们提交并推送，远程仓库也会记录这些删除。

当前最安全的用法是：

1. 先打开“源代码管理”查看变化。
2. 只暂存自己确认过的文件。
3. 使用“提交已暂存更改”。
4. 拉取远程更新。
5. 确认无冲突后再推送。

在当前积压变化整理完以前，不建议使用“暂存全部”“提交所有更改”“提交并同步”或“丢弃所有更改”。

## 1. 这个插件是做什么的

Obsidian Git 把 Vault 当成一个 Git 仓库，用来：

- 记录笔记在不同时间的版本；
- 查看某个文件改了什么；
- 把本机提交推送到远程服务器；
- 从远程服务器拉取其他设备已经提交的内容；
- 在误改后，从历史版本中找回内容。

它不是实时同步盘，也不是完整的 Vault 备份。本机的 `.gitignore` 排除了附件、Obsidian 配置和若干工具目录，所以这些内容不会随 Git 一起备份。

## 2. 本机当前状态

| 项目 | 当前值 | 说明 |
|---|---|---|
| Obsidian Git 插件 | 2.39.0 | 插件已启用 |
| Vault / 仓库目录 | `/Users/ar/Downloads/Syn/Ob/Ob.temp` | Git 仓库就在 Vault 根目录 |
| 当前分支 | `main` | 日常使用的主分支 |
| 远程名称 | `origin` | Git 默认远程名称 |
| 远程仓库 | `https://git.boborobots.com/r/crazy-macs/obsidianar.git` | 私有 Git 服务 |
| 本机 Git 用户 | `Ariver` | 提交记录中的作者名 |
| 凭据管理 | macOS Keychain | 密码或令牌不写进笔记 |
| 当前提交 | `2febc76` | 本机和本机缓存的 `origin/main` 指向相同提交 |
| 已暂存文件 | 0 | 当前没有准备提交的文件 |
| 冲突文件 | 0 | 当前没有正在解决的合并冲突 |
| 已跟踪但有变化 | 270 个文件 | 包含修改和删除 |
| 未跟踪内容 | 106 个路径，展开约 2732 个文件 | 尚未纳入 Git 的新内容 |

注意：“本机和 `origin/main` 相同”只表示本机上一次取得的远程记录相同。本次核查没有联网 Fetch，不能据此证明服务器此刻没有新提交。

## 3. 先认识六个词

| 名称 | 通俗解释 |
|---|---|
| 修改（Modified） | Git 认识这个文件，但内容变了 |
| 删除（Deleted） | Git 认识这个文件，但本机已经找不到它 |
| 未跟踪（Untracked） | 新文件，Git 还没有开始记录它 |
| 暂存（Stage） | 把选中的变化放进“本次准备提交”的清单 |
| 提交（Commit） | 在本机生成一个可回看的版本节点 |
| 推送（Push） | 把本机已有的提交上传到远程服务器 |

“拉取（Pull）”是把远程的新提交取回本机并合并。“提交”不等于“推送”，只提交而不推送时，版本仍只在这台电脑上。

## 4. 当前最安全的日常操作

### 第一步：打开源代码管理

1. 在 Obsidian 按 `Command + P` 打开命令面板。
2. 输入 `Git: Open source control view`。
3. 执行“Git: Open source control view（打开源代码管理视图）”。

这里会列出修改、删除和未跟踪文件。

### 第二步：逐项判断

对每个文件先判断：

- 这是我刚才有意修改的吗？
- 如果显示删除，我真的打算删除它吗？
- 这是正文笔记，还是缓存、临时文件、自动生成文件？
- 文件名和所在目录是否符合预期？

不确定的项目先不要暂存。尤其是大量删除，必须先确认是整理目录造成的正常移动，还是同步、挂载或文件系统异常。

### 第三步：只暂存已确认文件

在源代码管理视图中，对确定要纳入本次版本的文件点击“Stage / 暂存”。

当前阶段不要点“Stage all / 暂存全部”。暂存只是把文件加入本次提交清单，不会删除文件，也不会上传服务器；如果选错，可以使用“Unstage / 取消暂存”。

### 第四步：填写提交说明

提交说明应写清楚“做了什么”，例如：

- `补充 Obsidian Git 操作手册`
- `整理 8 月项目笔记`
- `修正 TaskNotes 项目页说明`

避免只写“更新”“备份”“改了一下”，否则以后很难从历史中找到需要的版本。

### 第五步：提交已暂存更改

从命令面板执行：

`Git: Commit staged`

这只提交你刚才暂存的内容，不会把其余 270 个变化和大量未跟踪文件一起带进去。

### 第六步：拉取，再推送

1. 执行 `Git: Pull`。
2. 如果没有冲突，再执行 `Git: Push`。
3. 查看通知和状态栏，确认没有错误。

如果 Pull 出现冲突，先停止，不要继续 Push，按“冲突处理”一节操作。

## 5. 这些按钮分别会做什么

| 命令 | 实际作用 | 当前建议 |
|---|---|---|
| Open source control view | 查看变化并选择暂存文件 | 推荐 |
| Stage current file | 暂存当前打开的文件 | 推荐，先确认文件 |
| Unstage current file | 从本次提交清单移除，不删除文件 | 可安全使用 |
| Commit staged | 只提交已经暂存的内容 | 当前最推荐 |
| Pull | 拉取并合并远程提交 | 提交后、推送前使用 |
| Push | 上传本机已有提交 | 确认 Pull 成功后使用 |
| Commit | 根据插件上下文执行提交 | 新手优先使用含义更明确的 Commit staged |
| Commit all changes | 暂存全部变化并提交 | 当前不要使用 |
| Commit-and-sync | 暂存全部、提交、拉取、推送 | 当前不要使用 |
| Stage all | 把所有变化加入下次提交 | 当前不要使用 |
| Discard all changes | 丢弃未提交变化 | 高风险，不要使用 |
| Delete repository | 删除 Git 仓库结构 | 禁止使用，除非明确重建仓库 |

### 什么时候可以使用“Commit-and-sync”

只有同时满足以下条件时才考虑使用：

- 源代码管理列表已经检查过；
- 没有意外的大批删除；
- 没有临时文件或不应提交的隐私内容；
- 当前所有变化都确实属于同一次备份；
- 你理解它会把全部变化暂存、提交，然后 Pull 和 Push。

## 6. 本机自动化设置的真实含义

本机插件当前配置如下：

| 设置 | 当前值 | 实际效果 |
|---|---:|---|
| 自动提交 / 自动备份间隔 | 0 | 自动提交已关闭 |
| 自动推送间隔 | 20 分钟 | 已存在的本机提交可能被自动推送 |
| 启动 Obsidian 时自动拉取 | 开启 | 启动后会尝试从远程拉取 |
| 定时自动拉取 | 0 | 定时拉取关闭 |
| 推送前先拉取 | 开启 | 插件在推送流程中会先 Pull |
| 文件变化后触发自动备份 | 开启 | 但自动提交间隔为 0，因此目前不会自动生成提交 |
| 源代码管理自动刷新 | 开启，约 7 秒 | 文件变化后列表会刷新 |

因此，旧备忘中“笔记一改动就自动 commit”的描述现在已经不成立。当前状态是：插件不会自动替你创建提交，但一个已经创建、尚未推送的本机提交，可能在 20 分钟自动推送周期到来时被上传。

在积压变化整理完成之前，可以在命令面板执行 `Git: Pause/Resume automatic routines` 暂停自动例程。再次执行同一命令即可恢复。暂停前后应查看 Obsidian 通知或 Git 状态栏确认状态。

## 7. 为什么这不是完整备份

当前 `.gitignore` 明确排除了：

- 整个 `.obsidian/`：包括主题、插件、插件配置、CSS snippets；
- `X.Attachment/`：附件目录；
- 图片、音频、视频、PDF、EPUB、字体、Office 文档等二进制文件；
- `.agents/`、`.claude/`、`.copilot/`、`.opencode/`、`.smart-env/`、`.workbuddy/`、`.trash/`；
- `P3.bobo/`；
- macOS 的 `.DS_Store` 等系统文件。

所以 Git 主要保护的是未被忽略的文本笔记。若要完整恢复 Vault，还必须另外备份附件和 `.obsidian` 配置。不要因为远程 Git 可以访问，就停止现有的磁盘、同步盘或系统备份。

## 8. 多设备使用顺序

每次从一台设备切换到另一台设备时，推荐：

1. 离开旧设备前：检查变化 → 分批提交 → Pull → Push。
2. 到新设备后：先 Pull，再开始编辑。
3. 编辑结束后：再次检查 → 提交 → Pull → Push。

不要让两台设备同时长时间编辑同一个文件；这最容易产生冲突。

## 9. 出现冲突怎么办

冲突表示本机和远程修改了同一部分，Git 无法自动决定保留哪一版。

1. 立即停止 Push，也不要点击“Discard all changes”。
2. 先在 Finder 中把冲突笔记复制一份到 Vault 之外，保留原始内容。
3. 在源代码管理或 Diff 视图中查看冲突文件。
4. 文件中可能出现以下标记：

```text
<<<<<<<
本机内容
=======
远程内容
>>>>>>>
```

5. 人工合并需要保留的内容，并删除这些标记行。
6. 保存文件，暂存已解决文件，然后提交。
7. 再执行 Push。

如果不确定哪一版正确，停止操作并请维护者协助；不要用“丢弃全部”碰运气。

## 10. 常见问题

### 我点了 Commit，但远程没变化

Commit 只在本机形成版本；还需要 Push。也可以等待当前 20 分钟自动推送周期，但手动确认后 Push 更可控。

### Push 提示要登录

本机使用 `osxkeychain` 管理 Git 凭据。不要把密码或访问令牌写进笔记、插件提交说明或 Git 仓库。如果钥匙串凭据失效，应在系统钥匙串或 Git 服务端重新配置。

### 为什么附件没有出现在 Git 中

附件及常见二进制格式被 `.gitignore` 排除了，这是当前仓库策略，不是插件故障。

### 删除文件也会被备份吗

会。Git 会把“删除”记录为一次版本变化。历史提交仍可用于找回，但如果删除不是你的本意，就不应把它提交和推送。

### 换主题会影响 Git 吗

通常不会。Git 插件和主题彼此独立；不过 `.obsidian/` 已被忽略，主题及插件配置本身不会由这个仓库备份。

### 如何查看某个文件改了什么

在源代码管理视图选择文件，或从命令面板使用 `Git: Open diff view`。确认差异后再决定是否暂存。

## 11. 只读排查命令（给维护者）

以下命令只用于查看，不会提交、推送或丢弃内容：

```bash
git -C /Users/ar/Downloads/Syn/Ob/Ob.temp status --short
git -C /Users/ar/Downloads/Syn/Ob/Ob.temp diff --stat
git -C /Users/ar/Downloads/Syn/Ob/Ob.temp diff --cached --stat
git -C /Users/ar/Downloads/Syn/Ob/Ob.temp log --oneline -10
git -C /Users/ar/Downloads/Syn/Ob/Ob.temp remote -v
```

查看某个文件的未提交差异：

```bash
git -C /Users/ar/Downloads/Syn/Ob/Ob.temp diff -- "相对于Vault根目录的文件路径"
```

不要在不了解后果时执行 `reset --hard`、`clean -fd`、`checkout --`、`restore` 或强制推送。

## 12. 当前仓库的首次整理建议

这一步只需做一次，但应谨慎：

1. 暂停 Git 自动例程。
2. 按顶层目录查看 270 个修改 / 删除和 106 个未跟踪路径。
3. 先把“明确要保留的新笔记”分批暂存并提交。
4. 对每一批删除确认：是真的删除，还是目录移动、同步遗漏或文件暂时不可见。
5. 检查未跟踪目录中是否有自动生成内容、隐私内容或应该加入 `.gitignore` 的内容。
6. 每批只处理一个主题，提交说明写清楚。
7. 每批提交后 Pull；无冲突再 Push。
8. 源代码管理列表恢复到可理解、可控的状态后，再恢复自动例程。

本手册不会替你判断当前大量删除是否应该保留。那需要结合文件内容和你的整理意图单独审查。

## 13. 以后要改配置时

插件设置入口：

`Obsidian 设置 → 第三方插件 → Git`

配置文件位置：

`/Users/ar/Downloads/Syn/Ob/Ob.temp/.obsidian/plugins/obsidian-git/data.json`

不建议直接编辑 JSON；优先通过 Obsidian 设置界面修改。若必须手工修改，应先退出 Obsidian，并单独备份该文件。

需要特别记录的设置是：自动提交间隔、自动推送间隔、启动时自动拉取、推送前拉取、同步方式。修改后应同步更新本手册的“本机自动化设置”表格。

由于 `.obsidian/` 被 Git 忽略，插件配置不会随这个仓库同步到其他设备，也不会被当前 Git 仓库备份。

## 14. 三个月后接手时先检查什么

维护者不要直接相信本页中的数量和提交号，因为仓库会继续变化。接手时按顺序检查：

1. 插件版本和 `data.json` 自动化设置。
2. 当前分支、远程地址和上游分支。
3. 是否有已暂存、未提交、未跟踪或冲突文件。
4. `.gitignore` 是否仍排除 `.obsidian/` 和附件。
5. 本机提交与远程分支是否有 ahead / behind。
6. 先做只读检查，再决定 Commit、Pull 或 Push。

本页记录的是 2026-08-31 的真实本机快照；功能说明长期有效，状态数字以当时重新检查为准。