先明确目标：我要保留的是“分叉过、又重新合并”的真实历史#

我的项目基于 Firefly 继续修改。

现在我同时维护两个远程。origin 指向我自己的 GitHub 仓库；upstream 指向官方 Firefly 仓库。对我而言，origin/master 代表我的远程版本，而 upstream/master 代表官方的最新版本。

可以用下面的命令查看当前远程仓库配置：

1
git remote -v

这里有一个以前没有认真区分的点：

origin 和 upstream 并不是 Git 的特殊关键字，它们本质上只是远程仓库的名字。

origin 只是 git clone 时 Git 通常默认给源仓库取的名字；而 upstream 是我为了区分“官方上游”而人为添加的名称。

真正让我做选择的是分支已经发生了分叉：

1
                官方继续开发
2
               D──E──F
3
              /
4
A──B──C──────
5
       \
6
        X──Y
7
           ↑
8
        我的修改

我的 master 有自己的提交，官方 upstream/master 也在继续向前。此时我面对的是 merge 和 rebase 两种不同思路。

如果使用：

1
git rebase upstream/master

我的提交会被重新放到官方最新提交之后，历史会变得非常线性：

1
A──B──C──D──E──F──X'──Y'

这种方式很整洁，但它会重写我原来的提交。

而我这次真正想保留的是另一件事：

官方代码和我的个人修改曾经沿着两条路线发展，随后我在某个时间点把它们重新合并到一起。

所以我最终选择：

1
git merge --no-ff upstream/master

我特意保留 --no-ff，因为我希望历史中明确留下一个 Merge Commit，让以后回看 Git Graph 时能直接看到：

• 官方继续开发的轨迹；
• 我的个性化修改轨迹；
• 两条历史重新汇合的位置。

这对我来说，比一条“看起来一直都很整齐”的线性历史更符合实际。

真正值得记录的不是命令，而是三类不同的冲突#

这次合并过程中，Git 自动处理了不少文件，但以下几类冲突需要我自己判断：

1
src/components/layout/Footer.astro
2
src/config/FooterConfig.html
3
src/config/footerConfig.ts
4
src/config/navBarConfig.ts
5
src/config/profileConfig.ts
6
src/config/siteConfig.ts

其中大部分是 CONFLICT (content)，而 footerConfig.ts 是 CONFLICT (modify/delete)。

刚看到 Automatic merge failed 时，很容易下意识把它理解成“合并失败了”。但实际更准确的理解是：

Git 已经完成了能自动完成的部分；剩下这些地方存在多个合理结果，所以必须由开发者自己决定。

因此冲突并不是 Git 出错，而是 Git 在把决策权交回来。

我主要通过 VS Code Merge Editor 来处理这些问题。这里最重要的三个概念是：

• Current：我执行 merge 时所在的 master
• Incoming：正在被合入的 upstream/master
• Result：最终真正会进入 Merge Commit 的结果

这次最重要的认识之一，就是 Result 并不一定等于 Current，也不一定等于 Incoming。

很多真实冲突的正确答案其实是：

保留一部分 Current，吸收一部分 Incoming，再做必要的人工调整。

第一类冲突：个人配置不应该被“官方默认值”覆盖#

siteConfig.ts 和 profileConfig.ts 都属于非常典型的个人配置冲突。

例如 siteConfig.ts 中，官方新版的标题是 title: "Firefly"，而我的版本是 title: "Nightbug Inn"。导航栏标题也类似，官方是 title: "Firefly Blog"，而我的是 title: "Nightbug Inn"。

除此之外，还有：

• site URL
• subtitle
• description
• keywords
• themeColor
• 页面开关
• 文章列表布局
• Bilibili UID
• 站点开始时间

这些内容的本质并不是“官方代码更新了，而我的代码旧了”，而是：

官方默认配置和我的实际站点配置不同。

同理，profileConfig.ts 中官方保留的是官方作者的头像、名称、签名和链接，而我的版本则是自己的资料。

因此这两类文件最后都保留了我的旧配置：

• siteConfig_new.ts == siteConfig_old.ts
• profileConfig_new.ts == profileConfig_old.ts

这里真正重要的判断原则是：

先看这个文件在项目里的职责，再决定哪一侧才是正确来源。

如果这是“个人配置”，那官方版本即使更新得更晚，也并不意味着它更适合我的项目。

第二类冲突：文本能合上，不代表逻辑一定正确#

navBarConfig.ts 让我更直观地体会到了这一点。

我的版本里新增了自己的导航结构，例如：

