Skip to main content

database index-files

[Infrastruktur] Indiziere eigenständige Dateien mit einem angegebenen CodeQL-Extraktor.

Wer kann dieses Feature verwenden?

GitHub CodeQL wird nach der Installation auf Benutzerbasis lizenziert. Du kannst CodeQL nur für bestimmte Aufgaben unter den Lizenzeinschränkungen verwenden. Weitere Informationen findest du unter Informationen zur CodeQL-CLI.

Wenn du über eine GitHub Advanced Security-Lizenz verfügst, kannst du CodeQL für eine automatisierte Analyse sowie für Continuous Integration und Continuous Delivery verwenden. Weitere Informationen findest du unter Informationen zu GitHub Advanced Security.

In diesem Inhalt wird die neueste Version von CodeQL CLI beschrieben. Weitere Informationen zu diesem Thema findest du unter https://github.com/github/codeql-cli-binaries/releases.

Um Details zu den Optionen anzuzeigen, die für diesen Befehl in früheren Releases verfügbar sind, führe den Befehl mit der Option --help im Terminal aus.

Übersicht

Shell
codeql database index-files --language=<lang> [--threads=<num>] [--ram=<MB>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

Beschreibung

[[Infrastruktur] Indiziere eigenständige Dateien mit einem angegebenen CodeQL-Extraktor.

Dieser Befehl wählt eine Gruppe von Dateien im angegebenen Arbeitsverzeichnis aus und wendet den angegebenen Extraktor auf sie an. Standardmäßig werden alle Dateien ausgewählt. Bei typischen Aufrufen werden Optionen angegeben, um die eingeschlossenen Dateien einzuschränken.

Für die Optionen --include, --exclude und --prune können jeweils Globmuster mit folgenden Platzhalterzeichen angegeben werden:

  • Ein einzelnes Fragezeichen (?) entspricht einem beliebigen Zeichen, mit Ausnahme eines Schrägstrichs oder eines umgekehrten Schrägstrichs.
  • Ein einzelnes Sternchen (*) entspricht einer beliebigen Anzahl von Zeichen, mit Ausnahme von Schrägstrichen oder umgekehrten Schrägstrichen.
  • Das Muster „**“ entspricht null oder mehr vollständigen Verzeichniskomponenten.

Optionen

Primäre Optionen

<database>

[Obligatorisch] Pfad zur CodeQL-Datenbank, die sich im Aufbau befindet. Dieser muss für die Extraktion mit codeql database init vorbereitet sein.

-l, --language=<lang>

[Obligatorisch] Der Extraktor, der zum Indizieren entsprechender Dateien verwendet werden soll.

-j, --threads=<num>

Dient zum Festlegen der Anzahl von Threads, die der Extraktor verwenden soll. Diese Option wird als Vorschlag an den Extraktor übergeben. Wenn die Umgebungsvariable „CODEQL_THREADS“ festgelegt wird, hat der Wert der Umgebungsvariablen Vorrang vor dieser Option.

Du kannst 0 übergeben, um jeweils einen Thread pro Kern auf dem Computer zu verwenden, oder -N, um N Kerne ungenutzt zu lassen. (Es wird allerdings immer noch mindestens ein Thread verwendet.)

-M, --ram=<MB>

Dient zum Festlegen der Arbeitsspeichermenge, die der Extraktor verwenden soll. Diese Option wird als Vorschlag an den Extraktor übergeben. Wenn die Umgebungsvariable „CODEQL_RAM“ festgelegt wird, hat der Wert der Umgebungsvariablen Vorrang vor dieser Option.

--working-dir=<dir>

[Erweitert] Das Verzeichnis, in dem der angegebene Befehl ausgeführt werden soll. Ohne Angabe dieses Arguments wird der Befehl in dem Wert von --source-root ausgeführt, der an codeql database create übergeben wird (sofern vorhanden). Ohne Angabe des Arguments --source-root wird der Befehl im aktuellen Arbeitsverzeichnis ausgeführt.

Optionen zum Steuern des Extraktorverhaltens

-O, --extractor-option=<extractor-option-name=value>

Ermöglicht das Festlegen von Optionen für CodeQL-Extraktoren. extractor-option-name muss im Format „Extraktorname.Gruppe1.Gruppe2.Optionsname“ oder im Format „Gruppe1.Gruppe2.Optionsname“ angegeben werden. Wenn extractor_option_name mit einem Extraktornamen beginnt, muss der angegebene Extraktor die Option „Gruppe1.Gruppe2.Optionsname“ deklarieren. Andernfalls wird die Option für jeden Extraktor festgelegt, der die Option „Gruppe1.Gruppe2.Optionsname“ deklariert. value kann eine beliebige Zeichenfolge ohne Zeilenumbruch sein.

Diese Befehlszeilenoption kann wiederholt verwendet werden, um mehrere Extraktoroptionen festzulegen. Wenn du mehrere Werte für die gleiche Extraktoroption angibst, hängt das Verhalten von dem Typ ab, den die Extraktoroption erwartet. Bei Zeichenfolgenoptionen wird der zuletzt angegebene Wert verwendet. Bei Arrayoptionen werden alle angegebenen Werte der Reihe nach verwendet. Mit dieser Befehlszeilenoption angegebene Extraktoroptionen werden nach Extraktoroptionen verarbeitet, die über --extractor-options-file angegeben wurden.

Bei Übergabe an codeql database init oder codeql database begin-tracing werden die Optionen nur auf die indirekte Ablaufverfolgungsumgebung angewendet. Wenn dein Workflow auch Aufrufe an codeql database trace-command sendet, müssen die Optionen auch dorthin übergeben werden, falls gewünscht.

Weitere Informationen zu CodeQL-Extraktoroptionen findest du unter https://codeql.github.com/docs/codeql-cli/extractor-options. Dort erfährst du unter anderem, wie du die von den einzelnen Extraktoren deklarierten Optionen auflisten kannst.

--extractor-options-file=<extractor-options-bundle-file>

Dient zum Angeben von Paketdateien für Extraktoroptionen. Eine Paketdatei für Extraktoroptionen ist eine JSON-Datei (Erweiterung .json) oder eine YAML-Datei (Erweiterung .yaml oder .yml), die Extraktoroptionen festlegt. Die Datei muss über den Zuordnungsschlüssel „Extraktor“ der obersten Ebene und darunter über Extraktornamen als Zuordnungsschlüssel der zweiten Ebene verfügen. Weitere Zuordnungsebenen stellen geschachtelte Extraktorgruppen dar, und Zeichenfolgen- und Arrayoptionen sind Zuordnungseinträge mit Zeichenfolgen- und Arraywerten.

Paketdateien für Extraktoroptionen werden in der angegebenen Reihenfolge gelesen. Wenn verschiedene Paketdateien für Extraktoroptionen die gleiche Extraktoroption angeben, hängt das Verhalten von dem Typ ab, den die Extraktoroption erwartet. Bei Zeichenfolgenoptionen wird der zuletzt angegebene Wert verwendet. Bei Arrayoptionen werden alle angegebenen Werte der Reihe nach verwendet. Mit dieser Befehlszeilenoption angegebene Extraktoroptionen werden vor Extraktoroptionen verarbeitet, die über --extractor-option angegeben wurden.

Bei Übergabe an codeql database init oder codeql database begin-tracing werden die Optionen nur auf die indirekte Ablaufverfolgungsumgebung angewendet. Wenn dein Workflow auch Aufrufe an codeql database trace-command sendet, müssen die Optionen auch dorthin übergeben werden, falls gewünscht.

Weitere Informationen zu CodeQL-Extraktoroptionen findest du unter https://codeql.github.com/docs/codeql-cli/extractor-options. Dort erfährst du unter anderem, wie du die von den einzelnen Extraktoren deklarierten Optionen auflisten kannst.

Optionen zum Einschränken der Gruppe von indizierten Dateien

--include-extension=<.ext>

Dient zum Einschließen aller Dateien in der Suchverzeichnisstruktur, die über die angegebene Erweiterung verfügen. In der Regel muss der Punkt vor der Erweiterung mit angegeben werden. Wenn du also beispielsweise --include-extension .xml übergibst, werden alle Dateien mit der Erweiterung „.xml“ eingeschlossen. Diese Option ist nicht mit negierten Optionen vom Typ --include kompatibel.

--include=<glob>

Dient zum Einschließen aller Dateien und Verzeichnisse in der Suchverzeichnisstruktur, die dem angegebenen Glob entsprechen. Hierbei wird der relative Pfad der jeweiligen Datei und des jeweiligen Verzeichnisses aus dem Suchverzeichnis verwendet. Wenn das Glob mit einem Ausrufezeichen (!) beginnt, werden die entsprechenden Dateien und Verzeichnisse stattdessen ausgeschlossen.

Optionen vom Typ --include werden der Reihe nach verarbeitet, und frühere Optionen werden durch spätere Optionen überschrieben. --include ** --include !sub/*.ts --include sub/main.* würde beispielsweise sub/main.ts einschließen (da durch sub/main.* eingeschlossen), sub/index.ts ausschließen (da durch !sub/*.ts ausgeschlossen) und sub/test.js einschließen (da durch ** eingeschlossen, ohne nachträglich ausgeschlossen zu werden).

--also-match=<glob>

Dient zum Festlegen, dass alle Ergebnisse auch dem angegebenen Glob entsprechen müssen, wobei der relative Pfad der jeweiligen Datei und des jeweiligen Verzeichnisses aus dem Suchverzeichnis verwendet wird. Diese Option hat die gleiche Struktur und die gleiche Interpretation wie --include, gibt aber eine separate Sequenz von Globs an, die zusammen mit --include angewendet werden.

--exclude=<glob>

Dient zum Ausschließen aller Dateien und Verzeichnisse, die dem angegebenen Glob entsprechen. Hierbei wird der relative Pfad der jeweiligen Datei und des jeweiligen Verzeichnisses aus dem Suchverzeichnis verwendet. Diese Option überschreibt alle Optionen vom Typ „include“. Diese Option ist nicht mit negierten Optionen vom Typ --include kompatibel.

--prune=<glob>

Dient zum Ausschließen aller Dateien und Verzeichnisse, die dem angegebenen Glob entsprechen. Hierbei wird der relative Pfad der jeweiligen Datei und des jeweiligen Verzeichnisses aus dem Suchverzeichnis verwendet. Diese Option überschreibt alle Optionen vom Typ „include“. Diese Option ist nicht mit negierten Optionen vom Typ --include kompatibel.

--size-limit=<bytes>

Dient zum Ausschließen aller Dateien, deren Größe den angegebenen Grenzwert übersteigt. Das Größenlimit wird in Bytes angegeben, kann mit dem Suffix „k“ aber auch in Kibibytes (KiB), mit dem Suffix „m“ in Mebibytes (MiB) und mit dem Suffix „g“ in Gibibytes (GiB) angegeben werden. Diese Option überschreibt alle Optionen vom Typ „include“.

--total-size-limit=<bytes>

Sorgt dafür, dass der Befehl mit einem Fehler beendet wird, wenn die kombinierte Größe aller aufgelösten Dateien den angegebenen Grenzwert übersteigen würde. Das Größenlimit wird in Bytes angegeben, kann mit dem Suffix „k“ aber auch in Kibibytes (KiB), mit dem Suffix „m“ in Mebibytes (MiB) und mit dem Suffix „g“ in Gibibytes (GiB) angegeben werden.

Dient zum Festlegen, dass allen ggf. vorhandenen symbolischen Verknüpfungen zu ihren Zielen gefolgt werden soll.

--[no-]find-any

Dient zum Festlegen, dass maximal eine Übereinstimmung gefunden werden soll (im Gegensatz zu allen Übereinstimmungen).

Verfügbar seit v2.11.3.

Allgemeine Optionen

-h, --help

Zeigt diesen Hilfetext an.

-J=<opt>

[Erweitert] Dient zum Angeben einer Option für die JVM-Instanz, die den Befehl ausführt.

(Beachte, dass Optionen, die Leerzeichen enthalten, nicht ordnungsgemäß verarbeitet werden.)

-v, --verbose

Ermöglicht die inkrementelle Erhöhung der Anzahl ausgegebener Statusmeldungen.

-q, --quiet

Ermöglicht die inkrementelle Verringerung der Anzahl ausgegebener Statusmeldungen.

--verbosity=<level>

[Erweitert] Dient zum expliziten Festlegen des Ausführlichkeitsgrads auf „errors“, „warnings“, „progress“, „progress+“, „progress++“ oder „progress+++“. Überschreibt -v und -q:

--logdir=<dir>

[Erweitert] Ermöglicht das Schreiben detaillierter Protokolle in eine oder mehrere Dateien im angegebenen Verzeichnis mit generierten Namen, die Zeitstempel und den Namen des ausgeführten Unterbefehls enthalten.

(Um eine Protokolldatei mit einem Namen zu schreiben, über den du die volle Kontrolle hast, gib stattdessen --log-to-stderr an, und leite stderr wie gewünscht um.)

--common-caches=<dir>

[Erweitert] Steuert den Speicherort zwischengespeicherter Daten auf dem Datenträger, der zwischen mehreren Ausführungsvorgängen der CLI beibehalten wird, z. B. heruntergeladene QL-Pakete und kompilierte Abfragepläne. Wenn dies nicht explizit festgelegt ist, wird dieses Verzeichnis standardmäßig auf ein Verzeichnis mit dem Namen .codeql festgelegt, das sich im Startverzeichnis des Benutzer. Es wird erstellt, wenn es noch nicht vorhanden ist.

Verfügbar seit v2.15.2.