使用 bencher run 的分支 & 起始点

---

一个分支是 git 引用（即分支名称或标签）。 使用 bencher run CLI 子命令时，通过 --branch 选项或 BENCHER_BRANCH 环境变量选择一个分支。 当前的 git 哈希也可以通过 --hash 选项指定。 如果没有指定分支，则在可用的情况下使用当前的 git 分支名称。 否则，使用 main 作为默认分支。 同样，如果没有指定 git 哈希，则在可用的情况下使用当前的 git 哈希。

进行持续基准测试（即在 CI 中进行基准测试）时，您通常希望在已经存在的分支上创建或变基一个分支。 这被称为分支起始点。 起始点是在特定版本（和 git 哈希，如果可用）上的另一个分支。 使用 bencher run CLI 子命令时，可以通过 --start-point 选项选择一个起始点。 此外，使用 --start-point-hash 选项来为起始点指定一个特定的 git 哈希。 从起始点复制过来的数据量由 --start-point-max-versions 选项控制。 同样，阈值 可以通过 --start-point-clone-thresholds 标志从起始点复制过来。 为了防止漂移，使用 --start-point-reset 标志总是将分支重置到起始点。

--branch <BRANCH>

要选择一个分支，设置 --branch 选项或 BENCHER_BRANCH 环境变量为分支的名称、标识或 UUID。 如果指定的值是名称或标识且分支尚不存在，它将为您创建。 但是，如果指定的值是 UUID，则必须事先存在该分支。 如果两者都指定了，则 --branch 选项优先于 BENCHER_BRANCH 环境变量。

如果两者都未指定，Bencher CLI 会尝试查找当前的 git 分支。 它首先在当前工作目录中寻找 git 仓库。 如果不成功，它将继续到其父目录，并一路重试直到根目录。 如果找到 git 仓库，则使用当前的短分支名称。 但是，如果未找到 git 仓库，则使用 main 作为默认分支。

--hash <HASH>

40个字符的 SHA-1 提交哈希值。 如果两个报告具有相同的分支和哈希，他们将被认为是来自同一次提交。 因此，他们将有相同的分支版本号。

如果未提供，Bencher CLI会尝试查找当前的git哈希。 它首先在当前工作目录中寻找git仓库。 如果查找不成功，它会继续在其父目录中查找，并一直重试到根目录。 如果找到了git仓库，那么将会使用当前分支的HEAD git哈希。

--start-point <BRANCH>

使用指定的分支名称、标识或 UUID 作为起始点，用于branch 选项。 对于 GitHub，通常是拉取请求的 base 分支， 对于 GitLab，通常是合并请求的 target 分支。 --start-point 的主要用例是统计连续基准测试。

• 如果指定的起始点是一个空字符串，则忽略此选项。
• 如果 branch 不存在，将使用此起始点创建它。
• 如果 branch 已存在且起始点相同，则忽略此选项。
• 如果 branch 已存在且起始点不同， 将使用此更新的起始点创建一个新的 branch Head。
• 如果 branch 不存在且起始点不存在， 则该 branch 将在没有任何历史数据的情况下被创建。
• 如果 branch 已存在且起始点不存在， 则忽略此选项。

如果使用起始点创建了一个新的 branch， 则将从指定的起始点复制最近的数据和可选的阈值。 有关详细信息，请参阅--start-point-max-versions 选项和--start-point-clone-thresholds 选项。

例如，如果 feature_branch 尚不存在，但 main 存在并具有历史数据。 那么使用 --branch feature_branch --start-point main 将会：

1. 创建一个名为 feature_branch 的新分支
2. 将最近的数据从 main 复制到 feature_branch
3. bencher run 将使用 feature_branch 进行处理

🐰 注意：使用环境变量时，应该将其用双引号包裹（如 --start-point "$MY_BRANCH_ENV_VAR"）， 如果您希望在 MY_BRANCH_ENV_VAR 未定义时不出错地执行 bencher run。

--start-point-hash <HASH>

使用指定的完整 Git 哈希作为branch选项的起始点。此选项需要设置--start-point选项。

• 如果branch不存在，它将从指定哈希的start-point创建。
• 如果branch存在且start-point与指定的哈希相同，则忽略此选项。
• 如果branch存在并且start-point或指定的哈希不同，将从指定哈希的start-point创建新的branch分支头。
• 如果branch不存在且start-point在指定哈希处不存在，则该branch将从start-point的最新版本创建。 如果start-point不存在，则该branch将在没有任何历史数据的情况下创建。
• 如果branch存在且start-point在指定的哈希处不存在，将从start-point的最新版本创建新的branch分支头。 如果start-point不存在，则忽略此选项。

如果通过起始点创建了新的branch，那么来自指定哈希的start-point的所有最新数据和可选的阈值将被复制。有关更多细节，请参见--start-point-max-versions 选项和--start-point-clone-thresholds 选项。