• 足迹
• 娱乐
• 关于本站

GitHub 链接也改成了自己的仓库，还增加了 Bilibili 等个人链接。

官方新版则保留了自己的 GitHub / Gitee 配置。

这类对象数组在 Merge Editor 里很容易出现一种危险情况：文本块看似合并成功，但对象内部的字段被错误拼接。

当时就出现过类似这样的组合：

1
{
2
    name: "Bilibili",
3
    ...
4
    icon: "fa7-brands:gitee",
5
}

从语法上看，它完全可能是合法的。

从 Git 的角度看，它也可能已经“没有冲突”。

但从逻辑上看，它显然是错误的。

所以这次我真正理解到：

Merge Editor 解决的是文本冲突，不是业务逻辑。

最终 navBarConfig_new.ts == navBarConfig_old.ts，因为我希望继续保留自己的导航结构。但更重要的是，我开始意识到：任何人工合并后的对象、数组、配置文件，都必须再做一次逻辑检查。

最关键的案例：Footer 不是“选哪一边”，而是一次真正的架构迁移#

这次最值得记录的其实不是前面的配置冲突，而是 Footer。

它同时涉及：

• FooterConfig.html
• Footer.astro
• footerConfig.ts

这三者一起看，才能理解官方这次到底改了什么。

1
<!--
2
    你可以在这个文件中使用HTML内容自定义网站底部的footer
3
    You can use html to customize the footer at the bottom of the website in this file.
4
-->

1
import { footerConfig, profileConfig } from "@/config";

1
if (footerConfig.enable) {
2
    ...
3
}

1
footerConfig.ts
2
      ↓
3
enable
4
      ↓
5
Footer.astro
6
      ↓
7
FooterConfig.html

1
import { profileConfig } from "@/config";

1
Footer.astro
2
      ↓
3
直接读取
4
      ↓
5
FooterConfig.html

1
customFooterHtml = customFooterHtml.replace(
2
    /__THEME_VERSION__/g,
3
    themeVersion,
4
);

modify/delete 冲突真正考验的是“是否理解重构意图”#

footerConfig.ts 的冲突类型是 CONFLICT (modify/delete)。

我的旧版还在修改它，官方新版则已经把整个文件删除。

Git 无法自动判断：

到底应该保留我的修改，还是接受官方删除？

一开始如果只从“我改过，所以不能丢”的角度出发，很容易选择保留。

但结合前面对 Footer.astro 的分析，我已经确认：

• 官方确实重构了 Footer；
• footerConfig.enable 已经没有存在必要；
• 我的真实功能已经迁移到新架构；
• FooterConfig.html 仍然继续使用；
• 版本号注入逻辑也已经保留下来。

这时删除 footerConfig.ts 才是合理的。

我执行：

1
git rm src/config/footerConfig.ts

这里的 git rm 不只是“删除文件”，在当前 merge 状态里，它同时意味着：

我选择“删除”作为这个 modify/delete 冲突的最终结果。

这让我第一次真正理解：冲突处理不是“保护自己改过的东西”，而是判断 哪些设计还应该继续存在。

我最后形成了一套自己的冲突判断方法#

这次合并之后，我觉得真正有价值的不是记住“哪个按钮怎么点”，而是形成了一套更稳定的判断方式。

这次使用到的工作流，其实可以压缩成很少几步#

虽然这篇文章讨论了很多细节，但真正的上游同步流程其实很短。

先确认自己在正确分支：

1
git switch master

获取官方最新历史：

1
git fetch upstream

开始合并：

1
git merge --no-ff upstream/master

发生冲突后，用：

1
git status

确认当前状态，逐个处理文件。

普通冲突解决后：

1
git add <file>

如果最终决定删除：

1
git rm <file>

如果方向完全错了，可以在提交 Merge Commit 之前：

1
git merge --abort

全部解决后，提交并推送：

1
git commit
2
git push origin master

这部分命令本身其实不难。

真正难的是中间那一步：

理解冲突背后的代码意图。

合并结束后，我才真正体会到 Git 历史的价值#

这次 Merge Commit 是 dcaed5bc。

它有两个 parent：

• dcaed5bc^1：我 merge 前的 master
• dcaed5bc^2：这次被合入的 upstream/master

也就是说，对于这次合并，我可以随时回到三个明确状态：

• old：我的旧版
• upstream：官方新版
• new：最终合并版

这也是为什么后来即使我已经把工作区更新成最终版，仍然能把旧文件重新找出来。

例如查看我的旧版 Footer：

