NAME
gdcloud topic command-conventions – Zusätzliche Hilfe zu gdcloud-Befehlskonventionen
BESCHREIBUNG
Das Befehlsdesign der gdcloud CLI folgt einer Reihe gemeinsamer Prinzipien und Konventionen. Diese werden in diesem Dokument ausführlich beschrieben.
Konventionen sind eher Ziele als Regeln. Informationen zu Ausnahmen finden Sie in der Dokumentation zu den einzelnen Befehlen, die Sie mit dem Flag --help aufrufen können.
BEFEHLSHIERARCHIE
gdcloud CLI-Befehle sind als Baumstruktur organisiert, mit gdcloud als Stamm, Befehlsgruppen in den inneren Knoten und Befehlen in den Blattknoten. Gruppenbefehle sind ausführbar, aber nur zum Anzeigen des Hilfetexts.
Alle Gruppen und Befehle haben ein Flag --help, das den Hilfetext als Standardausgabe anzeigt. Der Hilfetext wird aus der ausgeführten Datei abgeleitet und ist daher immer aktuell, auch wenn Sie zwischen mehreren Release-Installationen wechseln.
BEFEHLSZEILE
Jeder gdcloud-Befehl folgt derselben Form
gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
Flag- und Positionsargumente können gemischt werden. Aus Gründen der Konsistenz werden Positionsargumente jedoch normalerweise zuerst in der Reihenfolge und dann Flags in beliebiger Reihenfolge angezeigt.
NOTATION FÜR DIE BEFEHLSVERWENDUNG
Die Befehlsverwendung ist eine Kurznotation, die den vollständigen Befehlsnamen, die Positionsargumente und die Flag-Argumente in gruppierter sortierter Reihenfolge enthält. Optionale Argumente sind in [ ... ] eingeschlossen. Beispiel:
gdcloud foo bar NAME [--format=FORMAT]
Dies ist die Verwendung für den Befehl gdcloud foo bar mit einem erforderlichen Positionsargument NAME, einem optionalen Positionsargument EXTRA und einem optionalen Flag-Argument --format.
Positionsargumente
Positionsargumente sind geordnet und müssen in der Reihenfolge angegeben werden, die in der Liste der Argumentdefinitionen in der Befehlsverwendung und im Hilfedokument aufgeführt ist.
Flag-Argumente
Flag-Namen sind kleingeschrieben und haben das Präfix --. Bei Flags mit mehreren Wörtern wird - (Bindestrich/Strich) als Worttrennzeichen verwendet.
Gemäß der UNIX-Konvention gilt bei Wiederholung eines Flags in der Befehlszeile nur das am weitesten rechts stehende Vorkommen. Es wird keine Diagnose ausgegeben. So lassen sich Befehlsaliase und Wrapper-Skripts einfach einrichten, die Standard-Flag-Werte bereitstellen. Diese Werte können einfach überschrieben werden, indem Sie sie in der Befehlszeile des Alias oder Wrapper-Skripts angeben.
Boolesche Flags
Viele boolesche Flags haben den impliziten Wert false, einige sind standardmäßig true. Durch das Vorhandensein von --flag wird das Flag auf true oder false gesetzt, je nachdem, welcher Wert durch den Namen des Flags impliziert wird.
Flags mit Werten
Nicht boolesche Flags haben einen expliziten Wert. Der Wert kann angegeben werden, indem Sie ihn als nächstes Argument nach dem Flag --flag value platzieren.
Wenn der Wert eine Ganzzahl ist, muss er 0 oder höher sein. Negative Ganzzahlen sind nicht zulässig.
Ausgabe
Die Standardausgabe ist für explizite Informationen vorgesehen, die vom Befehl angefordert werden.
Je nach Kontext gibt es möglicherweise Garantien für das Ausgabeformat, um eine deterministische Analyse zu unterstützen. Bestimmte Befehle geben Ressourcen zurück. Diese Ressourcen werden in der Standardausgabe normalerweise entweder in einem befehlsspezifischen Tabellenformat oder im Standard-YAML-Format aufgeführt. Außerdem kann das Flag --format verwendet werden, um diese Standardausgabeformate zu ändern oder zu konfigurieren. Die --format-Werte yaml, json und csv garantieren, dass bei erfolgreichem Abschluss des Befehls Standardausgabedaten ausgegeben werden, die mit dem jeweiligen Format analysiert werden können. Eine detaillierte Erläuterung der Funktionen des Flags --format finden Sie mit dem Befehl gdcloud topic formats. Bei Befehlen, die keine Ressourcen zurückgeben, wird die Ausgabe im Flag --help des Befehls definiert.
Die Standardfehlerausgabe ist für Diagnosen reserviert. Im Allgemeinen kann sich das Format der Standardfehlerausgabe von Release zu Release ändern. Nutzer dürfen keine Skripts für bestimmte Inhalte oder auch nur für das Vorhandensein einer Ausgabe in der Standardfehlerausgabe erstellen. Der einzige zuverlässige Fehlerindikator ist der Exit-Status.
Keine gdcloud CLI-Befehle sollten mit einer nicht abgefangenen Ausnahme abstürzen. Wenn die gdcloud CLI jedoch abstürzt, wird der Stacktrace abgefangen und in die Logdatei geschrieben. Außerdem wird eine Absturzdiagnose in die Standardfehlerausgabe geschrieben.
Exit-Status
Der Exit-Status 0 gibt Erfolg an. Jeder andere Exit-Status gibt einen Fehler an. Befehlsspezifische Diagnosen erläutern die Art des Fehlers und wie er behoben werden kann.