{"id":19850520,"url":"https://github.com/mroth/semverdesc","last_synced_at":"2025-07-11T13:36:00.326Z","repository":{"id":57551920,"uuid":"186054815","full_name":"mroth/semverdesc","owner":"mroth","description":":dart: git describe with semantic version compatible names","archived":false,"fork":false,"pushed_at":"2021-12-12T02:02:10.000Z","size":64,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-12T13:29:57.983Z","etag":null,"topics":["cli","devtools","git","semantic-versioning","semver"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mroth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-05-10T21:10:22.000Z","updated_at":"2021-12-12T02:01:58.000Z","dependencies_parsed_at":"2022-09-26T18:41:40.069Z","dependency_job_id":null,"html_url":"https://github.com/mroth/semverdesc","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mroth%2Fsemverdesc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mroth%2Fsemverdesc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mroth%2Fsemverdesc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mroth%2Fsemverdesc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mroth","download_url":"https://codeload.github.com/mroth/semverdesc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233484528,"owners_count":18683099,"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":["cli","devtools","git","semantic-versioning","semver"],"created_at":"2024-11-12T13:26:28.330Z","updated_at":"2025-01-11T13:13:56.103Z","avatar_url":"https://github.com/mroth.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# git semver-describe :dart:\n\n![Test Status](https://github.com/mroth/semverdesc/workflows/test/badge.svg)\n[![Go Report Card](https://goreportcard.com/badge/github.com/mroth/semverdesc)](https://goreportcard.com/report/github.com/mroth/semverdesc)\n[![GoDoc](https://godoc.org/github.com/mroth/semverdesc?status.svg)](https://godoc.org/github.com/mroth/semverdesc)\n\nExtends `git describe` to return [Semantic Versioning v2.0](https://semver.org)\ncompatible names by default:\n\n```\n$ git describe --tags\nv0.2.1-15-gd71dd50\n\n$ git semver-describe --tags\nv0.2.1+15.gd71dd50\n\n$ git semver-describe --tags --legacy\nv0.2.1-15-gd71dd50\n```\n\n## Usage\n\nFor the most part, this is a drop-in replacement for `git describe`, with nearly\nidentical option syntax.\n\nThe official git-describe has [tons of\noptions](https://git-scm.com/docs/git-describe), a few of which are not\nsupported here, but I believe we have covered the entire subset of options that\nare potentially useful when using git tags for semantic versioning:\n\n```\n$ git semver-describe --help\nusage: git semver-describe [\u003coptions\u003e] [\u003ccommit-ish\u003e]\n   or: git semver-describe [\u003coptions\u003e] --dirty\n\n      --all                       use any ref\n      --tags                      use any tag, even unannotated\n      --long                      always use long format\n      --first-parent              only follow first parent\n      --abbrev \u003cn\u003e                use \u003cn\u003e digits to display SHA-1s (default 7)\n      --exact-match               only output exact matches\n      --candidates \u003cn\u003e            consider \u003cn\u003e most recent tags (default 10)\n      --match \u003cpattern\u003e           only consider tags matching \u003cpattern\u003e\n      --exclude \u003cpattern\u003e         do not consider tags matching \u003cpattern\u003e\n      --dirty \u003cmark\u003e[=\"-dirty\"]   append \u003cmark\u003e on dirty working tree\n      --path \u003cpath\u003e               describe repository at \u003cpath\u003e (default $PWD)\n      --trim \u003cprefix\u003e             trim \u003cprefix\u003e from results\n      --legacy                    format results like normal git describe\n```\n\nThe last three flags: `--path`, `--trim` and `--legacy` are some handy extra\nfeatures unique to semver-describe.\n\n## Installation\n\nDownload from the [Releases] page and put somewhere in your `$PATH`.\n\nHomebrew users can `brew install mroth/tap/git-semver-describe`.\n\n[Releases]: https://github.com/mroth/semverdesc/releases\n\n## API\n\nThere is also a Go library encapsulating a lot of this functionality, for more\ninformation see the [GoDocs](https://godoc.org/github.com/mroth/semverdesc).\n\n## Detailed Discussion\n\n_:warning: Warning: this is likely only interesting to you if really care about\nsemantic versioning..._\n\nFirstly familiarize yourself with actual semver specification, this discussion\nlikely won't make much sense otherwise.\n\n**git semver-describe** essentially takes the following philosophy: only tagged\nrefs are part of semver version precedence (including for pre-release versions),\neverything else goes in the build metadata field.\n\nHow do these strings differ?\n\nHere are some of the current issues in integrating `git describe` with semantic\nversioning git tags:\n\n- Git describe output would increment the pre-release patch version. But\n  \"prelease\" versions come before a specific release. During early development,\n  you don't necessarily know if the next release will be a major/minor/patch\n  release.\n- The output of git describe looks close to valid semver to the naked eye, but\n  does not actually adhere to the specification.\n- Once you tag an actual pre-release version (e.g. ), git describe's output\n  drifts even further off from the specification. See the example below.\n\nConsider the following sequence in both git describe and semver-describe:\n\n| `git semver-describe`   | `git describe`           | comments                        |\n|-------------------------|--------------------------|---------------------------------|\n|                `v0.8.3` |                 `v0.8.3` | TAG: currently released version |\n|     `v0.8.3+1.g1a2b3c4` |     `v0.8.3-1-g1a2b3c4`¹ | one commit later                |\n|     `v0.8.3+2.g2b3c4d5` |      `v0.8.3-2-g2b3c4d5` | two commits later               |\n|            `v0.9.0-rc1` |             `v0.9.0-rc1` | TAG: pre-minor-release          |\n| `v0.9.0-rc1+1.gd3adb33` | `v0.9.0-rc1-1-gd3adb33`² | one commit later                |\n|                `v0.9.0` |                 `v0.9.0` | TAG: minor-release made         |\n\u003csmall\u003e\n\n1. This \"describe\" version is now something that comes _before_ the previous\n   release in semver ordering.\n2. This doesn't parse in SemVer v2.0 at all, but if it did, a typical\n   interpretation would be something that also came before the  previous\n   `v0.9.0` release.\n\n\u003c/small\u003e\n\nIf you were to re-order those commits by semantic versioning precedence, rather\nthan commit order, you would get:\n```\n\n|  git semver-describe    |  git describe            |\n|-------------------------|--------------------------|\n|                 v0.8.3  |       v0.8.3-1-g1a2b3c4* |\n|      v0.8.3+1.g1a2b3c4  |       v0.8.3-2-g2b3c4d5* |\n|      v0.8.3+2.g2b3c4d5  |                  v0.8.3* |\n|             v0.9.0-rc1  |   v0.9.0-rc1-1-gd3adb33* |\n|  v0.9.0-rc1+1.gd3adb33  |              v0.9.0-rc1* |\n|                 v0.9.0  |                  v0.9.0  |\n\n*: Out-of-order: SemVer ordering differs from commit history.\n```\n\n\nThere are some other benefits:\n\n- As a happy coincidence, the `+` character that precedes build metadata in\n  SemVer v2.0 better expresses the situational context possible during a git\n  describe: something that comes *after* a point in history, rather than\n  *before* something to come.\n\n## Integration with various build tools\n\n### Go\n\nConfigure a placeholder variable in your main package.\n\n```go\npackage main\n\nvar (\n    version = \"unknown\"\n)\n```\n\nYou will then override this variable value in your build command:\n\n```shell\n$ VERSION=$(git-semver-describe --tags) go build -ldflags=\"-X main.version=$VERSION\"\n```\n\nOr for another example, using a Makefile:\n\n```makefile\nVERSION := $(shell git-semver-describe --tags --trim=v)\n\nbuild:\n   go build -ldflags=\"-X main.version=${VERSION}\"\n```\n\nFor a more involved example, see this project itself.\n\n## Related Work\n\n- A similar versioning schematic was implemented as a NodeJS library, which\n  looks to function by parsing and wrapping the output from shell commands sent\n  to git: https://www.npmjs.com/package/git-describe.\n- Some relevant discussion on the semver spec itself: semver/semver#106, semver/semver#106, semver/semver#106\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmroth%2Fsemverdesc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmroth%2Fsemverdesc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmroth%2Fsemverdesc/lists"}