1
git show dcaed5bc^1:src/components/layout/Footer.astro

查看官方当时的 Footer：

1
git show dcaed5bc^2:src/components/layout/Footer.astro

查看最终版：

1
git show dcaed5bc:src/components/layout/Footer.astro

这件事让我真正意识到：

Git 保存的不是“当前文件”，而是整个项目在不同提交节点上的历史快照。

worktree 让我把这段历史真正“摊开”来看#

为了更方便地做 old / upstream / new 三方对比，我没有把主工作区来回切换到旧提交，而是用了 git worktree。

例如创建 merge 前的个人版本：

1
git worktree add ../Firefly-before-merge dcaed5bc^1

创建官方当时的版本：

1
git worktree add ../Firefly-upstream dcaed5bc^2

这样我同时拥有：

1
Desktop
2
│
3
├── Firefly
4
│   └── 最终 merge 后版本
5
│
6
├── Firefly-before-merge
7
│   └── 我的 merge 前版本
8
│
9
└── Firefly-upstream
10
    └── 官方 merge 前版本

这三个目录非常适合复盘：

• Firefly-before-merge：Current
• Firefly-upstream：Incoming
• Firefly：Result

而且主工作区完全不需要切换。

这两个历史 worktree 通常处于 detached HEAD，因为它们直接检出的是具体 commit，而不是分支。

对我这次“只看历史、不继续开发”的用途来说，这正合适。

使用完后可以先检查：

1
git worktree list

再确认两个历史 worktree 是否干净：

1
git -C ../Firefly-before-merge status
2
git -C ../Firefly-upstream status

确认没有需要保留的改动后：

1
git worktree remove ../Firefly-before-merge
2
git worktree remove ../Firefly-upstream

如果曾经直接手动删掉目录，还可以：

1
git worktree prune

清理残留登记。

值得注意的是，删除 worktree 并不会删除那些历史 commit。

worktree 只是“为某个历史节点临时打开一个额外工作目录”。

这次合并之后，我对 Git 的理解发生了什么变化#

以前我对 Git 的理解更接近：

修改文件 → git add → git commit → git push

现在我开始把它理解成：

一套用于描述代码历史关系的数据结构和工具。

这次我第一次把很多以前零散知道的概念真正串起来：

• 分支为什么只是指向 commit 的引用；
• fetch 为什么不会修改工作区；
• merge 为什么能保留真实分叉历史；
• rebase 为什么会改变 commit hash；
• Merge Commit 为什么有多个 parent；
• ^1、^2 为什么能回到不同父提交；
• 为什么被删掉的旧文件还能重新取回；
• 为什么 worktree 能同时看到多个历史版本；
• 为什么 Git 说“冲突解决了”，也不代表程序逻辑一定正确。

这些东西一旦连起来以后，Git 就不再是一堆要背的命令。

它开始变成一套可以推理的系统。

这次实践涉及的 Git 知识完整总结#

下面把这次实际使用到的知识集中整理一次。

这部分也是我以后再次同步 upstream 时，最希望自己能回来查阅的内容。

1
HEAD
2
↓
3
master
4
↓
5
某个 commit

1
origin
2
= 我的 GitHub 仓库
3

4
upstream
5
= 官方 GitHub 仓库

1
git remote -v

1
git fetch upstream

1
git fetch upstream

1
下载远程对象
2
+
3
更新远程跟踪引用

1
git pull

1
fetch
2
+
3
merge/rebase

1
git fetch upstream
2
git merge --no-ff upstream/master

1
A──B──C

1
A──B──C──D──E

1
A──B──C──X──Y

1
        D──E
2
       /
3
A──B──C
4
       \
5
        X──Y

1
共同祖先
2
Current
3
Incoming

1
A──B──C   master
2
       \
3
        D──E   upstream/master

1
git merge --no-ff ...

1
git switch master
2
git merge upstream/master

1
Current = master
2
Incoming = upstream/master

1
Current = 我的
2
Incoming = 官方

1
Current
2
= 当前 checkout 的分支
3

4
Incoming
5
= 被 merge 进来的那一侧

1
完全等于 Current
2
完全等于 Incoming
3
或者完全不同于两者

1
<<<<<<< HEAD
2
Current
3
=======
4
Incoming
5
>>>>>>> upstream/master

1
A：修改
2
B：删除

1
保留修改后的文件
2
还是
3
接受删除

1
git add file

1
git rm file

1
git status

1
方向错了
2
冲突太复杂
3
想重新开始

1
git merge --abort

