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! 🎉