Branchenauswahl mit bencher run

Eine Branch ist die git Ref (d.h. Branch-Name oder Tag). Beim Verwenden des bencher run CLI-Unterbefehls, wähle eine Branch mit der Option --branch oder der Umgebungsvariable BENCHER_BRANCH. Standardmäßig starten alle Projekte mit einer main Branch, und main wird standardmäßig verwendet, falls weder noch angegeben sind.

Beim Kontinuierlichen Benchmarking, also Benchmarking in CI, will man oft eine branch auf eine bereits existierende Branch erstellen oder rebasen. Dies wird ein Branch Startpunkt genannt. Ein Startpunkt ist eine andere Branch zu einer bestimmten Version (und git Hash, falls verfügbar). Beim Verwenden des bencher run CLI-Unterbefehls, wähle einen Startpunkt mit der Option --branch-start-point. Zusätzlich kann die Option --branch-start-point-hash verwendet werden, um einen bestimmten git Hash für den Startpunkt anzugeben. Alle Daten und Schwellenwerte werden vom Startpunkt kopiert. Um Drift zu verhindern, benutze die Option --branch-reset, um die Branch immer auf den Startpunkt zurückzusetzen.

--branch <BRANCH>

Um einen Branch auszuwählen, setzen Sie die --branch Option oder die BENCHER_BRANCH Umgebungsvariable auf den Namen, den Slug oder die UUID des Branches. Wenn der angegebene Wert ein Name oder Slug ist und der Branch noch nicht existiert, wird er für Sie erstellt. Wenn jedoch der angegebene Wert eine UUID ist, muss der Branch bereits existieren. Wenn beides angegeben ist, hat die --branch Option Vorrang vor der BENCHER_BRANCH Umgebungsvariablen.

Wenn keines angegeben ist, versucht das Bencher CLI, den aktuellen git-Zweig zu finden. Es beginnt mit der Suche nach einem git-Repository im aktuellen Arbeitsverzeichnis. Falls dies erfolglos ist, setzt es seine Suche im übergeordneten Verzeichnis fort und wiederholt dies bis zum Stammverzeichnis. Wenn ein git-Repository gefunden wird, dann wird der aktuelle kurze Zweigname verwendet. Wenn jedoch kein git-Repository gefunden wird, dann wird main als Standardzweig verwendet.

--branch-start-point <BRANCH>

Verwenden Sie den angegebenen Branch-Namen, Slug oder UUID als Startpunkt für die branch Option. Für GitHub ist dies normalerweise der base Branch für eine Pull Request, und für GitLab ist dies normalerweise der target Branch für eine Merge Request. Der Hauptanwendungsfall für --branch-start-point ist Statistische Kontinuierliche Benchmarking.

• Wenn der angegebene Startpunkt eine leere Zeichenkette ist, wird diese Option ignoriert.
• Wenn branch nicht existiert, wird er mit diesem Startpunkt erstellt.
• Wenn branch existiert und der Startpunkt derselbe ist, wird diese Option ignoriert.
• Wenn branch existiert und der Startpunkt unterschiedlich ist, wird die alte Version von branch sowohl umbenannt als auch archiviert und ein neuer branch wird mit diesem aktualisierten Startpunkt erstellt.
• Wenn branch nicht existiert und der Startpunkt nicht existiert, wird der branch ohne historische Daten erstellt.
• Wenn branch existiert und der Startpunkt nicht existiert, wird diese Option ignoriert.

Wenn ein neuer branch mit einem Startpunkt erstellt wird, werden alle Daten und Schwellenwerte vom angegebenen Startpunkt übernommen.

Zum Beispiel, wenn feature_branch noch nicht existiert, aber main existiert und historische Daten hat. Dann würde die Verwendung von --branch feature_branch --branch-start-point main folgendes tun:

1. Einen neuen Branch namens feature_branch erstellen
2. Alle Daten und Schwellenwerte von main in feature_branch kopieren
3. bencher run würde mit feature_branch fortfahren

