1 什么是 Git

Git是一个分布式版本控制系统 (DVCS)，用于跟踪文件的修改历史，可以有效、高速地追踪和管理软件开发项目的历史版本，最开始是Linus Torvalds为了帮助管理Linux内核开发而专门开发的一个版本控制软件。

由于Obsidian笔记本质上就是本地保存的Markdown文本文件，这种文本文件和各类软件代码文件本质上是一样的，都是可以直接用记事本打开的那种文件，所以用Git来跟踪和管理Obsidian笔记的历史版本，就显得十分合适。

题外说一句，由于Obsidian笔记是文本文件的这一特性，所有适合代码编辑和管理的工具，其实都可以用来管理和编写Obsidian笔记，比如我比较喜欢用的VS Code，以及最近比较火的Cursor、Claude Code和Gemini CLI等，因此，我们完全可以在Obsidian笔记仓库中体验这些编程领域最火的AI工具。

2 你是否需要Git

虽然可以在Obsidian中使用Git，但是你是否需要这么做。

答案完全取决于你对笔记历史版本保存和管理的需求度。

一般来说，对于记笔记这件事情而言，版本管理和控制不是一个优先级很高的功能，因为相比于一个WORD和PPT的方案文件，笔记文件反复修改的次数在刚开始使用Obsidian时没有那么频繁，即便有一定的保留版本的需要，也完全可以通过复制一个笔记文件来保留旧版本。

而且，Git在设计之初，就是为了给程序员管理代码项目有的，这就使得使用Git对于非计算机相关专业的人来说还是有一点学习成本，需要了解一些命令行的基本知识，也需要了解Git基本的工作原理。

有鉴于此，刚开始使用Obsidian的时候，虽然经常在Obsidian插件库里看到排名前列的Git插件，也看到有教程建议将GitHub作为免费同步方案，我依然没有考虑过使用Git。

不过，随着笔记仓库内容越来越多，尤其是自己手搓的内容越来越多，版本管理的必要性开始体现出来。比如为了让AI在总结提炼新闻报道的时候更好地达到好的效果，我一直在持续优化和改进总结提炼新闻报道的提示词，目前已经从最开始一百字左右的一段话，扩展为现在差不多一千多字的长篇大论了。

在这个改进的过程中，我经常会发现一个调整过的提示词效果还不如原来的，这种时候不免就需要回到之前的版本。于是我开始有意识地保留历史版本文件，结果就造成笔记仓库有了提示词V1、提示词V2、提示词V3、提示词V4A、提示词V4-B等各种不同版本。作为一个强迫症，终于还是觉得笔记的历史版本保存和管理要自动化一点会更清爽，于是最终决定还是用一下Git以及GitHub。

以下为在Obsidian中使用git的一个简单使用教程，关于Git的详细专业介绍请参考官方介绍和相关权威书籍

3 了解Git如何看待文件

Git 将文件状态分为三个区域，如果加上GitHub这个远程仓库，总共可以看作我们有四个管理区域，这是所有操作的基础。

4 如何安装和初步配置

4.1 安装

Windows用户可以在官网直接下载Git，然后双击安装，一路next就好。 https://Git-scm.com/install/windows； Linux用户一般在命令行输入sudo apt install Git即可。

安装完成后，在命令行终端输入（Windows用户推荐使用Windows terminal，可在Windows商店查找安装）git -v回车，能输出类似于git version 2.51.1.windows.1这样一行字就说明安装成功了。

4.2 设置用户名和邮箱

Git会跟踪是谁修改了项目，哪怕参与项目开发的人只有一个。为此，Git需要知道你的用户名和电子邮箱地址。用户名和邮箱都可以随意，如果要是用GitHub的话，最好使用注册GitHub的那个邮箱。

$ git config --global user.name "username" 
$ git config --global user.email "username@example.com"

4.3 设置忽略文件（重要）

在笔记仓库根目录，创建一个名为.gitignore的文件（这个文件名以点号打头）​，并用记事本或其他文本编辑器打开（Obsidian默认不显示点号开头的文件），在其中添加以下内容。

