拉取请求的文件版本

在自身不保存已查看文件记录的托管方上，这个环境（environment）自己保存这些标记，并向托管方询问每个已标记文件处于哪个版本，这样一次推送才能把已清除的文件报告为有变更。这个版本要穿过四层，条目缺失在每一层的含义都不一样。没有类型区分这些含义，也没有单独一个文件把整条路径写清楚。本页就是为了写清这件事。

这次失败是实际发生过的，不是设想出来的。位于 GitLab 的 getFileRevisions 之上的接口文档，曾经写出和它下面的代码相反的意思，因为它按下一层的含义去描述路径缺失。照那种读法写出来的东西，会把托管方拒绝给出的版本当成变更请求已经删掉的文件，于是在令牌看不到的项目（project）里，读者已经清除的每个文件都会被报告为有变更。

缺失到了提供方边界，含义就变了

在边界之下，补丁解析器或响应解码器里，路径缺失表示这一版并不包含该文件。在边界之上，ProviderFileRevisions 里，路径缺失表示这次读取无法给出答案。提供方（provider）的 getFileRevisions 在向上传递时做转换：托管方看过、却没有版本的路径，到达上层时是空字符串；缺失则留给提供方根本没能看到的那些路径。边界之下的缺失过不了这条边界。

「根本没能看到」具体是哪些情况，由托管方决定，契约一种也无从得知：

• Azure DevOps 从同一份迭代列表里读出每一个版本，所以变更长到没法跟到结尾时，那个点之后的路径就不会出现在结果里。
• Bitbucket 从拉取请求（pull request）自己的补丁里读这些版本，那是它写明文件版本的唯一地方，所以补丁在字节上限处被截断时，切口之后的路径就不会出现在结果里。
• GitLab 是分批去问的，所以它没能读到的那一批，这一批的路径就不会出现在结果里。

这三件事实留在各自的提供方里。契约只规定缺失表示读取无法给出答案，而提供方必须转换成的就是这一层含义。

三种 null，空字符串并不在其中

空字符串是一个答案：托管方看过了，而 head 没有版本。被删除的文件就处于这种状态。它和打上同一值的标记比较时相等，所以对着一次删除记下的标记，会清除一次，并一直保持清除。下面这些都是没有答案，三种形式不能互换。

服务读取整个范围时得到的 null 映射，会让这些标记失去变陈旧的能力。它们仍显示为已清除，但不再察觉推送。提供方完全不提供 getFileRevisions 时会这样；无论走哪条路径，调用失败并已经记入日志时也会这样。一次按下如果没有得到答案，并不会拒绝读者的勾选：存下的标记没有基线，这就是下面的第三种。

已经给出答案的映射里缺了某条路径，这是按路径的情形，而且绝不能把它读成一次删除。HeldFileRevisions 既记录自己问过什么，也记录自己听到什么，所以缺失的路径会保留上一次给出的版本，而不是把版本丢掉。

存在已存储标记上的 null 是第三种，也是这个环境（environment）自己引入的唯一一种。PullRequestFileViewedMark 把 revision 存成可空，这样对某条路径没有得到答案的按下，就可以完全不存基线。如果改成存空字符串，一旦托管方其实有版本，这个文件会立刻被报告为有变更。没有基线的标记会一直被读成已清除，直到读者再次按下。

两种读侧的 null 在写路径上都会收成这第三种：不管映射本身是 null，还是路径只是不在这张映射里，这次按下存下的标记都没有基线。