Quelle est la syntaxe de la version bower (et npm)?


274

Bower me permet de spécifier les exigences de version pour les packages à l'aide de la syntaxe suivante:

"dependencies": {
  "<name>": "<version>",
},

Mais je n'ai pas pu trouver quelle est la syntaxe à utiliser pour le <version>. Je sais que je peux spécifier que les versions doivent être:

  • supérieur à une certaine version avec ">1.0.0"
  • supérieur ou égal à une version: ">=1.0.0"
  • ou dans une plage: "1.0.0 - 2.0.0".

Je sais aussi qu'il ya une syntaxe de version commune contenant le tilde: "~1.0.0". Mais je ne sais pas ce que cela signifie et si c'est la même chose que "=1.0.0".

Je suis également intéressé de savoir si je suis capable de spécifier plusieurs versions non consécutives, telles que des 1.0.3versions exactement plus supérieures à 1.5.0, etc.


3
Cela pourrait être un doublon de stackoverflow.com/a/19040351/537738
David

Réponses:


341

En résumé, la syntaxe des numéros de version de Bower (et des NPM) est appelée SemVer, qui est l'abréviation de «Semantic Versioning». Vous pouvez trouver de la documentation pour la syntaxe détaillée de SemVer utilisée dans Bower et NPM sur l'API pour l'analyseur semver dans Node / npm . Vous pouvez en savoir plus sur la spécification sous-jacente (qui ne mentionne pas~ ou d'autres détails de syntaxe) sur semver.org .

Il y a une calculatrice visuelle très pratique avec laquelle vous pouvez jouer, ce qui rend tout cela beaucoup plus facile à tester et à tester.

SemVer n'est pas seulement une syntaxe! Il a des choses assez intéressantes à dire sur les bonnes façons de publier des API, qui aideront à comprendre ce que signifie la syntaxe. Crucialement:

Une fois que vous avez identifié votre API publique, vous lui communiquez les modifications avec des incréments spécifiques à votre numéro de version. Considérez un format de version de XYZ (Major.Minor.Patch) . Les corrections de bogues n'affectant pas l'incrémentation de l'API de la version du correctif, les ajouts / modifications d'API rétrocompatibles incrémentent la version mineure et les modifications d'API incompatibles en arrière incrémentent la version principale.

