如何理解 git format-patch 手册中的 "<since>"？

Question

我正在阅读 git format-patch 的 man 页面：

有两种方法来指定要操作的提交。

1. 一个单独的提交、<since>，指定将导致输出的提交领先于当前分支末端的提交历史中不包含在 <since> 历史中的提交。

......

我对 "commits ... that are not in the history that leads to the <since> to be output." 的理解感到困惑。我认为应该是 "...that are not in the history ..."。

- Nan Xiao

---

但是这样做会不会包括在该提交之前的所有历史记录呢？为了更清晰地表达，那个句子的措辞可能会有所不同，但我理解的方式是，任何作为<since>的前置提交都不会包含在历史记录中，因此"not"是该句子的一部分是正确的。 - Lasse V. Karlsen

Answer 1

这个表述可能有些困惑，因为英语解析很棘手，但这就是它的意思：

一个单一的提交，“<since>”，指定以下内容： 1. 领先于当前分支端点的提交； 2. 这些提交不在导致“<since>”的历史记录中。

换句更易懂的话说，可以从绘图开始：

______________________________

...--o--o--<since>--o--o--o--o   <-- currentbranch (HEAD)
__________________

我标号为2的部分，是导致<since>的历史记录，下划线部分表示。 我标号为1的部分，是指向当前分支末端的提交，上划线部分表示。 整个表达式的含义是“上划线集合减去下划线集合”，这将留下从除了<since>之后的提交，直到并包括HEAD。

这也是当你编写以下命令时，git rev-list（因此也包括git log）的意思：

<since>..HEAD

请注意，如果历史记录有分支，则结果可能会有些令人惊讶：

...--o--o--*--*--*--*---*   <-- currentbranch (HEAD)
         \             /
          o--<since>--*

在这种情况下，由<since>..currentbranch包含的提交是那些标记为*的提交。这不仅适用于git format-patch，而且适用于所有基于提交图的操作，当您使用拼写为<since>..currentbranch或<since>..HEAD或<since>..这三个语法时（它们都表示同一件事）。

（可能令人困惑的是，git diff不执行基于提交图的操作，因此如果您尝试基于git diff的行为来理解，您将看不到此效果。大多数人经常使用的一个命令是git log本身，但由于默认情况下git log不会绘制图形，因此不知道发生了什么。要使其明显，请从DOG获得帮助：git log --decorate --oneline --graph <since>..HEAD。日志或者说棒子总是更有趣与装饰在线图形（DOG）一起！ :-)

- torek