Seleção de Branch com bencher run

Uma Branch é a referência git (ou seja, nome da branch ou tag). Ao usar o subcomando de CLI bencher run, selecione uma Branch com a opção --branch ou a variável de ambiente BENCHER_BRANCH. Por padrão, todos os projetos começam com uma Branch main, e main é usada por padrão se nenhuma das opções for especificada.

Ao fazer Benchmarking Contínuo, ou seja, benchmarking em CI, você frequentemente desejará criar ou rebasear uma branch em uma Branch já existente. Isso é chamado de Ponto de Início de Branch Start Point. Um Ponto de Início é outra Branch em uma versão específica (e hash git, se disponível). Ao usar o subcomando de CLI bencher run, selecione um Ponto de Início com a opção --start-point. Além disso, use a opção --start-point-hash para especificar um hash git específico para o Ponto de Início. A quantidade de dados copiada do Ponto de Início é controlada com a opção --start-point-max-versions. Da mesma forma, Limiares podem ser copiados do Ponto de Início com o flag --start-point-clone-thresholds. Para evitar desvio, use o flag --start-point-reset para sempre redefinir a Branch para o Ponto de Início.

--branch <BRANCH>

Para selecionar um Branch, defina a opção --branch ou a variável de ambiente BENCHER_BRANCH para o nome, slug ou UUID do Branch. Se o valor especificado for um nome ou slug e o Branch ainda não existir, ele será criado para você. No entanto, se o valor especificado for um UUID, então o Branch 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, a CLI do Bencher tenta encontrar a git branch atual. Ela começa procurando por um repositório git no diretório de trabalho atual. Se não tiver sucesso, continua para seu diretório pai e tenta novamente até chegar ao diretório raiz. Se um repositório git for encontrado, o nome curto da branch atual será usado. No entanto, se um repositório git não for encontrado, main é usado como a Branch padrão.

--start-point <BRANCH>

Use o nome do Branch especificado, slug ou UUID como o Ponto de Partida para a opção branch. No GitHub, isso geralmente é o branch base para uma Pull Request, e no GitLab, isso geralmente é o branch target para uma Merge Request. O principal caso de uso para --start-point é Benchmarking Contínuo Estatístico.

• Se o Ponto de Partida especificado for uma string vazia, essa opção será ignorada.
• Se branch não existir, ele será criado usando este Ponto de Partida.
• Se branch existir e o Ponto de Partida for o mesmo, essa opção será ignorada.
• Se branch existir e o Ponto de Partida for diferente, um novo branch Head será criado usando este Ponto de Partida atualizado.
• Se branch não existir e o Ponto de Partida não existir, então o branch será criado sem nenhum dado histórico.
• Se branch existir e o Ponto de Partida não existir, então essa opção será ignorada.

Se um novo branch for criado com um Ponto de Partida, os dados mais recentes e, opcionalmente, os Limiares do Ponto de Partida especificado serão copiados. Veja a opção --start-point-max-versions e a opção --start-point-clone-thresholds para mais detalhes.

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

1. Criar um novo Branch chamado feature_branch
2. Copiar os dados mais recentes de main para feature_branch
3. bencher run prosseguiria usando feature_branch

🐰 Nota: Sempre que utilizar variáveis de ambiente, elas devem estar entre aspas duplas (ou seja, --start-point "$MY_BRANCH_ENV_VAR"), se desejar que bencher run não apresente erro quando MY_BRANCH_ENV_VAR não estiver definida.

--start-point-hash <HASH>

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

• Se branch não existir, ele será criado a partir de start-point no hash especificado.
• Se branch existir e tanto start-point quanto o hash especificado forem os mesmos, então esta opção é ignorada.
• Se branch existir e ou o start-point ou o hash especificado forem diferentes, um novo Cabeçalho de branch será criado a partir de start-point no hash especificado.
• Se branch não existir e o start-point não existir no hash especificado, então o branch será criado sem nenhum dado histórico.
• Se branch existir e o start-point não existir no hash especificado, então esta opção é ignorada.

Se um novo branch for criado com um Ponto de Início, todos os dados mais recentes e, opcionalmente, Limiares do start-point no hash especificado serão copiados. Veja a opção --start-point-max-versions e a opção --start-point-clone-thresholds para mais detalhes.

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

1. Removeria o antigo Cabeçalho de feature_branch
2. Criaria um novo Cabeçalho de feature_branch
3. Cópia de todos os dados mais recentes de main no hash 68b12758509ca5e2b1e3983525625e532eb5f562 para o novo Cabeçalho de feature_branch
4. bencher run então prosseguiria usando o novo Cabeçalho de feature_branch

--start-point-max-versions <COUNT>

Especifique o número máximo de versões históricas da ramificação a serem incluídas a partir do Ponto de Início para a opção branch. Quaisquer versões além desse número serão omitidas. O padrão é 255 versões. Esta opção requer que a opção --start-point esteja definida.

Por exemplo, se feature_branch existir com seu Ponto de Início sendo a Ramificação main e main tiver 300 versões, então usar --branch feature_branch --start-point main --start-point-max-versions 100 incluiria apenas as 100 versões mais recentes de main em feature_branch.

--start-point-clone-thresholds

Clone todos os Thresholds do Ponto de Início para a opção branch. Esta flag requer que a opção --start-point esteja configurada.

• Se um Threshold não existir, ele será criado a partir do Threshold do start-point.
• Se um Threshold existir e for igual ao Threshold do start-point, então esse Threshold será efetivamente ignorado.
• Se um Threshold existir e seu modelo for diferente do Threshold do start-point, então o modelo antigo será substituído pelo modelo do Threshold do start-point.
• Se um Threshold existir e o Threshold do start-point não existir, então o modelo do Threshold será removido.

Por exemplo, se feature_branch existir com seu Ponto de Início sendo o Branch main e main tiver um Threshold para o Testbed embutido localhost e a Medida de latency, então usar --branch feature_branch --start-point main --start-point-clone-thresholds criaria um novo Threshold para feature_branch com o Testbed localhost e a Medida de latency.

--start-point-reset

Redefina o branch especificado. Quando a opção --start-point é definida, o branch será redefinido para o Ponto de Partida especificado. Isso é útil para evitar desvios nos dados de Benchmarking Contínuo Estatístico. O principal caso de uso para --start-point-reset sem especificar um Ponto de Partida é o Benchmarking Contínuo Relativo.

• Se o branch não existir e nenhum Ponto de Partida for especificado, o branch será criado sem qualquer dado histórico.
• Se o branch existir e nenhum Ponto de Partida for especificado, um novo Head do branch será criado sem qualquer dado histórico.
• Se o branch não existir e um Ponto de Partida for especificado, o branch será criado usando o Ponto de Partida.
• Se o branch existir e um Ponto de Partida for especificado, um novo Head do branch será criado usando o Ponto de Partida.

Se um novo branch for criado com um Ponto de Partida, todos os dados mais recentes e, opcionalmente, os Limiares do start-point no hash especificado são copiados. Veja a opção --start-point-max-versions e a opção --start-point-clone-thresholds para mais detalhes.

Por exemplo, se o feature_branch existir sem um Ponto de Partida, então usar --branch feature_branch --start-point-reset:

1. Removeria o antigo Head do feature_branch
2. Criaria um novo Head do feature_branch sem dados históricos
3. bencher run procederia então usando o novo Head do feature_branch

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

Continue: Limites & Alertas ➡