Votre question spécifique ~concerne donc ce schéma Major.Minor.Patch. (De même que l'opérateur caret associé ^.) Vous pouvez utiliser ~pour réduire la gamme de versions que vous êtes prêt à accepter:

  • des modifications ultérieures au niveau du correctif vers la même version mineure ( «corrections de bogues n'affectant pas l'API» ), ou
  • modifications ultérieures de niveau mineur à la même version principale ( "ajouts / modifications d'API rétrocompatibles" )

Par exemple: pour indiquer que vous prendrez toutes les modifications ultérieures au niveau du correctif sur l'arborescence 1.2.x, en commençant par 1.2.0, mais moins de 1.3.0, vous pouvez utiliser:

"angular": "~1.2"
  or:
"angular": "~1.2.0"

Cela vous donne également les mêmes résultats que l'utilisation de la .xsyntaxe:

"angular": "1.2.x"

Mais, vous pouvez utiliser le tilde / ~syntaxe pour être encore plus spécifique: si vous êtes seulement prêt à accepter les changements au niveau du patch commençant par 1.2.4 , mais toujours inférieur à 1.3.0, vous utiliseriez:

"angular": "~1.2.4"

Déplacement vers la gauche, vers la version principale , si vous utilisez ...

"angular": "~1"

... c'est la même chose que ...

"angular": "1.x"
  or:
"angular": "^1.0.0"

... et correspond à toute modification mineure ou au niveau du patch supérieure à 1.0.0 et inférieure à 2.0:

Notez cette dernière variation ci-dessus: elle s'appelle une 'gamme de carets' . Le signe d'insertion ressemble énormément à un >, donc vous seriez excusé de penser que cela signifie "toute version supérieure à 1.0.0". (J'ai certainement glissé là-dessus.) Non!

Les plages de signes d'insertion sont essentiellement utilisées pour dire que vous vous souciez uniquement du chiffre le plus à gauche - généralement la version principale - et que vous autoriserez tous les changements mineurs ou au niveau du patch qui n'affectent pas ce chiffre le plus à gauche. Pourtant, contrairement à une plage tilde qui spécifie une version majeure, les plages caret vous permettent de spécifier un point de départ mineur / correctif précis. Ainsi, tandis ^1.0.0 === ~1qu'une plage de points d'insertion telle que ^1.2.3vous permet de dire que vous prendrez toutes les modifications >=1.2.3 && <2.0.0. On ne pouvait pas faire ça avec une gamme tilde.

Tout cela semble déroutant au début, quand on regarde de près. Mais faites un zoom arrière pendant une seconde et pensez-y de cette façon: le curseur vous permet simplement de dire que vous êtes le plus préoccupé par le chiffre significatif le plus à gauche. Le tilde vous permet de dire que vous êtes le plus préoccupé par le chiffre le plus à droite. Le reste est un détail.

C'est la puissance expressive du tilde et du curseur qui explique pourquoi les gens les utilisent beaucoup plus que la .xsyntaxe plus simple : ils vous laissent simplement faire plus. C'est pourquoi vous verrez souvent le tilde utilisé même là où .xil servirait. Par exemple, voyez npm lui-même: son propre fichier package.json inclut beaucoup de dépendances au ~2.4.0format, plutôt que le 2.4.xformat qu'il pourrait utiliser. En respectant ~, la syntaxe est cohérente tout au long d'une liste de plus de 70 dépendances versionnées, quel que soit le numéro de patch de début acceptable.

Quoi qu'il en soit, SemVer contient encore plus, mais je n'essaierai pas de tout détailler ici. Vérifiez-le dans le fichier Lisez-moi du paquetage node semver . Et assurez-vous d'utiliser la calculatrice de gestion des versions sémantique pendant que vous vous entraînez et essayez de comprendre comment fonctionne SemVer.


RE: Numéros de version non consécutifs: La dernière question d'OP semble être de spécifier les numéros de version / plages non consécutifs (si je l'ai édité de manière équitable). Oui, vous pouvez le faire, en utilisant la double conduite commune « ou » opérateur: ||. Ainsi:

"angular": "1.2 <= 1.2.9 || >2.0.0"

27
Ainsi, ~en particulier, le numéro de patch (troisième) peut être supérieur à celui spécifié, par exemple ~1.2.3est équivalent à >=1.2.3 <1.3.0.
z0r

1
Peut également être utilisé pour le numéro mineur (deuxième), par modifications en ligne ci-dessus.
XML

intéressant, que la documentation SemVer semble également permettre la notation x (qui est beaucoup plus intuitive pour les humains).
Frank Nocke

2
La notation x est intuitive à lire au début, mais beaucoup moins flexible. Par exemple, '1.1.x' === '>=1.1.0' === '~1.1.0'. Le cas 1.1.0 est facile. Mais la notation x ne peut pas être granulaire, comme le peut '>=1.1.4'ou '~1.1.4'. Donc, vous vous retrouvez '1.1.x'à un endroit de votre liste de dépendances et '~2.7.3'à un autre endroit. C'est bien, et cela fonctionne, mais un développeur doit ensuite analyser plusieurs syntaxes pour lire une seule liste. Et, si vous écrivez des packages pour définir la version par programme, vous voulez une seule syntaxe. Et, la plupart des gens veulent empêcher les changements de rupture. Par conséquent, tous les problèmes ont été résolus ~.
XML

1
Hah. Je pense que "grok" est moins géographique que culturel (et peut-être lié à l'âge), @Clonkex. Pour les futurs lecteurs: c'est une référence à Stranger in a Strange Land de Heinlein ...
XML

141

Basé sur semver , vous pouvez utiliser

  • Gammes de trait d'union XYZ - ABC 1.2.3-2.3.4 indique > = 1.2.3 <= 2.3.4

  • Gammes X 1.2.x 1.X 1.2.*

  • Tilde Ranges ~1.2.3 ~1.2 Indique autoriser des modifications au niveau du correctif ou des modifications de version mineures.

  • Plages Caret ^ 1.2.3 ^ 0.2.5 ^ 0.0.4

    Permet les modifications qui ne modifient pas le chiffre non nul le plus à gauche dans le tuple [majeur, mineur, patch]

    • ^1.2.x (signifie> = 1.2.0 <2.0.0)
    • ^0.0.x (signifie> = 0,0,0 <0,1,0)
    • ^0.0 (signifie> = 0,0,0 <0,1,0)

21
Merci pour la réponse simple et facile à lire. Je n'ai pas eu à revenir en arrière ou quoi que ce soit, juste, boum, il y a la réponse. Bravo;)
toddmo

76

Bower utilise la syntaxe semver , mais voici quelques exemples rapides:

Vous pouvez installer une version spécifique:

$ bower install jquery#1.11.1

Vous pouvez utiliser ~ pour spécifier «toute version commençant par ceci»:

$ bower install jquery#~1.11

Vous pouvez spécifier plusieurs exigences de version ensemble:

$ bower install "jquery#<2.0 >1.10"

1
Je suis curieux de savoir comment l'utiliser concrètement. Installation de roulette?
gravidThoughts

Regarder la réponse de @ XMLilley (et les documents semver) `` commencer par '' semble faux, car 1.12, 1.13 serait également correct, tant que la version principale ne monte pas ...
Frank Nocke

13

Vous pouvez également utiliser le latestmot - clé pour installer la version la plus récente disponible:

  "dependencies": {
    "fontawesome": "latest"
  }

1
semver ne le mentionne pas. Où avez-vous établi sa validité? :) Il dit " "*" := >=0.0.0(n'importe quelle version satisfait)" qui est proche mais un peu vague car il ne dit pas spécifiquement le plus récent, donc ce pourrait être le premier qu'il trouve?
GazB

Pour être honnête, ce n'était que des essais et des erreurs - je l'ai essayé et cela a fonctionné! Vous avez peut-être raison de dire que ce n'est pas valide à 100%, mais cela fonctionne.
shacker

7

S'il n'y a pas de numéro de patch, ~équivaut à l'ajouter .xà la version non tilde. S'il y a un numéro de patch, ~autorise tous les numéros de patch> = celui spécifié.

~1     := 1.x
~1.2   := 1.2.x
~1.2.3 := (>=1.2.3 <1.3.0)

Je n'ai pas assez de points pour commenter la réponse acceptée, mais certaines des informations tilde est en désaccord avec le lien semver documentation: "angular": "~1.2"ne pas correspondre à 1.3, 1.4, 1.4.9. Aussi "angular": "~1"et ne"angular": "~1.0" sont pas équivalents. Cela peut être vérifié avec la calculatrice semver npm .

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.