使用 bencher run 进行分支选择

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

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

--branch <BRANCH>

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

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

--branch-start-point <BRANCH>

使用指定的分支名称、别名或UUID作为branch选项的起始点。 对于GitHub，通常是Pull Request的base分支； 对于GitLab，通常是Merge Request的target分支。 --branch-start-point的主要用途是统计持续基准测试。

• 如果指定的起始点是空字符串，则忽略此选项。
• 如果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"）， 如果你不希望在MY_BRANCH_ENV_VAR未定义时bencher run报错。

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

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

• 如果 branch 不存在，将会从指定的哈希值处的 branch-start-point 创建。
• 如果 branch 已存在且 branch-start-point 与指定的哈希值相同， 则此选项将被忽略。
• 如果 branch 已存在且 branch-start-point 或指定的哈希值不同， 旧版本的 branch 将被重命名， 并从 branch-start-point 处的指定哈希值创建新的 branch。

如果使用起点创建了一个新的 branch， 那么从指定哈希值处的 branch-start-point 将复制所有数据和阈值。

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

1. 将旧的 feature_branch 重命名为 feature_branch@main/hash/32aea434d751648726097ed3ac760b57107edd8b
2. 创建一个名为 feature_branch 的新分支
3. 将所有数据和阈值从 main 的哈希 68b12758509ca5e2b1e3983525625e532eb5f562 复制到新的 feature_branch
4. 使用新的 feature_branch 进行 bencher run

--branch-reset

重置指定的branch。 --branch-reset的主要用例是相对持续基准测试。 此标志与--branch-start-point选项相冲突。

• 如果branch不存在，将被创建。
• 如果branch已存在，原有版本的branch将被重命名， 并且将创建新的branch。

当新的branch被创建时，它不会有历史数据或阈值。

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

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

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

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