# Obsidian specific files
.obsidian/
*.backup
# Other dot directories
.claude/
.copilot-index/
.smart-env/
.trash/
# Temporary files
*.tmp
*.tmp*
*.temp
*.log
.DS_Store
Thumbs.db
# Local configuration that shouldn't be shared
.local/
config/
# Cache files
.cache/
*.cache
# Node modules if any JS tools are added later
node_modules/
# Python related (if any Python tools are used)
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
env/
venv/
.venv/
# Build outputs if any build tools are added later
dist/
build/
*.min.js
*.min.css
# Other common ignores
.vscode/
.idea/
*.swp
*.swo

# Any local sync or backup files
*.sync
*.bak
# System files
.Spotlight-V100
.Trashes
.gemini/
gha-creds-*.json

以上部分为AI建议

# 以下内容可个性化设置
# Attachment directories
Attachments/
# 敏感信息
项目记录/

添加以上内容后，所有上面写到的文件或文件夹下的文件，都不会被Git追踪，也不会被上传到GitHub。一般建议点号开头的文件和文件夹都写进去。

也可把Obsidian中的附件文件夹写进去，主要是为了减少磁盘和GitHub存储占用，此外也可以把敏感信息如个人信息工作信息等内容也屏蔽掉（如果只是本地使用Git就无所谓，如果是使用GitHub即便是私密仓库，建议也谨慎一点）。

4.4 解决中文乱码

Windows用户如果使用的命令行解释器是PowerShell，有一定可能会碰到乱码问题，这个时候建议按照以下方式进行配置：

1. 解决 PowerShell 乱码：
   • 在PowerShell中输入：notepad $PROFILE
   • 如果弹出记事本但是显示“系统找不到指定的路径”，就输入：if (-not (Test-Path (Split-Path $PROFILE))) { mkdir (Split-Path $PROFILE) }，然后再输入notepad $PROFILE
   • 如果弹出记事本且正常打开一个文件名中包含PowerShell的文件，就在记事本中输入以下三行代码并保存：

$OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding = [System.Text.Encoding]::UTF8

2. 解决 Git 路径八进制乱码：
   • 运行命令禁用Git安全编码：git config --global core.quotepath false
   • 安全性：这个设置是安全的，只影响终端显示。

如果你使用的是Git Bash，似乎不用配置也不会有乱码问题，强烈推荐。 如果你使用的是命令提示符CMD，建议换成PowerShell或Git Bash。 如果配置过程中有什么问题，可以直接截图发给AI，AI在这类问题上还是比较靠谱的。

5 如何使用Git保存文件版本

5.1 仓库初始化

完成以上配置后，终于可以开始折腾Git了。这一阶段还是需要在命令行终端里面操作。 对于Windows用户，如果你在D盘建了一个Obsidian文件夹作为Obsidian笔记仓库，那么可以打开终端，如果使用使用的是PowerShell，输入以下命令进入你的Obsidian笔记仓库：cd "d:\Obsidian"，文件路径建议用加双引号。如果使用的是Git Bash，输入以下命令进入你的Obsidian笔记仓库：cd "/d/Obsidian"，文件路径用加双引号不容易出错。

对于Linux用户，命令行是常规操作，就不再说明了。

进入仓库后，就可以使用Git命令管理仓库，首先来个git init进行初始化。每个仓库只需初始化一次。后续在同一个仓库不再需要使用这个命令。

这个命令会在当前文件夹（也就是你进入的笔记仓库路径"d:\Obsidian"）会生成一个.Git文件夹，你不需要与这个目录打交道，但千万不要删除它，否则将丢失项目的所有历史记录。

5.2 保存仓库历史记录

首先通过Git add .将你当前工作去的笔记保存在暂存区。 然后通过Git commit -m "你的提交消息"将暂存区的记录保存到本地仓库。

三个状态，两个命令。文件版本记录依次从工作区到暂存区再到本地仓库进行存档。

到这一步，所有的历史版本记录都还是保存在本地。

5.3 其他可用命令

