Branch Selection with bencher run

---

A Branch is the git ref (ie branch name or tag). When using the bencher run CLI subcommand, select a Branch with the --branch option or the BENCHER_BRANCH environment variable. By default all projects start with a main Branch, and main is used by default if neither are specified.

When Continuous Benchmarking, that is benchmarking in CI, you will often want to create or rebase a branch on an already existing Branch. This is called a Branch Start Point. A Start Point is another Branch at a specific version (and git hash, if available). When using the bencher run CLI subcommand, select a Start Point with the --branch-start-point option. Additionally, use the --branch-start-point-hash option to specify a specific git hash for the Start Point. All the data and Thresholds are copied over from the Start Point.

--branch <BRANCH>

To select a Branch, set the --branch option or the BENCHER_BRANCH environment variable to the name, slug, or UUID for the Branch. If the value specified is a name or slug and the Branch does not already exist, it will be created for you. However, if the value specified is a UUID then the Branch must already exist. If both are specified, the --branch option takes precedence over the BENCHER_BRANCH environment variable. If neither are specified then main is used as the default Branch.

--branch-start-point <BRANCH>

Use the specified Branch name, slug, or UUID as the Start Point for the branch option. For GitHub this is usually the base branch for a Pull Request, and for GitLab this is usually the target branch for a Merge Request. The primary use case for --branch-start-point is Statistical Continuous Benchmarking.

• If the specified Start Point is an empty string, then this option is ignored.
• If branch does not exist, it will be created using this Start Point.
• If branch does exist and the Start Point is the same, then this option is ignored.
• If branch does exist and the Start Point is different, the old version of branch will be renamed and a new branch will be created using this updated Start Point.

If a new branch is created with a Start Point, then all the data and Thresholds from the specified Start Point are copied over.

For example, if feature_branch does not yet exist, but main does exist and has historical data. Then using --branch feature_branch --branch-start-point main would:

1. Create a new Branch named feature_branch
2. Copy of all the data and Thresholds from main to feature_branch
3. bencher run would proceed using feature_branch

🐰 Note: Whenever using environment variables they should be wrapped in double quotes (ie --branch-start-point "$MY_BRANCH_ENV_VAR"), if you would like bencher run to not error when MY_BRANCH_ENV_VAR is undefined.

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

Use the specified full Git hash as the Start Point for the branch option. This option requires the --branch-start-point option to be set.

• If branch does not exist, it will be created from branch-start-point at the specified hash.
• If branch does exist and both branch-start-point and the specified hash are the same, then this option is ignored.
• If branch already exists and either the branch-start-point or the specified hash are different, the old version of branch will be renamed and a new branch will be created from branch-start-point at the specified hash.

If a new branch is created with a Start Point, then all the data and Thresholds from the branch-start-point at the specified hash are copied over.

For example, if feature_branch exists with its Start Point being the main Branch at hash 32aea434d751648726097ed3ac760b57107edd8b then using --branch feature_branch --branch-start-point main --branch-start-point-hash 68b12758509ca5e2b1e3983525625e532eb5f562 would:

1. Rename the old feature_branch to feature_branch@main/hash/32aea434d751648726097ed3ac760b57107edd8b
2. Create a new Branch named feature_branch
3. Copy of all the data and Thresholds from main at hash 68b12758509ca5e2b1e3983525625e532eb5f562 to the new feature_branch
4. bencher run would proceed using the new feature_branch

--branch-reset

Reset the specified branch. The primary use case for --branch-reset is Relative Continuous Benchmarking. This flag conflicts with the --branch-start-point option.

• If branch does not exit, it will be created.
• If branch does exist, the old version of branch will be renamed and a new branch will be created.

When a new branch is created it will have no historical data or Thresholds.

For example, if feature_branch exists without a Start Point then using --branch feature_branch --branch-reset would:

1. Rename the old feature_branch to feature_branch@detached
2. Create a new Branch named feature_branch
3. bencher run would proceed using the new feature_branch

🐰 Congrats! You have learned all about Branch selection! 🎉

Keep Going: Benchmark Harness Adapters ➡