例如，如果存在feature_branch且其起始点是哈希为32aea434d751648726097ed3ac760b57107edd8b的main分支，则使用--branch feature_branch --start-point main --start-point-hash 68b12758509ca5e2b1e3983525625e532eb5f562将会：

1. 移除旧的feature_branch分支头
2. 创建新的feature_branch分支头
3. 将来自main在哈希68b12758509ca5e2b1e3983525625e532eb5f562的所有最新数据复制到新的feature_branch分支头
4. 然后使用新的feature_branch分支头执行bencher run

--start-point-max-versions <COUNT>

使用指定的历史分支版本最大数量，从起始点中为branch选项包含。超出此数量的版本将被省略。默认值是64版本。此选项需要设置--start-point选项。

例如，如果feature_branch的起始点为main分支，并且main有300个版本，那么使用--branch feature_branch --start-point main --start-point-max-versions 100只会在feature_branch中包含main的最近100个版本。

--start-point-clone-thresholds

克隆所有来自起始点的阈值用于branch选项。此标志需要设置 --start-point 选项。

• 如果阈值不存在，则会从start-point 阈值创建。
• 如果阈值存在且与start-point 阈值相同，则该阈值实际上被忽略。
• 如果阈值存在且其模型与start-point 阈值不同，则旧模型将被start-point 阈值模型替换。
• 如果阈值存在且start-point 阈值不存在，则将移除该阈值模型。

例如，如果feature_branch 存在，其起始点为main 分支，并且main 有一个用于内置localhost 测试平台和latency 度量的阈值，那么使用--branch feature_branch --start-point main --start-point-clone-thresholds 将为feature_branch 创建一个新的localhost 测试平台和latency 度量的阈值。

--start-point-reset

重置指定的 branch。 当设置了 --start-point 选项时， branch 将被重置到指定的起始点。 这对于防止统计连续基准测试数据的偏差非常有用。 在未指定起始点的情况下，--start-point-reset 的主要用例是相对连续基准测试。

• 如果 branch 不存在且未指定起始点，将在没有任何历史数据的情况下创建该 branch。
• 如果 branch 存在且未指定起始点， 将在没有任何历史数据的情况下创建一个新的 branch Head。
• 如果 branch 不存在且指定了起始点， 将使用起始点创建该 branch。
• 如果 branch 存在且指定了起始点， 将使用起始点创建一个新的 branch Head。

如果使用起始点创建新的 branch， 则从指定哈希值的 start-point 复制所有最新数据以及可选的阈值。 有关更多详细信息，请参阅--start-point-max-versions 选项和--start-point-clone-thresholds 选项。

使用相同幂等键对同一 branch 的重置共享一个 branch Head， 因此同一次 CI 运行中的并行作业不会相互重置 branch。 在 GitHub Actions 中运行时，该键会自动设置为当前工作流运行的尝试。 同一工作流运行中后续重置 branch 的步骤也会使用该 Head，因此对于需要再次重置 branch 的步骤，请设置不同的键。

例如，如果存在 feature_branch 而没有起始点， 那么使用 --branch feature_branch --start-point-reset 会：

1. 移除旧的 feature_branch Head
2. 创建一个没有历史数据的新 feature_branch Head
3. bencher run 随后将使用新的 feature_branch Head 进行

--start-point-idempotency-key <KEY>

使用指定的键作为 --start-point-reset 标志的幂等键。 该键可以是任意文本。 设置 --start-point-idempotency-key 选项或 BENCHER_START_POINT_IDEMPOTENCY_KEY 环境变量。 如果未设置 --start-point-reset 或该键为空，则忽略此选项。

• 如果没有任何 branch Head 拥有该键，重置将创建一个带有该键的新 branch Head。
• 如果某个 branch Head 已经拥有该键，则使用该 Head，并且不会再次重置 branch， 即使起始点已更改或该 Head 此后已被替换。

在 GitHub Actions 中运行时，该键默认为当前工作流运行的尝试。 同一工作流运行中的所有作业共享一个 branch Head，重新运行工作流会创建一个新的 Head。 同一工作流运行中后续重置 branch 的步骤也会使用该 Head，因此对于需要再次重置 branch 的步骤，请设置不同的键。 对于其他 CI 提供商，请将该键设置为在一次流水线运行的所有作业中都相同的值 (例如：在 GitLab CI/CD 中使用 --start-point-idempotency-key "$CI_PIPELINE_ID")。

例如，如果一个工作流运行由三个作业组成的矩阵，每个作业都使用 --branch feature_branch --start-point main --start-point-reset --start-point-idempotency-key run-abc123， 那么：

1. 第一个报告的作业从 main 创建一个带有幂等键 run-abc123 的新 feature_branch Head
2. 由于该 Head 带有幂等键 run-abc123，其他两个作业使用同一个 feature_branch Head
3. 所有三个作业的结果一起显示在 feature_branch 上

🐰 恭喜！您已经学会了所有关于分支 & 起始点的知识！🎉

继续前进：Testbeds & Specs ➡