{"id":13492297,"url":"https://github.com/Masterminds/semver","last_synced_at":"2025-03-28T09:34:11.993Z","repository":{"id":38956527,"uuid":"43896280","full_name":"Masterminds/semver","owner":"Masterminds","description":"Work with Semantic Versions in Go","archived":false,"fork":false,"pushed_at":"2024-08-27T21:34:16.000Z","size":1491,"stargazers_count":1206,"open_issues_count":25,"forks_count":150,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-10-29T11:10:00.508Z","etag":null,"topics":["caret","comparison","constraints","go","golang","semantic-versions","semver","tilde"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Masterminds.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-08T14:57:25.000Z","updated_at":"2024-10-26T14:03:26.000Z","dependencies_parsed_at":"2024-02-19T19:08:30.717Z","dependency_job_id":"d3398710-1b14-46a7-b904-303775d8b47c","html_url":"https://github.com/Masterminds/semver","commit_stats":{"total_commits":163,"total_committers":29,"mean_commits":5.620689655172414,"dds":"0.26993865030674846","last_synced_commit":"e6e3d4d3cb1073f0ab8fb3d4be0869d1687b75f9"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Masterminds%2Fsemver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Masterminds%2Fsemver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Masterminds%2Fsemver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Masterminds%2Fsemver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Masterminds","download_url":"https://codeload.github.com/Masterminds/semver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246004460,"owners_count":20708222,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["caret","comparison","constraints","go","golang","semantic-versions","semver","tilde"],"created_at":"2024-07-31T19:01:04.803Z","updated_at":"2025-03-28T09:34:11.711Z","avatar_url":"https://github.com/Masterminds.png","language":"Go","readme":"# SemVer\n\nThe `semver` package provides the ability to work with [Semantic Versions](http://semver.org) in Go. Specifically it provides the ability to:\n\n* Parse semantic versions\n* Sort semantic versions\n* Check if a semantic version fits within a set of constraints\n* Optionally work with a `v` prefix\n\n[![Stability:\nActive](https://masterminds.github.io/stability/active.svg)](https://masterminds.github.io/stability/active.html)\n[![](https://github.com/Masterminds/semver/workflows/Tests/badge.svg)](https://github.com/Masterminds/semver/actions)\n[![GoDoc](https://img.shields.io/static/v1?label=godoc\u0026message=reference\u0026color=blue)](https://pkg.go.dev/github.com/Masterminds/semver/v3)\n[![Go Report Card](https://goreportcard.com/badge/github.com/Masterminds/semver)](https://goreportcard.com/report/github.com/Masterminds/semver)\n\n## Package Versions\n\nNote, import `github.com/Masterminds/semver/v3` to use the latest version.\n\nThere are three major versions fo the `semver` package.\n\n* 3.x.x is the stable and active version. This version is focused on constraint\n  compatibility for range handling in other tools from other languages. It has\n  a similar API to the v1 releases. The development of this version is on the master\n  branch. The documentation for this version is below.\n* 2.x was developed primarily for [dep](https://github.com/golang/dep). There are\n  no tagged releases and the development was performed by [@sdboyer](https://github.com/sdboyer).\n  There are API breaking changes from v1. This version lives on the [2.x branch](https://github.com/Masterminds/semver/tree/2.x).\n* 1.x.x is the original release. It is no longer maintained. You should use the\n  v3 release instead. You can read the documentation for the 1.x.x release\n  [here](https://github.com/Masterminds/semver/blob/release-1/README.md).\n\n## Parsing Semantic Versions\n\nThere are two functions that can parse semantic versions. The `StrictNewVersion`\nfunction only parses valid version 2 semantic versions as outlined in the\nspecification. The `NewVersion` function attempts to coerce a version into a\nsemantic version and parse it. For example, if there is a leading v or a version\nlisted without all 3 parts (e.g. `v1.2`) it will attempt to coerce it into a valid\nsemantic version (e.g., 1.2.0). In both cases a `Version` object is returned\nthat can be sorted, compared, and used in constraints.\n\nWhen parsing a version an error is returned if there is an issue parsing the\nversion. For example,\n\n    v, err := semver.NewVersion(\"1.2.3-beta.1+build345\")\n\nThe version object has methods to get the parts of the version, compare it to\nother versions, convert the version back into a string, and get the original\nstring. Getting the original string is useful if the semantic version was coerced\ninto a valid form.\n\n## Sorting Semantic Versions\n\nA set of versions can be sorted using the `sort` package from the standard library.\nFor example,\n\n```go\nraw := []string{\"1.2.3\", \"1.0\", \"1.3\", \"2\", \"0.4.2\",}\nvs := make([]*semver.Version, len(raw))\nfor i, r := range raw {\n    v, err := semver.NewVersion(r)\n    if err != nil {\n        t.Errorf(\"Error parsing version: %s\", err)\n    }\n\n    vs[i] = v\n}\n\nsort.Sort(semver.Collection(vs))\n```\n\n## Checking Version Constraints\n\nThere are two methods for comparing versions. One uses comparison methods on\n`Version` instances and the other uses `Constraints`. There are some important\ndifferences to notes between these two methods of comparison.\n\n1. When two versions are compared using functions such as `Compare`, `LessThan`,\n   and others it will follow the specification and always include pre-releases\n   within the comparison. It will provide an answer that is valid with the\n   comparison section of the spec at https://semver.org/#spec-item-11\n2. When constraint checking is used for checks or validation it will follow a\n   different set of rules that are common for ranges with tools like npm/js\n   and Rust/Cargo. This includes considering pre-releases to be invalid if the\n   ranges does not include one. If you want to have it include pre-releases a\n   simple solution is to include `-0` in your range.\n3. Constraint ranges can have some complex rules including the shorthand use of\n   ~ and ^. For more details on those see the options below.\n\nThere are differences between the two methods or checking versions because the\ncomparison methods on `Version` follow the specification while comparison ranges\nare not part of the specification. Different packages and tools have taken it\nupon themselves to come up with range rules. This has resulted in differences.\nFor example, npm/js and Cargo/Rust follow similar patterns while PHP has a\ndifferent pattern for ^. The comparison features in this package follow the\nnpm/js and Cargo/Rust lead because applications using it have followed similar\npatters with their versions.\n\nChecking a version against version constraints is one of the most featureful\nparts of the package.\n\n```go\nc, err := semver.NewConstraint(\"\u003e= 1.2.3\")\nif err != nil {\n    // Handle constraint not being parsable.\n}\n\nv, err := semver.NewVersion(\"1.3\")\nif err != nil {\n    // Handle version not being parsable.\n}\n// Check if the version meets the constraints. The variable a will be true.\na := c.Check(v)\n```\n\n### Basic Comparisons\n\nThere are two elements to the comparisons. First, a comparison string is a list\nof space or comma separated AND comparisons. These are then separated by || (OR)\ncomparisons. For example, `\"\u003e= 1.2 \u003c 3.0.0 || \u003e= 4.2.3\"` is looking for a\ncomparison that's greater than or equal to 1.2 and less than 3.0.0 or is\ngreater than or equal to 4.2.3.\n\nThe basic comparisons are:\n\n* `=`: equal (aliased to no operator)\n* `!=`: not equal\n* `\u003e`: greater than\n* `\u003c`: less than\n* `\u003e=`: greater than or equal to\n* `\u003c=`: less than or equal to\n\n### Working With Prerelease Versions\n\nPre-releases, for those not familiar with them, are used for software releases\nprior to stable or generally available releases. Examples of pre-releases include\ndevelopment, alpha, beta, and release candidate releases. A pre-release may be\na version such as `1.2.3-beta.1` while the stable release would be `1.2.3`. In the\norder of precedence, pre-releases come before their associated releases. In this\nexample `1.2.3-beta.1 \u003c 1.2.3`.\n\nAccording to the Semantic Version specification, pre-releases may not be\nAPI compliant with their release counterpart. It says,\n\n\u003e A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version.\n\nSemVer's comparisons using constraints without a pre-release comparator will skip\npre-release versions. For example, `\u003e=1.2.3` will skip pre-releases when looking\nat a list of releases while `\u003e=1.2.3-0` will evaluate and find pre-releases.\n\nThe reason for the `0` as a pre-release version in the example comparison is\nbecause pre-releases can only contain ASCII alphanumerics and hyphens (along with\n`.` separators), per the spec. Sorting happens in ASCII sort order, again per the\nspec. The lowest character is a `0` in ASCII sort order\n(see an [ASCII Table](http://www.asciitable.com/))\n\nUnderstanding ASCII sort ordering is important because A-Z comes before a-z. That\nmeans `\u003e=1.2.3-BETA` will return `1.2.3-alpha`. What you might expect from case\nsensitivity doesn't apply here. This is due to ASCII sort ordering which is what\nthe spec specifies.\n\n### Hyphen Range Comparisons\n\nThere are multiple methods to handle ranges and the first is hyphens ranges.\nThese look like:\n\n* `1.2 - 1.4.5` which is equivalent to `\u003e= 1.2 \u003c= 1.4.5`\n* `2.3.4 - 4.5` which is equivalent to `\u003e= 2.3.4 \u003c= 4.5`\n\nNote that `1.2-1.4.5` without whitespace is parsed completely differently; it's\nparsed as a single constraint `1.2.0` with _prerelease_ `1.4.5`.\n\n### Wildcards In Comparisons\n\nThe `x`, `X`, and `*` characters can be used as a wildcard character. This works\nfor all comparison operators. When used on the `=` operator it falls\nback to the patch level comparison (see tilde below). For example,\n\n* `1.2.x` is equivalent to `\u003e= 1.2.0, \u003c 1.3.0`\n* `\u003e= 1.2.x` is equivalent to `\u003e= 1.2.0`\n* `\u003c= 2.x` is equivalent to `\u003c 3`\n* `*` is equivalent to `\u003e= 0.0.0`\n\n### Tilde Range Comparisons (Patch)\n\nThe tilde (`~`) comparison operator is for patch level ranges when a minor\nversion is specified and major level changes when the minor number is missing.\nFor example,\n\n* `~1.2.3` is equivalent to `\u003e= 1.2.3, \u003c 1.3.0`\n* `~1` is equivalent to `\u003e= 1, \u003c 2`\n* `~2.3` is equivalent to `\u003e= 2.3, \u003c 2.4`\n* `~1.2.x` is equivalent to `\u003e= 1.2.0, \u003c 1.3.0`\n* `~1.x` is equivalent to `\u003e= 1, \u003c 2`\n\n### Caret Range Comparisons (Major)\n\nThe caret (`^`) comparison operator is for major level changes once a stable\n(1.0.0) release has occurred. Prior to a 1.0.0 release the minor versions acts\nas the API stability level. This is useful when comparisons of API versions as a\nmajor change is API breaking. For example,\n\n* `^1.2.3` is equivalent to `\u003e= 1.2.3, \u003c 2.0.0`\n* `^1.2.x` is equivalent to `\u003e= 1.2.0, \u003c 2.0.0`\n* `^2.3` is equivalent to `\u003e= 2.3, \u003c 3`\n* `^2.x` is equivalent to `\u003e= 2.0.0, \u003c 3`\n* `^0.2.3` is equivalent to `\u003e=0.2.3 \u003c0.3.0`\n* `^0.2` is equivalent to `\u003e=0.2.0 \u003c0.3.0`\n* `^0.0.3` is equivalent to `\u003e=0.0.3 \u003c0.0.4`\n* `^0.0` is equivalent to `\u003e=0.0.0 \u003c0.1.0`\n* `^0` is equivalent to `\u003e=0.0.0 \u003c1.0.0`\n\n## Validation\n\nIn addition to testing a version against a constraint, a version can be validated\nagainst a constraint. When validation fails a slice of errors containing why a\nversion didn't meet the constraint is returned. For example,\n\n```go\nc, err := semver.NewConstraint(\"\u003c= 1.2.3, \u003e= 1.4\")\nif err != nil {\n    // Handle constraint not being parseable.\n}\n\nv, err := semver.NewVersion(\"1.3\")\nif err != nil {\n    // Handle version not being parseable.\n}\n\n// Validate a version against a constraint.\na, msgs := c.Validate(v)\n// a is false\nfor _, m := range msgs {\n    fmt.Println(m)\n\n    // Loops over the errors which would read\n    // \"1.3 is greater than 1.2.3\"\n    // \"1.3 is less than 1.4\"\n}\n```\n\n## Contribute\n\nIf you find an issue or want to contribute please file an [issue](https://github.com/Masterminds/semver/issues)\nor [create a pull request](https://github.com/Masterminds/semver/pulls).\n\n## Security\n\nSecurity is an important consideration for this project. The project currently\nuses the following tools to help discover security issues:\n\n* [CodeQL](https://github.com/Masterminds/semver)\n* [gosec](https://github.com/securego/gosec)\n* Daily Fuzz testing\n\nIf you believe you have found a security vulnerability you can privately disclose\nit through the [GitHub security page](https://github.com/Masterminds/semver/security).\n","funding_links":[],"categories":["开源类库","Misc","Go","Open source library","Repositories"],"sub_categories":["未归类","Not Categorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMasterminds%2Fsemver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMasterminds%2Fsemver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMasterminds%2Fsemver/lists"}