🐰 Hinweis: Wann immer Umgebungsvariablen verwendet werden, sollten sie in doppelte Anführungszeichen gesetzt werden (z.B. --branch-start-point "$MY_BRANCH_ENV_VAR"), falls Sie möchten, dass bencher run keinen Fehler ausgibt, wenn MY_BRANCH_ENV_VAR undefiniert ist.

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

Verwenden Sie den angegebenen vollständigen Git-Hash als Startpunkt für die Option branch. Diese Option erfordert, dass die Option --branch-start-point gesetzt ist.

• Wenn branch nicht existiert, wird es aus branch-start-point an dem angegebenen Hash erstellt.
• Wenn branch existiert und sowohl branch-start-point als auch der angegebene Hash gleich sind, wird diese Option ignoriert.
• Wenn branch bereits existiert und entweder branch-start-point oder der angegebene Hash unterschiedlich sind, wird die alte Version von branch umbenannt und archiviert, und ein neues branch wird aus branch-start-point an dem angegebenen Hash erstellt.
• Wenn branch nicht existiert und der branch-start-point an dem angegebenen Hash nicht existiert, wird branch ohne historische Daten erstellt.
• Wenn branch existiert und der branch-start-point an dem angegebenen Hash nicht existiert, wird diese Option ignoriert.

Wenn ein neues branch mit einem Startpunkt erstellt wird, werden alle Daten und Schwellenwerte von branch-start-point an dem angegebenen Hash kopiert.

Zum Beispiel, wenn feature_branch existiert und der Startpunkt der main-Branch bei Hash 32aea434d751648726097ed3ac760b57107edd8b ist, würde die Verwendung von --branch feature_branch --branch-start-point main --branch-start-point-hash 68b12758509ca5e2b1e3983525625e532eb5f562 folgendes bewirken:

1. Die alte feature_branch würde in feature_branch@archive-suffix umbenannt und archiviert
2. Eine neue Branch mit dem Namen feature_branch würde erstellt
3. Alle Daten und Schwellenwerte von main bei Hash 68b12758509ca5e2b1e3983525625e532eb5f562 würden in die neue feature_branch kopiert
4. bencher run würde mit der neuen feature_branch fortfahren

--branch-reset

Setzt den angegebenen branch zurück. Wenn die Option --branch-start-point gesetzt ist, wird der branch auf den angegebenen Startpunkt zurückgesetzt. Dies ist nützlich, um Abweichungen in den Daten der Statistischen kontinuierlichen Benchmarking zu verhindern. Der Hauptanwendungsfall für --branch-reset ohne Angabe eines Startpunkts ist das Relative kontinuierliche Benchmarking.

• Wenn branch nicht existiert und kein Startpunkt angegeben ist, wird der branch ohne historische Daten erstellt.
• Wenn branch existiert und kein Startpunkt angegeben ist, wird die alte Version von branch sowohl umbenannt als auch archiviert und ein neuer branch ohne historische Daten erstellt.
• Wenn branch nicht existiert und ein Startpunkt angegeben ist, wird der branch unter Verwendung des Startpunkts erstellt.
• Wenn branch existiert und ein Startpunkt angegeben ist, wird die alte Version von branch sowohl umbenannt als auch archiviert und ein neuer branch unter Verwendung des Startpunkts erstellt.

Wenn ein neuer branch mit einem Startpunkt erstellt wird, werden alle Daten und Schwellenwerte vom angegebenen Startpunkt kopiert. Andernfalls wird der branch ohne historische Daten erstellt.

Zum Beispiel, wenn feature_branch ohne einen Startpunkt existiert, würde die Verwendung von --branch feature_branch --branch-reset folgendes bewirken:

1. Die alte feature_branch wird in feature_branch@archive-suffix umbenannt und archiviert
2. Ein neuer Branch namens feature_branch wird erstellt
3. bencher run würde unter Verwendung des neuen feature_branch fortgesetzt

🐰 Glückwunsch! Sie haben alles über die Branchenauswahl gelernt! 🎉

Weitermachen: Benchmark Harness Adapters ➡