海角官网git固定一份文档 · 复核同一结论

海角官网git：让下一位读者回到相同的文档状态

简明回答：记录“哪个仓库、哪次提交、哪个文件、哪一节、在什么条件下支持什么结论”。固定提交解决版本漂移，完整路径解决位置漂移，上下文解决解释漂移；三者结合，才能把一条可打开的链接变成可核对的资料依据。

一、区分移动分支、版本标签与固定修订

先设一个教学情境：你在周一从 main 分支读到“先配置 A”，周五把原网址发给同伴，对方却看到“先配置 B”。两人都可能准确描述了各自看到的页面。原因是分支名称指向的提交可以前进，浏览器中的地址没有变，文件状态已经变了。此时应先确认双方各自使用的修订，不能只凭截图争论哪句才是原文。

实际记录时，先打开目标文件，确认正在看的分支或标签，再取得指向该文件具体提交的永久链接。GitHub 的文件永久链接把 URL 中的分支名换成提交标识；在支持快捷键的文件页面可用 y 切换，然后核对地址和文件内容。其他托管平台的操作入口可能不同，判断重点始终是链接是否包含明确修订，而不是按钮是否叫“永久”。

标签名适合沟通版本，例如教学中的 v1.2，但标签引用本身可以被删除或改指。较稳妥的记录写成“查看时标签 v1.2 对应完整提交……”，把人易读的名字和精确定位同时保存。短提交前缀便于展示，却依赖仓库中是否足够唯一；交接时优先保存完整对象标识，不规定所有仓库都只有同一种长度。

固定修订描述的是内容身份，不是访问期限。仓库变为私有、对象不再可取或平台地址失效时，旧链接仍可能打不开。也不能由固定提交推定某仓库具有官方身份。完成这一节的产物是一对记录：当前使用的完整提交，以及当时所见的分支或标签背景。后者解释来源，前者帮助复核。保存完成后再检查链接显示的提交是否与笔记一致，尤其不要把浏览器另一个标签页里的旧版本误当成本次所选版本。

本节参考：GitHub：文件永久链接 · Git：标签操作

二、把文件路径和版本背景一起带走

确定提交后，还要问“依据具体在哪个文件”。只保存仓库地址会把寻找工作留给下一位读者。记录完整仓库标识、区分大小写的文件路径、语言目录和章节标题；必要时附上行范围。行号适合快速定位，但应与固定提交绑定；新增说明可能改变后续行号。GitHub 上引用 Markdown 的特定行，应切到源文件视图选择行范围，渲染页面的章节锚点承担另一种定位作用。

教学情境：旧修订中的文件是 docs/zh/setup.md，新修订把它移到了 guide/installation.md。复核旧结论时，应在旧提交的目录树中寻找旧路径，而不是把新路径机械拼接到旧提交后面。若需要说明迁移，分别列出旧修订与旧路径、新修订与新路径，再查看二者的改动关联；路径相似和标题相同都不能单独证明正文完全一致。

接着补读文档所依赖的条件。它是否要求某个软件版本、某份配置、某个操作系统或先前章节？同一提交可以固定仓库内的一组文件，但文档链接到的外部网站未必同步固定。子模块记录、外部依赖及生成工具也有各自的版本关系。对于只想引用文字的任务，至少写清与结论有关的条件；若要复现运行结果，还需要另行记录环境和依赖。

最后区分源码文档与对外生成页面。你固定了 Markdown 文件，并不自动证明某次公开网页就是由这次提交构建。没有构建关联信息时，引用应写成“该提交中的文档说明”，而不是“当时官网页面显示”。把这条边界写清楚，资料就能支持恰当范围内的结论，也能提示下一位读者还需要查什么。

本节参考：Git：修订与路径参数

三、按固定方向阅读新增、删除与上下文

比较之前，先给两个端点起清晰的角色名：A 是原先引用的提交，B 是准备采用的新提交。普通的 git diff A B 比较两端文件状态，从 A 到 B 显示变化；加上 -- docs/zh/setup.md 可以把阅读范围限定到教学路径。这里的 A、B 和文件名都是需要替换的示意值，命令用于已经有相关对象的本地仓库，不是要求安装或执行项目代码。

看差异时，先读文件名和改动块周围的标题，再读删除与新增。删除行属于 A 侧，新增行属于 B 侧；交换端点，显示方向也会改变。绿色并不代表“正确”，红色也不代表“错误”。例如一句“默认开启”被替换为“需要显式开启”，真正要记录的是启用条件发生变化，而不是笼统写成“文档优化”。

第二轮把变化放回完整段落。某句消失，可能是移到另一节、合并重复说明，也可能是取消了旧条件。只看折叠后的少量行很难区分。展开上下文，查看相邻标题、引用的配置文件和关联说明；遇到重命名则检查两侧实际路径。将“文本发生变化”与“产品行为已变化”分开，后者还需要实现、发布说明或其他直接证据。

第三轮记录未变化但影响解释的前提，例如“仅适用于测试环境”仍留在上一段。三点比较 A...B 通常以合并基点与 B 作比较，不能不加说明地替代两端比较。交接差异时写清端点、方向、路径和比较方式，再用一句话概括“哪条说明在什么条件下改变”。这样即使换一个界面，别人仍能重做同一项阅读。如果两个端点没有显示预期的文件，先确认仓库对象是否齐全、路径是否写对，再解释差异；空白结果不能自动证明所有内容相同。

本节参考：Git：差异比较 · Git：读取对象

git show A:docs/guide.md
git show B:docs/guide.md
git diff A B -- docs/guide.md

四、把引用写完整，再做一次交接复核

引用记录可以分成定位、解释和状态三部分。定位写完整仓库地址、提交标识、文件路径、章节或行范围；解释写你从原文得出的具体结论及适用条件；状态写查看日期、仍待确认的依赖与本次是否能重新打开。日期描述阅读发生的时点，不能替代提交，因为一天内可能有多次改动，也不能据日期推断页面一定对应那次提交。

教学写法可以是：“依据教学仓库中提交 A 的 docs/zh/setup.md『启用条件』节，本示例在设置参数后才启用功能；尚未核对生成网页与该提交的构建关系。”其中仓库、A、路径和功能均为虚构演示，实际引用应换成真实查得的信息。不要填一个看起来逼真的哈希或地址来遮盖缺项，也不要把教程中的示意字段复制成已核实事实。

交给同伴之前，先从自己保存的链接重新打开一次，不借助当前标签页的位置。依次确认完整提交、文件路径和对应原句，再看原句附近是否有会缩小结论范围的条件。若链接跳转到最新分支，不能只因标题相同就算通过；若需要登录或当前无权限，将访问条件写进记录。复核失败应保留原因，以便后来的人判断是地址、权限还是版本对象的问题。

当准备采用新版本时，保留旧引用，将新提交和新结论另列一条，并注明替换原因。这样可以解释历史教程为何与当前说明不同，而不必重写过去的依据。固定文档只是可复现阅读的一部分，不能保证复现程序运行，也不保证长期在线；但一份边界明确、可以逐项检查的引用，已经足够让讨论围绕相同的资料展开。

本节参考：GitHub：片段永久链接 · Git：对象清理

讨论问题：这份文档对哪种情形给出说明？
仓库：从有依据的来源取得的仓库完整地址
完整提交标识：由实际仓库复制，不自行编造
文件路径：例如 docs/guide.md（教学路径）
定位：章节名、关键句与该提交下的行范围
适用背景：语言、软件版本、配置前提
原文与结论：分开写直接说明和自己的推断
访问记录：填写实际阅读日期及仍待核对之处