Branch Selection with bencher run


There are a few ways to select the project branch in the bencher run CLI subcommand. If none of these options or flags are set then main is used as the default branch.


--branch <BRANCH>


The simplest way to select a branch is to set the --branch option or the BENCHER_BRANCH environment variable to the name, slug, or UUID of an already existing branch. If both are defined, the --branch option takes precedence over the BENCHER_BRANCH environment variable.

In CI/CD environments, new branches are popping up all the time, so there is a way to create new branches with bencher run Instead of using --branch or the BENCHER_BRANCH environment variable, there is the --if-branch option.


--if-branch <BRANCH_NAME>


The --if-branch option expects a branch name argument and queries to see if a single branch with that name exists. If there is exactly one branch found, then bencher run proceeds using that branch. Otherwise, bencher run will simply log and exit successfully.

For example, if main exists then using --if-branch main would find it. Then bencher run would proceed using main.

The --branch option conflicts with the --if-branch option, but the BENCHER_BRANCH environment variable takes precedent over the --if-branch option.


🐰 Note: Whenever using environment variables they should be wrapped in double quotes (ie --if-branch "$MY_ENV_VAR").


--else-if-branch <BRANCH_NAME>


Often, when working on feature branches, it would be useful to have historical data from the parent/base branch. This is where the --else-if-branch option comes in. The --else-if-branch option expects another branch name argument. If --if-branch fails, then --else-if-branch queries to see if a single branch with that name exists. If there is exactly one branch found, then all the data and thresholds from this starting point branch will be copied over to a newly created branch with the name given to --if-branch.

For example, if feature_branch does not yet exist, but main does exist and has historical data. Then using --if-branch feature_branch --else-if-branch main, would create a new branch named feature_branch, and it would have a copy of all the data and thresholds from main. Then bencher run would proceed using feature_branch.

It is also possible to use multiple --else-if-branch options. For example if mia_branch does not exist, --if-branch feature_branch --else-if-branch mia_branch --else-if-branch main would effectively function the same as the previous example, copying all of the data and thresholds from main and proceeding.

If the --if-branch query succeeds then --else-if-branch is never run, and if both --if-branch and --else-if-branch fail, bencher run will simply log and exit successfully.


🐰 Note: Whenever using environment variables they should be wrapped in double quotes (ie --else-if-branch "$MY_ENV_VAR").


--else-branch


To guarantee in all cases that the metrics from a run are stored, there is an --else-branch flag. The --else-branch flag takes no arguments. If --if-branch fails, then --else-branch simply creates a new branch with the name given to --if-branch.

For example, if feature_branch does not yet exist. Then using --if-branch feature_branch --else-branch, would create a new branch named feature_branch, and it would have no initial data nor thresholds. Then bencher run would proceed using feature_branch.

It is also possible to chain all three flags together: --if-branch, --else-if-branch, and --else-branch. For example, --if-branch feature_branch --else-if-branch main --else-branch.

If the --if-branch query succeeds then --else-branch is never run, and likewise, if --if-else-branch succeeds then --else-branch is never run. And --else-branch is expected to always succeed and exit successfully.


--endif-branch


The --endif-branch flag works as an optional noop flag to indicate the end of the --if-branch statement.

It is possible to chain all four flags together: --if-branch, --else-if-branch, --else-branch, and --endif-branch. For example, --if-branch feature_branch --else-if-branch "$MY_ENV_VAR" --else-branch --endif-branch.



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


Keep Going: Benchmark Harness Adapters ➡