1. 前言
在踩了无数的坑后，我终于理清楚了 Obsidian + Git 软件 + Obsidian Git 插件 + GitHub 的一整条同步链路了。这个方案目前来说是除去移动端外最稳定的同步方案（目前我自己没有在移动端使用 Obsidian 的需求，之后会去琢磨一下）。这个方案，要比先前用的 FreeFileSync + iCloud 的方案更稳定，也更好迁移，而且为之后的移动端同步提供了可能性。
（由于后续数据会托管至 GitHub 中，尽管 Private 仓库对外是不可见的，但毕竟还是托管到第三方平台，所以还是尽量不要存很关键很隐私的内容）
下面介绍这套同步流程的设置方式。
2. Git 软件的设置
2.1. 下载 Git
前往官网下载 Git 并安装，本节只说明关键设置项，安装过程可保持默认配置。Windows 用户安装 Git 时，如果不确定选项含义，可以一路使用默认选项。安装完成后会有 Git Bash。
首次使用 Git，需要配置用户名和邮箱：
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
查看配置是否成功：
git config --global --list
这里的邮箱建议和 GitHub 账号邮箱保持一致，后续提交记录会更清楚。
2.2 设置 Git 仓库初始化的默认分支名称
由于现在 GitHub 默认的主分支为 main。为了后续和其它平台对接时更方便（其实是随大流，养成大家公认的习惯，以后遇到问题也好搜索），建议将 Git 仓库初始化时的默认分支名称设置为main。
Git 本身支持通过 init.defaultBranch 配置新仓库初始化时的默认分支名。
打开 Git 的终端，先查看当前的默认分支：
git config --global --get init.defaultBranch
如果没有任何输出，这不是报错，只是说明没有设置过创建分支时的默认分支名。
这时输入下面命令，将默认的分支名设为main：
git config --global init.defaultBranch main
查看是否设置成功：
git config --global --get init.defaultBranch
如果输出：
main
说明已经设置成功了。
3. GitHub 注册、仓库创建和 SSH 配置
3.1. 注册 GitHub 账号
GitHub 账号注册过程较简单，按照页面提示完成邮箱验证即可。注册完成后，继续进行仓库创建。
3.2. 创建 GitHub 仓库
切换到个人的 GitHub 仓库界面，点击右上角的 New，在新的页面中填写仓库名称。
但是这里有一点需要注意，仓库一定要设置为private，除非你想让全世界的人都看到你的 Obsidian 仓库里的文件。
还有就是一定不要在仓库中创建任何文件，保持这个仓库为空，否则后面又要处理文件冲突的事情。
3.3. 设置 SSH 密钥
SSH 密钥相当于一个口令，设置好口令后，两端口令一致即可互相访问，
先检查本机是否已有 SSH Key：
ls ~/.ssh
如果看到类似：
id_ed25519
id_ed25519.pub
说明已有 SSH Key。
如果没有，就生成一个：
ssh-keygen -t ed25519 -C "你的GitHub邮箱"
GitHub 官方文档也推荐使用 ssh-keygen -t ed25519 -C "your_email@example.com" 生成新 SSH Key。
一路回车即可。
然后查看公钥：
cat ~/.ssh/id_ed25519.pub
复制输出的完整内容。
注意复制的是 .pub 公钥，不是私钥。
私钥是你电脑的钥匙，公钥才是交给 GitHub 的门牌号，别反了。
进入 GitHub：
头像 → Settings → SSH and GPG keys → New SSH key
粘贴公钥。GitHub 文档说明，需要在 SSH and GPG keys 中新增 SSH key，并把 public key 粘贴进去。
测试 SSH 是否连通：
ssh -T git@github.com
如果看到类似：
Hi 用户名! You've successfully authenticated...
说明 SSH 配置成功。
4. Obsidian 仓库的设置
4.1. 新建本地的 Obsidian 仓库
打开 Obsidian 软件，按提示进行创建即可。
4.2. 设置 Git 提交中需要忽略的内容
在你的 Obsidian 仓库根目录下创建一个文件：
.gitignore
注意：文件名就是 .gitignore，前面有点，后面没有 .txt。
推荐内容如下：
# Obsidian 本地工作区状态
.obsidian/workspace.json
.obsidian/workspace-mobile.json
# Obsidian 缓存
.obsidian/cache/
# 系统文件
.DS_Store
Thumbs.db
desktop.ini
# 临时文件
*.tmp
*.temp
# Obsidian 回收站
.trash/
不建议直接忽略整个 .obsidian/ 文件夹。
原因很简单：
.obsidian/ 里面有主题、插件配置、快捷键等内容。如果你是自己多设备同步，可以保留大部分配置；如果你直接忽略整个 .obsidian/，换设备后 Obsidian 配置就丢了。
如果文件已经被 Git 追踪，后来再写入 .gitignore 不会自动取消追踪，需要执行 git rm --cached。
4.3. 安装 Obsidian Git 插件
你可能在别的教程中看到让你下载名为Obsidian-git的插件，但是在插件市场搜不到。现在 Obsidian 中的 Git 插件名字就叫Git。在 Obsidian 设置中的第三方插件中关闭安全模式，然后在插件市场下载即可。如果不放心，可以去 GitHub 中下载插件然后手动安装。插件地址为：
Vinzent03/obsidian-git（GitHub 仓库的名称还是没变）。
4.4. 初始化仓库
方法一：Git 原生操作方法
进入你的 Obsidian 仓库目录，例如你的 Obsidian 仓库在：
D:\Obsidian\MyVault
Git Bash 中输入：
cd /d/Obsidian/MyVault
然后初始化 Git 仓库：
git init
查看状态：
git status
如果你看到很多未跟踪文件，说明 Git 已经开始识别这个 Obsidian 仓库了。
此时目录里会出现一个隐藏文件夹：
.git
这个文件夹是和这个仓库同步相关的配置文件，不要手动删，不要手动改。
方法二：Obsidian 插件操作方法
按住Ctrl + P，唤起命令行，然后输入
git:initialize a new repo没有报错即初始化成功。
4.5. 创建一次本地提交 commit
创建测试文件（可省略）
首先我们在 Obsidian 里新建一个测试文件：
同步测试.md
内容随便写，例如：
# 同步测试这是我的第一条 Obsidian Git 同步测试。
方法一：Git 原生操作方法
回到 Git Bash，查看状态：
git status
你应该能看到这个文件处于未跟踪状态。
然后我们把文件加入暂存区：
git add .
然后提交：
git commit -m "Initial commit"
查看提交记录：
git log --oneline
如果能看到一条提交记录，说明本地 commit 成功。
方法二：Obsidian 插件操作方法
在左边的功能栏点击，可以看到右侧侧边栏有此插件的操作区，点击上方的对勾，即可完成一次 commit。
注意：当完成第一次 commit 后，我们的 main 分支才正式创建。
4.6. 设置目标远程仓库和分支
方法一：Git 原生操作方法
在 GitHub 仓库页面，复制 SSH 地址，格式一般是：
git@github.com:你的用户名/仓库名.git
GitHub 文档说明，添加远程仓库使用 git remote add，通常远程名使用 origin。
在本地 Obsidian 仓库目录中执行：
git remote add origin git@github.com:你的用户名/仓库名.git
例如：
git remote add origin git@github.com:HyperionCHI/obsidian-vault.git
检查是否添加成功：
git remote -v
你应该看到类似：
origin git@github.com:HyperionCHI/obsidian-vault.git (fetch)origin git@github.com:HyperionCHI/obsidian-vault.git (push)
如果提示：
remote origin already exists
说明之前已经添加过 origin。可以改成：
git remote set-url origin git@github.com:你的用户名/仓库名.git
GitHub 文档也说明，可以通过 git remote set-url 修改远程地址。
方法二：Obsidian 插件操作方法
按住Ctrl + P，唤起命令行，然后输入
git: Edit remote当要求输入select or create a new remote by typing its name or selecting it时，输入origin，然后回车。这个origin的意思是给远程仓库在本地起一个别名。这里建议还是使用 origin 以遵守大家都使用的惯例。在这种事情上，越是遵守惯例，后续遇到问题时越好在网上找到答案。
当要求输入Enter remote URL时，输入远程仓库的 SSH 链接。
4.7. 第一次推送至远程服务器
方法一：Git 原生操作方法
先确认当前分支名：
git branch --show-current
如果输出不是 main，改成 main：
git branch -M main
第一次推送时，必须设置 upstream：
git push -u origin main
或者写完整一点：
git push --set-upstream origin main
Git 官方文档中也使用 git push --set-upstream origin main 来把本地 main 分支推送并关联到远程。这一步非常关键。
方法二：Obsidian 插件操作方法
在右侧 Git 插件的工作区中，点击右上角的 push 按钮（一个向上的箭头，下面有个没封口的框）
当要求输入时，选择刚才的 origiin
当要求输入select or create a new remote branch by typing its name or selecting it时，我们输入main。因为我们远程是没有分支的，这里我们为远程仓库创建一个叫 main 的分支的。然后按下回车即可。
如果没有报错，那我们回到 GitHub 刷新一下仓库，即可看到我们的提交了。
4.8. 后续的同步方法
后续需要同步时，只需在 Git 插件的工作区，先点击 “对勾” 进行 commit，然后再点击 Push 按钮即可完成上传；
点击向下的箭头 ——Pull 按钮即可拉取远端内容。
5. 进一步对 Obsidian Git 插件进行设置
设置 Auto commit-and-sync interval (minutes)，即自动保存时间。
打开 Pull On Startup，以保证每次打开 Obsidian 时都可以进行同步；
6. 第二台电脑的同步方式
第二台电脑不要重新 git init。
第二台电脑不要重新创建 GitHub 仓库。
第二台电脑应该 git clone 已有仓库，然后用 Obsidian 打开 clone 下来的文件夹。
在另一台需要同步的电脑上，按照上面的步骤，创建 SSH KEY，然后将这个 KEY 添加到 GitHub 中，然后将我们在 GitHub 中仓库的 SSH 地址复制下来。
同样的，在这台电脑上，我们需要安装 Git、Obsidian 这两款基础软件。
安装完成后，在存放仓库的地方，单击鼠标右键，选择Open Git Bash Here，然后在弹出的终端中输入：
git clone [复制下来的 SSH 格式的仓库地址]仓库克隆完成后，在 Obsidian 中打开这个仓库即可。
第二台电脑开始写之前先 pull，否则会出现文件冲突的情况！
如果 Git 配置的没有问题，那么应该是可以直接进行 commit 和 push 的。
7. 一些概念解释
origin 是远程仓库的本地别名，不是分支名。 main 是分支名，不是远程仓库名。
正确关系是：
本地分支 main → 远程仓库 origin → 远程分支 origin / main
不要把 remote 命名为 main，也不要把 branch 命名为 origin。
如果对您有所帮助，欢迎添加本站到收藏夹，也欢迎微信搜索公众号 半山数字札记 ，我会持续更新新的内容。
如果你也在做个人项目、优化工作流，或者只是想找一群折腾工具和内容的人交流，可以添加我的微信，备注「半山」，我会邀请你进群，欢迎一起探讨，一起交流。
