Seleção de Branch com bencher run

Um Branch é o git ref (isto é, nome do branch ou tag). Ao usar o subcomando CLI bencher run, selecione um Branch com a opção --branch ou a variável de ambiente BENCHER_BRANCH. Por padrão, todos os projetos começam com um Branch main, e main é usado por padrão se nenhum deles for especificado.

Quando se faz Benchmarking Contínuo, ou seja, benchmarking em CI, você vai querer frequentemente criar ou fazer rebase de um branch em um Branch já existente. Isso é chamado de Ponto de Início de um Branch. Um Ponto de Início é outro Branch em uma versão específica (e git hash, se disponível). Ao usar o subcomando CLI bencher run, selecione um Ponto de Início com a opção --branch-start-point. Adicionalmente, use a opção --branch-start-point-hash para especificar um git hash específico para o Ponto de Início. Todos os dados e Limites são copiados do Ponto de Início.

--branch <BRANCH>

Para selecionar um Ramo, defina a opção --branch ou a variável de ambiente BENCHER_BRANCH para o nome, identificador ou UUID do Ramo. Se o valor especificado for um nome ou identificador e o Ramo ainda não existir, ele será criado para você. No entanto, se o valor especificado for um UUID, então o Ramo já deve existir. Se ambos forem especificados, a opção --branch tem precedência sobre a variável de ambiente BENCHER_BRANCH.

Se nenhum dos dois for especificado, o CLI do Bencher tenta encontrar o branch atual do git. Ele começa procurando por um repositório git no diretório de trabalho atual. Se não for bem-sucedido, continua para o diretório pai e tenta novamente, até chegar ao diretório raiz. Se um repositório git for encontrado, então o nome curto do branch atual é usado. No entanto, se um repositório git não for encontrado, então main é usado como o Branch padrão.

--branch-start-point <BRANCH>

Use o nome da Branch, slug ou UUID especificado como Ponto de Início para a opção branch. Para o GitHub, isso é geralmente a base branch para um Pull Request, e para o GitLab, isso é geralmente a target branch para um Merge Request. O principal caso de uso para --branch-start-point é Benchmarks Estatísticos Contínuos.

• Se o Ponto de Início especificado for uma string vazia, então essa opção será ignorada.
• Se branch não existir, ela será criada usando esse Ponto de Início.
• Se branch já existir e o Ponto de Início for o mesmo, então essa opção será ignorada.
• Se branch já existir e o Ponto de Início for diferente, a versão antiga de branch será renomeada e uma nova branch será criada usando esse Ponto de Início atualizado.

Se uma nova branch for criada com um Ponto de Início, então todos os dados e Limiares do Ponto de Início especificado serão copiados.

Por exemplo, se feature_branch ainda não existir, mas main existir e tiver dados históricos. Então, usar --branch feature_branch --branch-start-point main faria:

1. Criar uma nova Branch chamada feature_branch
2. Copiar todos os dados e Limiares de main para feature_branch
3. bencher run prosseguiria usando feature_branch

🐰 Nota: Sempre que utilizar variáveis de ambiente, elas devem ser envolvidas em aspas duplas (ou seja, --branch-start-point "$MY_BRANCH_ENV_VAR"), caso você queira que bencher run não apresente erro quando MY_BRANCH_ENV_VAR estiver indefinido.

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

Utilize o hash Git completo especificado como o Ponto de Início para a opção branch. Esta opção requer que a opção --branch-start-point esteja definida.

• Se branch não existir, será criada a partir do branch-start-point no hash especificado.
• Se branch já existir e tanto o branch-start-point quanto o hash especificado forem os mesmos, então esta opção é ignorada.
• Se branch já existir e tanto o branch-start-point quanto o hash especificado forem diferentes, a versão antiga de branch será renomeada e uma nova branch será criada a partir do branch-start-point no hash especificado.

Se um novo branch é criado com um Ponto de Início, então todos os dados e Limites do branch-start-point no hash especificado são copiados.

Por exemplo, se feature_branch existir com seu Ponto de Início sendo o Branch main no hash 32aea434d751648726097ed3ac760b57107edd8b então usar --branch feature_branch --branch-start-point main --branch-start-point-hash 68b12758509ca5e2b1e3983525625e532eb5f562 faria com que:

1. O antigo feature_branch seja renomeado para feature_branch@main/hash/32aea434d751648726097ed3ac760b57107edd8b
2. Crie um novo Branch chamado feature_branch
3. Copie todos os dados e Limites do main no hash 68b12758509ca5e2b1e3983525625e532eb5f562 para o novo feature_branch
4. bencher run prosseguiria usando o novo feature_branch

--branch-reset

Redefine a branch especificada. O principal caso de uso para --branch-reset é o Benchmarking Contínuo Relativo. Esta opção entra em conflito com a opção --branch-start-point.

• Se branch não existir, ela será criada.
• Se branch já existir, a versão antiga da branch será renomeada e uma nova branch será criada.

Quando uma nova branch é criada ela não terá dados históricos ou Limites.

Por exemplo, se feature_branch existe sem um Ponto de Início, então usar --branch feature_branch --branch-reset faria:

1. Renomear a antiga feature_branch para feature_branch@detached
2. Criar uma nova Branch chamada feature_branch
3. bencher run procederá usando a nova feature_branch

🐰 Parabéns! Você aprendeu tudo sobre seleção de branches! 🎉

Continue: Adaptadores do Harness de Benchmark ➡