NAME
gdcloud topic command-conventions : aide supplémentaire pour les conventions de commande gdcloud.
DESCRIPTION
La conception des commandes de la CLI gdcloud suit un ensemble commun de principes et de conventions. Ce document les décrit en détail.
Les conventions sont des objectifs plutôt que des règles. Pour toute exception, reportez-vous aux informations fournies pour les commandes individuelles à l'aide de l'option --help.
HIÉRARCHIE DES COMMANDES
Les commandes de la CLI gdcloud sont organisées sous forme d'arborescence, avec gdcloud à la racine, des groupes de commandes dans les nœuds internes et des commandes dans les nœuds feuilles. Les commandes de groupe sont exécutables, mais uniquement pour afficher le texte d'aide.
Tous les groupes et toutes les commandes comportent une option --help qui affiche le texte d'aide en tant que sortie standard. Le texte d'aide est dérivé de l'exécutable en cours d'exécution. Il est donc toujours à jour, même lorsque vous passez d'une installation de version à une autre.
LIGNE DE COMMANDE
Chaque commande gdcloud suit la même forme
gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
Les arguments d'option et positionnels peuvent être mélangés, mais par souci de cohérence, les arguments positionnels sont généralement affichés en premier, suivis des options dans n'importe quel ordre.
NOTATION D'UTILISATION DES COMMANDES
L'utilisation des commandes est une notation abrégée qui contient le nom complet de la commande, les arguments positionnels et les arguments d'option dans l'ordre de tri du groupe. Les arguments facultatifs sont placés entre crochets [ ... ]. Exemple
gdcloud foo bar NAME [--format=FORMAT]
Il s'agit de l'utilisation de la commande gdcloud foo bar avec un argument positionnel NAME obligatoire, un argument positionnel EXTRA facultatif et un argument d'option --format facultatif.
Arguments positionnels
Les arguments positionnels sont ordonnés et doivent être spécifiés dans l'ordre indiqué dans la liste de définition des arguments du document d'aide et d'utilisation de la commande.
Arguments d'option
Les noms d'option sont en minuscules et précédés de --. Les options composées de plusieurs mots utilisent - (tiret) comme séparateur de mots.
Conformément à la convention UNIX, si une option est répétée sur la ligne de commande, seule l'occurrence la plus à droite prend effet. Aucun diagnostic n'est émis. Cela facilite la configuration des alias de commande et des scripts wrapper qui fournissent des valeurs d'option par défaut. Ces valeurs peuvent être facilement remplacées en les spécifiant sur la ligne de commande de l'alias ou du script wrapper.
Options booléennes
Bien que de nombreuses options booléennes aient une valeur implicite false, certaines sont true par défaut. La présence de --flag définit l'option sur true ou false, selon la valeur implicite du nom de l'option.
Options avec valeur
Les options non booléennes ont une valeur explicite. La valeur peut être spécifiée en la plaçant comme argument suivant après l'option --flag value.
Si la valeur est un entier, elle doit être supérieure ou égale à 0. Les entiers négatifs ne sont pas acceptés.
Sortie
La sortie standard est destinée aux informations explicites demandées par la commande.
Selon le contexte, le format de sortie peut être garanti pour permettre une analyse déterministe. Certaines commandes renvoient des ressources, qui sont listées en tant que sortie standard, généralement au format de tableau spécifique à la commande ou au format YAML par défaut. De plus, l'option --format peut être utilisée pour modifier ou configurer ces formats de sortie par défaut. Les valeurs de sortie --format yaml, json et csv garantissent que l'exécution réussie de la commande génère des données de sortie standard qui peuvent être analysées à l'aide du format respectif. Une explication détaillée des fonctionnalités de l'option --format est disponible avec la commande gdcloud topic formats. Pour les commandes qui ne renvoient pas de ressources, le résultat est défini dans l'option --help de la commande.
L'erreur standard est réservée aux diagnostics. En général, le format des données d'erreur standard peut changer d'une version à l'autre. Les utilisateurs ne doivent pas créer de scripts basés sur un contenu spécifique, ni même sur l'existence d'une sortie vers l'erreur standard. Le seul indicateur d'erreur fiable est l'état de sortie.
Aucune commande de la CLI gdcloud ne doit planter avec une exception non interceptée. Toutefois, si la CLI gdcloud plante, la trace de la pile est interceptée et écrite dans le fichier journal, et un diagnostic de plantage est écrit dans l'erreur standard.
État de sortie
L'état de sortie 0 indique la réussite. Tout autre état de sortie indique une erreur. Les diagnostics spécifiques à la commande expliquent la nature de l'erreur et comment la corriger.