查看仓库状态：每次操作完，可以用Git status查看仓库状态，具体可以看到当前工作区是否有修改过或新增的文件需要暂存（stage/add），暂存区是否有已暂存的文件需要提交（commit）；已提交历史记录是否需要推送到远程仓库（push）。

查看提交记录：使用Git log查看保存的提交记录。

实际上，我们可以基于查到的提交记录来在命令行查看和恢复我们想要的历史文件，但是不推荐这样做，因为走到这一步，不考虑使用远程仓库的话，已经可以直接跳到Obsidian Git插件，进行可视化管理了。

6 连接并推送仓库到GitHub

6.1 GitHub SSH密钥生成与认证

Git需要一把进入你GitHub账户的钥匙，这把钥匙可以通过HTTPS链接或SSH链接方式获取。如果通过HTTPS链接方式获取，可以略过本节步骤，直接跳到下一节。

1. 运行以下命令，遇到提示时，一路按 回车 (Enter) 键，使用默认路径和空密码，会在你的本地电脑生成 SSH 密钥对：

ssh-keygen -t ed25519 -C "你的邮箱@example.com"

2. 复制公钥内容：输入以下命令，命令行会输出刚刚生成的SSH密钥对的公钥，复制命令行终端显示的所有内容（从 ssh-ed25519 开始）。

cat ~/.ssh/id_ed25519.pub

3. 登录 GitHub： 进入 Settings → SSH and GPG keys → New SSH key，将复制的公钥粘贴进去并保存。
4. 验证连接：输入以下命令，看到命令行输出 Hi [你的GitHub用户名]! You've successfully authenticated, but GitHub does not provide shell access. 即为成功。

ssh -T Git@Github.com

6.2 在GitHub新建仓库

登录你的GitHub账户，在主页Dashboard左侧新建仓库，输入仓库名，其他可以默认，点击创建仓库。

创建完成后就会弹出这个仓库的HTTPS链接和SSH链接。 如果是SSH链接，一般为git@github.com:[用户名]/[仓库名.git]。 如果是HTTPS链接，一般为https://github.com/[用户名]/[仓库名.git]

6.3 通过SSH首次推送并建立跟踪

1. 设置远程仓库链接

# 确保当前目录在你的笔记库中
git remote add origin git@github.com:用户名/仓库名.git（上一步复制的SSH地址）
# 或者
git remote add origin https://github.com/[用户名]/[仓库名.git]（上一步复制的HTTPS地址）

说明：git remote add 是一个一次性的设置命令，它的作用是在你的本地仓库中，注册一个名为 origin 的远程仓库地址。origin 是远程地址的默认别名，方便后续操作。这个命令只在首次关联时使用。

2. 调整远程仓库链接：后续如果要修改同步的远程仓库，可以运行以下命令

# 确保当前目录在你的笔记库中
git remote set-url origin git@github.com:用户名/仓库名.git 
# 或者
git remote set-url origin https://github.com/[用户名]/[仓库名.git]

3. 首次推送并建立跟踪

git push -u origin HEAD

说明：这是一条“首次关联”的特殊命令。它的作用是：

• 将你本地仓库的所有历史记录，完整地推送到刚刚在 GitHub 上创建的那个空白仓库里。同时用 -u 参数告诉 Git，把你的本地仓库和这个远程仓库“绑定”起来。
• 这个命令只需要在第一次推送时使用一次。完成这次操作后，未来再同步时，只需要使用更简单的 git push 命令就可以了。这里的 HEAD 是一个固定写法，代表“你当前所有的工作”。
• 如果使用HTTPS链接，这一命令输入后，桌面会弹出一个需要你验证的弹窗，点击在浏览器中验证就可以。如果出现未知错误，建议还是使用SSH链接。

7 使用Obsidian Git插件

在确认了Git的基础设置和GitHub的连接之后，建议就可以开始使用Obsidian Git插件进行日常的版本管理操作了。

7.1 配置Obsidian Git插件

插件安装启用后，可以在Obsidian的设置中找到“Obsidian Git”选项进行详细配置。