1
A──B──C
2
    \   \
3
     X───M

1
C
2
X

1
git switch master
2
git merge upstream/master

1
M^1
2
= merge 前的 master
3

4
M^2
5
= upstream/master

1
git log --graph --oneline --decorate -10

1
HEAD
2
master
3
origin/master
4
upstream/master

1
git show dcaed5bc
2
git diff dcaed5bc^1 dcaed5bc
3
git worktree add ...

1
git show <commit>:<path>

1
只存在于工作区
2
从未 commit

1
主目录检出 master
2
另一个目录检出旧 commit
3
再一个目录检出官方 commit

1
git switch -c new-branch

1
git worktree list

1
git worktree remove <path>

1
git worktree prune

1
git push origin master

1
git push --force-with-lease

1
构建
2
测试
3
预览
4
功能检查

以后同步 upstream，我准备使用的标准流程#

以后官方继续更新，我会先：

1
git switch master
2
git status

确认：

• 在正确分支；
• 工作区没有不希望混入 merge 的未提交内容。

然后：

1
git fetch upstream

查看历史：

1
git log --graph --oneline --decorate --all -20

确认确实需要合并后：

1
git merge --no-ff upstream/master

如果发生冲突：

1
git status

逐个处理。

普通文件：

1
git add <file>

接受删除：

1
git rm <file>

如果想放弃这次 merge：

1
git merge --abort

全部完成后：

1
git status

确认没有 unmerged paths，然后：

1
git commit

最后：

1
git push origin master

如果需要检查最终历史：

1
git log --graph --oneline --decorate -20

这次实践让我对 Git 的理解发生了什么变化#

以前我对 Git 的理解更接近 修改文件 → git add → git commit → git push。现在，我开始把 Git 理解成：

一套用于描述代码历史关系的数据结构和工具

分支不是“复制出来的文件夹”；

远程不是“云端文件夹”；

merge 也不是“把两个文件夹覆盖到一起”。

它们实际在操作的是：

1
commit
2
parent
3
reference
4
history graph

真正理解这些以后，很多 Git 命令突然就不再需要死记。

例如：

为什么 fetch 不改工作区？

因为它主要更新远程对象和 remote-tracking refs。

为什么 rebase 会变 commit hash？

因为它创建了拥有不同 parent 的新 commit。

为什么 merge commit 有 ^1 和 ^2？

因为它真的有两个 parent。

为什么已经被删掉的文件还能找回来？

因为旧 commit 的 tree 仍然记录着那个文件。

为什么 worktree 可以同时看到三个版本？

因为一个 Git repository 可以拥有多个工作目录，每个工作目录检出不同引用。

这些东西第一次真正连接在了一起。

结语#

这次我原本只是想做一件很简单的事：

把 Firefly 官方的新更新同步到自己的版本里。

最后却变成了一次非常完整的 Git 实战。

我经历了：

1
确认 origin / upstream
2
↓
3
fetch 官方历史
4
↓
5
观察分支分叉
6
↓
7
选择 merge 而非 rebase
8
↓
9
使用 --no-ff 保留 Merge Commit
10
↓
11
处理 content conflict
12
↓
13
处理 modify/delete conflict
14
↓
15
理解 Current / Incoming / Result
16
↓
17
判断配置冲突与架构冲突
18
↓
19
手工完成真正的三方合并
20
↓
21
commit
22
↓
23
push
24
↓
25
用 Git Graph 验证历史
26
↓
27
理解 Merge Commit parent
28
↓
29
用 worktree 恢复三个历史版本
30
↓
31
重新复盘 old / upstream / new

最重要的收获不是我记住了多少条命令。

而是我开始理解：

Git 的真正价值不是让我“能把代码上传到 GitHub”，而是让我可以明确地回答：代码是怎样一步一步变成今天这个样子的。

这次我特意没有把官方线和个人线通过 rebase 压成一条“看起来一直都很整齐”的历史。

我希望真实保留：

1
这里，我从官方版本分叉；
2
这里，我加入了自己的修改；
3
这里，官方继续向前更新；
4
这里，两套修改发生冲突；
5
这里，我理解两边代码后做出了自己的选择；
6
这里，它们重新合并。

对一个正在开始系统使用 Git 管理真实项目的人来说，我觉得这段历史本身就值得留下。

而下一次再看到 CONFLICT 时，我大概不会再把它理解成“Git 出问题了”。

它更像是在问我：

两个方向都发生了变化，你希望项目接下来长成什么样？

这可能才是版本管理真正开始变得有意思的地方。