Branch Selection with bencher run
There are a few ways for setting the project branch in the bencher run CLI subcommand.
If none of these options or flags are used then main is used as the default branch.
--branch
The simplest way is to set the --branch option or the BENCHER_BRANCH environment variable to the slug or UUID of an already existing branch.
If both are defined, the --branch option takes precedence over the BENCHER_BRANCH environment variable.
However, if both of these are missing or the provided value is invalid, then the bencher run command will error.
This is not the most convenient in CI/CD environments, where new branches are popping up all the time.
Instead of using --branch or the BENCHER_BRANCH environment variable, there is an --if-branch option.
--if-branch
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
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! 🎉