Automatic：如果不考虑使用GitHub作为Obsidian笔记同步方案，建议不用开启，尤其是在你还有其他同步方案的时候。在对Git进一步熟悉之前，手动进行暂存、提交、推送是一个好的选择。

Commit message：就是命令行中-m后面引号中的一句话。插件默认设置会加上每次提交的时间，但是Git也会自动加时间戳，在message里面再加一个时间感觉有点鸡肋，建议每次提交时手动修改。

Commit-and-sync：建议保持默认，也就是两个选项都选中。

其他的设置建议也不要修改，除非你知道是怎么回事。

7.2 打开源代码管理面板和历史面板

CTR+P打开Obsidian命令面板，输入Git,找到“Open source control view”并点击。然后同样的操作，打开历史面板（open history view）。打开后两个面板默认在右侧，可以手动拉到左侧。

其中，源代码管理面板（source control view）就是使用Obsidian Git的主要界面。

上面一行图标基本就对应了我们前面的一些命令

• 加号➕表示stage all，对应我们之前的命令Git add .；
• 减号➖表示unstage all，就是把暂存的文件给全部取消，对应我们之前未提到的命令Git restore --staged .；
• 对号✅表示commit，对应我们之前的命令Git commit -m "vault backup: {{date}}"，其中，插件会把{{date}}替换为提交时间。建议把vault backup: {{date}}修改为有意义的描述；
• 方形里面向上箭头↑表示push，对应我们之前的命令Git push；
• 方形里面向下箭头↓表示pull，就是把远程仓库最新的修改同步到本地，对应我们之前没有提到的命令Git pull；
• 圆圈里面一个向上箭头↑表示Commit-and-sync，如果上面的配置你没有修改，这个按钮的作用就是“暂存所有修改(staging everything)，然后提交（commit），然后从远程仓库拉取最新的修改并合并到本地，然后再将合并后的本地仓库推送到远程仓库”，简单来说就是一键同步。

7.3 查看修改

• 图中Changes下面的文件名，表示自从上次提交之后，你修改或者新增的文件，点击文件名，还可以看到具体修改的内容。

• 图中Staged Changes，表示自从上次提交之后，你修改并暂存或者新增并暂存的文件，点击文件名，还可以看到具体修改的内容。

• 历史面板下面可以看到仓库初始化Git init以来所有的提交（commit）记录，点击提交记录里面的文件名，可以查看该次提交的文件版本，而且还可以看到该次提交和该次提交之前一次提交的差异。你可以复制这个文件里面你需要的内容。

7.4 恢复文件

Git提供了一些命令将历史版本恢复到当前工作区，但如果不详细了解这些命令的细节，很容易造成当前工作区修改的内容被覆盖掉，反而得不偿失，所以不太建议在Obsidian中使用这些命令。 比如一个应该被禁止使用的命令Git resore .这个命令会用 Staging Area (暂存区 / Index)里面的记录来覆盖你当前工作区，也就是说会把你上次add之后工作区所做的所有修改都给丢弃，而且无法找回，这个命令对应上面截图中的Discard按钮（如下图）。建议不要在Obsidian中使用这个命令和按钮，除非你是专门建了一个仓库用来学习Git玩的。 - 测试

对于恢复历史文件，除了打开历史面板中的对应文件版本然后直接复制你要的内容外，我目前觉得最简单且安全的方式是

==直接打开GitHub，找到你想要的文件，点击历史版本，然后下载这个历史版本。==

8 最后的建议

如果在Obsidian中你之前已经有一套笔记同步方案，比如“Remotely Save+腾讯云COS”，一般不太建议你同时使用GitHub做同步方案（尤其是自动同步），这样做可能也不会发生什么事，但是也有可能也会发生你预料不到的事情，造成不必要的数据损失。

如果同步方案首选“Remotely Save+云存储”或其他类似方案，建议只在电脑端使用Git插件，并且在没必要的情况下尽量不要在GitHub网页上修改文件。理论上虽然只要错开Remotely Save同步和git pull同步的时间，应该就没啥影响，但是谨慎一点总是没错的，毕竟数据是无价的。

兴之所志 2025-10-27