使用 bencher run 进行分支选择

一个分支是 git 引用（即分支名或标签）。 当使用 bencher run 命令行子命令时， 可以使用 --branch 选项或 BENCHER_BRANCH 环境变量来选择一个分支。 默认情况下所有项目都从 main 分支开始， 如果没有指定，默认使用 main。

当持续基准测试（即在 CI 中进行基准测试）时， 你通常需要在一个已经存在的分支上创建或重置一个 branch。 这被称为分支起始点。 起始点是一个特定版本（如果有的话，还包括 git 哈希值）的另一个分支。 当使用 bencher run 命令行子命令时， 可以使用 --branch-start-point 选项来选择一个起始点。 此外，使用 --branch-start-point-hash 选项来指定起始点的特定 git 哈希值。 所有的数据和阈值都会从起始点复制过来。 为了防止漂移，可以使用 --branch-reset 标志总是将分支重置为起始点。

--branch <BRANCH>

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

如果没有指定，Bencher CLI 会尝试查找当前的 git 分支。 它首先在当前工作目录中寻找一个 git 仓库。 如果没有成功，它会继续到父目录并一直重试到根目录。 如果找到了一个 git 仓库，那么就会使用当前的简短分支名。 然而，如果没有找到 git 仓库，那么 main 会被用作默认分支。

--branch-start-point <BRANCH>

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

• 如果指定的起始点是空字符串，则忽略此选项。
• 如果 branch 不存在，将使用此起始点创建它。
• 如果 branch 存在且起始点相同，则忽略此选项。
• 如果 branch 存在且起始点不同， 旧版本的 branch 将被重命名和归档， 并将使用更新的起始点创建新的 branch。
• 如果 branch 不存在且起始点也不存在， 则 branch 将没有任何历史数据地被创建。
• 如果 branch 存在且起始点不存在， 则忽略此选项。

如果创建了一个带有起始点的新 branch， 则从指定的起始点复制所有数据和阈值。

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

1. 创建一个名为 feature_branch 的新分支
2. 将 main 的所有数据和阈值复制到 feature_branch
3. bencher run 将使用 feature_branch 继续

🐰 注意：每当使用环境变量时，它们应被双引号包裹（即 --branch-start-point "$MY_BRANCH_ENV_VAR"）， 如果你希望 bencher run 在 MY_BRANCH_ENV_VAR 未定义时不报错。

--branch-start-point-hash <HASH>

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

• 如果branch不存在，它将从指定的哈希的branch-start-point创建。
• 如果branch存在并且branch-start-point和指定的哈希相同，那么此选项将被忽略。
• 如果branch已存在并且branch-start-point或指定的哈希不同，旧版本的branch将被重命名和存档，新branch将从指定的哈希的branch-start-point创建。
• 如果branch不存在并且branch-start-point在指定的哈希不存在，那么branch将在没有任何历史数据的情况下创建。
• 如果branch存在并且branch-start-point在指定的哈希不存在，那么此选项将被忽略。

如果用起点创建新的branch，那么在指定哈希的branch-start-point的所有数据和阈值都将被复制。

例如，如果feature_branch的起点是哈希32aea434d751648726097ed3ac760b57107edd8b的main分支， 那么使用--branch feature_branch --branch-start-point main --branch-start-point-hash 68b12758509ca5e2b1e3983525625e532eb5f562将会：

1. 将旧的feature_branch重命名为feature_branch@archive-suffix并存档
2. 创建一个名为feature_branch的新分支
3. 将哈希68b12758509ca5e2b1e3983525625e532eb5f562的main分支的所有数据和阈值复制到新的feature_branch
4. 使用新的feature_branch运行bencher run

--branch-reset

重置指定的 branch。当设置了 --branch-start-point 选项时，branch 将被重置到指定的起点。这对于防止 Statistical Continuous Benchmarking 数据漂移非常有用。未指定起点时使用 --branch-reset 的主要用例是 Relative Continuous Benchmarking。

• 如果 branch 不存在且未指定起点，将创建无任何历史数据的 branch。
• 如果 branch 存在且未指定起点，旧版本的 branch 将被重命名和归档，并创建一个无任何历史数据的新 branch。
• 如果 branch 不存在且指定了起点，将使用起点创建 branch。
• 如果 branch 存在且指定了起点，旧版本的 branch 将被重命名和归档，并使用起点创建新的 branch。

若使用起点创建了新的 branch，则会复制指定起点的所有数据和阈值。否则，将创建无任何历史数据的 branch。

例如，如果 feature_branch 存在且无指定起点，则使用 --branch feature_branch --branch-reset 会：

1. 将旧的 feature_branch 重命名为 feature_branch@archive-suffix 并归档
2. 创建一个名为 feature_branch 的新分支
3. bencher run 将使用新的 feature_branch 继续进行

🐰 恭喜！您已经学会了所有关于分支选择的知识！🎉

继续前进：基准测试适配器 ➡