NAME
gdcloud topic command-conventions - Guida supplementare per le convenzioni dei comandi gdcloud.
DESCRIZIONE
La progettazione dei comandi della CLI gdcloud segue un insieme comune di principi e convenzioni. Questo documento li descrive in dettaglio.
Le convenzioni sono obiettivi anziché regole. Per eventuali eccezioni, consulta le informazioni fornite per i singoli comandi utilizzando il flag --help.
GERARCHIA DEI COMANDI
I comandi della CLI gdcloud sono organizzati come un albero con gdcloud alla radice, gruppi di comandi nei nodi interni e comandi nei nodi foglia. I comandi di gruppo sono eseguibili, ma solo per visualizzare il testo della guida.
Tutti i gruppi e i comandi hanno un flag --help che visualizza il testo della guida come output standard. Il testo della guida deriva dall'eseguibile in esecuzione, quindi è sempre aggiornato, anche quando si passa da un'installazione di release all'altra.
RIGA DI COMANDO
Ogni comando gdcloud segue la stessa forma
gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
I flag e gli argomenti posizionali possono essere combinati, ma per coerenza, i posizionali vengono in genere visualizzati per primi in ordine, seguiti dai flag in qualsiasi ordine.
NOTAZIONE DI UTILIZZO DEI COMANDI
L'utilizzo dei comandi è una notazione abbreviata che contiene il nome completo del comando, gli argomenti posizionali e gli argomenti flag in ordine di gruppo. Gli argomenti facoltativi sono racchiusi tra [ ... ]. Ad esempio:
gdcloud foo bar NAME [--format=FORMAT]
Questo è l'utilizzo del comando gdcloud foo bar con un argomento posizionale NAME obbligatorio, un argomento posizionale EXTRA facoltativo e un argomento flag --format facoltativo.
Argomenti posizionali
Gli argomenti posizionali sono ordinati e devono essere specificati nell'ordine elencato nell'elenco delle definizioni degli argomenti del documento di utilizzo e della guida dei comandi.
Argomenti flag
I nomi dei flag sono in minuscolo con un prefisso --. I flag con più parole utilizzano - (trattino) come separatore di parole.
Seguendo la convenzione UNIX, se un flag viene ripetuto nella riga di comando, viene applicata solo l'occorrenza più a destra. Non viene emessa alcuna diagnostica. In questo modo è facile configurare alias di comandi e script wrapper che forniscono valori di flag predefiniti; valori che possono essere facilmente sostituiti specificandoli nella riga di comando dell'alias o dello script wrapper.
Flag booleani
Sebbene molti flag booleani abbiano un valore implicito di false, alcuni sono true per impostazione predefinita. La presenza di --flag imposta il flag su true o false, a seconda del valore implicito del nome del flag.
Flag con valori
I flag non booleani hanno un valore esplicito. Il valore può essere specificato inserendolo come argomento successivo al flag --flag value.
Se il valore è un numero intero, deve essere 0 o superiore. I numeri interi negativi non sono accettati.
Output
L'output standard è per le informazioni esplicite richieste dal comando.
A seconda del contesto, potrebbero essere presenti garanzie sul formato di output per supportare l'analisi deterministica. Alcuni comandi restituiscono risorse e queste risorse vengono elencate come output standard, in genere utilizzando un formato di tabella specifico del comando o il formato YAML predefinito. Inoltre, il flag --format può essere utilizzato per modificare o configurare questi formati di output predefiniti. I valori --format di output yaml, json e csv garantiscono che il completamento corretto del comando generi dati di output standard che possono essere analizzati utilizzando il rispettivo formato. Una spiegazione dettagliata delle funzionalità del flag --format è disponibile con il comando gdcloud topic formats. Per i comandi che non restituiscono risorse, l'output è definito nel flag --help del comando.
L'errore standard è riservato alla diagnostica. In generale, il formato dei dati di errore standard potrebbe cambiare da una release all'altra. Gli utenti non devono creare script basati su contenuti specifici o sull'esistenza di output nell'errore standard. L'unico indicatore di errore affidabile è lo stato di uscita.
Nessun comando della CLI gdcloud deve avere un arresto anomalo con un'eccezione non rilevata. Tuttavia, se la CLI gdcloud si arresta in modo anomalo, l'analisi dello stack viene intercettata e scritta nel file di log e viene scritta una diagnostica di arresto anomalo nell'errore standard.
Stato di uscita
Lo stato di uscita 0 indica l'esito positivo. Qualsiasi altro stato di uscita indica un errore. Le diagnostiche specifiche dei comandi spiegheranno la natura dell'errore e come correggerlo.