edit | blame | history | raw

---
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. 这个插件是做什么的

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. 当前最安全的日常操作

第一步：打开源代码管理

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

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

第二步：逐项判断

对每个文件先判断：

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

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

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

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

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

第四步：填写提交说明

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

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

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

第五步：提交已暂存更改

从命令面板执行：

Git: Commit staged

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

第六步：拉取，再推送

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

如果 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. 多设备使用顺序

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

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

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

9. 出现冲突怎么办

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

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

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

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

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

10. 常见问题

我点了 Commit，但远程没变化

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

Push 提示要登录

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

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

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

删除文件也会被备份吗

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

换主题会影响 Git 吗

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

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

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

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

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

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

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

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

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

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

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

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

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

13. 以后要改配置时

插件设置入口：

Obsidian 设置 → 第三方插件 → Git

配置文件位置：

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

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

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

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

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

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

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

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