github.com/mdomke/git-semver@v1.0.1-0.20200406193518-c0566816580f/README.md (about) 1 [](https://travis-ci.org/mdomke/git-semver) 2 [](https://codecov.io/gh/mdomke/git-semver) 3 [](https://hub.docker.com/r/mdomke/git-semver) 4  5  6 [](https://goreportcard.com/report/github.com/mdomke/git-semver) 7 8 # Semantic Versioning with git tags 9 10 Software should be versioned in order to be able to identify a certain 11 feature set or to know when a specific bug has been fixed. It is a good 12 practice to use [Sementic Versioning](https://semver.org/) (SemVer) in 13 order to attach a meaning to a version number or the change thereof. 14 15 [git](https://git-scm.com/) allows you to conveniently reference a certain 16 state of your code through the usage of tags. Tags can have an arbitrary 17 identifier, so that it seems a naturaly choice of using them for versioning. 18 19 ## Version tags 20 21 A semantic version consists of three dot-separated parts `<major>.<minor>.<patch>` 22 and this should be the name that you give to a tag. Optionally you can prepend 23 the letter `v` if your language specific tooling requires it. It is also possible 24 to attach a pre-release identifier to a version e.g. for a release candidate. This 25 identifier is separated with hyphen from the core version component. A valid version 26 tag would be, e.g. `1.2.3`, `v2.3.0`, `1.1.0-rc3`. 27 28 ```sh 29 $ git tag v2.0.0-rc1 30 ``` 31 32 So for a tagged commit we would know which version to assign to our software, but 33 which version should we use for not tagged commits? We can use `git describe` to 34 get a unique identifier based on the last tagged commit. 35 36 ```sh 37 $ git describe --tags 38 3.5.1-22-gbaf822dd5 39 ``` 40 41 This is the 22nd commit after the tag `3.5.1` with the abbreviated commit hash `gbaf822dd5`. 42 Sadly this identifier has two drawbacks. 43 44 1. It's not compliant to SemVer, because there are multiple hyphens after the core version. 45 See the [BNF specifiction](https://github.com/semver/semver/blob/master/semver.md#backusnaur-form-grammar-for-valid-semver-versions) 46 47 2. It doesn't allow proper sorting of versions, because the pre-release identifier would 48 make the version smaller than the tagged version, even though it has several commits build 49 on top of that version. 50 51 ## git-semver 52 53 `git-semver` parses the output of `git describe` and derives a proper SemVer compliant 54 version from it. E.g.: 55 56 ``` 57 3.5.1-22-gbaf822dd5 -> 3.5.2-dev22+gbaf822dd5 58 4.2.0-rc3-5-fcf2c8f -> 4.2.0-rc4.dev5-fcf2c8f 59 ``` 60 61 It will attach a pre-release tag of the form `devN`, where `N` is the number of commits 62 since the last commit, and the commit hash as build-metadata. Additionally the patch level 63 component will be incremented in case of a pre-release-version. If the last tag itself 64 contains a pre-release-identifier of the form `(alpha|beta|rc)\d+`, that identifier will 65 be incremnted instead of the patch-level. 66 67 ### Formatting 68 69 The output of `git-semver` can be controlled with the `-format` option or one of it shorthand 70 companions as described [here](#command-line-options). The format string can include the following 71 characters 72 73 | Format char | Description | 74 | --- | --- | 75 | `x` | Major version | 76 | `y` | Minor version | 77 | `z` | Patch version | 78 | `p` | Pre-release version | 79 | `m` | Metadata | 80 81 The format chars `x`, `y` and `z` are separted with a dot, `p` with a hyphen and `m` with a 82 plus character. A valid format string is e.g.: `x.y+m` 83 84 ### Command line options 85 86 The output and parsing of `git-semver` can be controlled with the following options. 87 88 | Name | Description | 89 | --- | --- | 90 | `-format` | Format string as described [here](#formatting) | 91 | `-no-minor` | Exclude minor version and all following components | 92 | `-no-patch` | Exclude patch version and all following components | 93 | `-no-pre` | Exclude pre-release version and all following components | 94 | `-no-meta`/`-no-hash` | Exclude build metadata | 95 | `-prefix` | Prefix string for version e.g.: v | 96 | `-set-meta` | Set buildmeta to this value | 97 98 99 #### Examples 100 101 ```sh 102 $ git-semver 103 3.5.2-dev22+gbaf822dd5 104 105 # Exclude build metadata 106 $ git-semver -no-meta 107 3.5.2-dev22 108 109 # Only major and minor version 110 $ git-semver -no-patch 111 3.5 112 113 $ git-semver -prefix v -no-hash 114 v3.5.2 115 116 $ git-semver -set-meta custom 117 3.5.2+custom 118 ``` 119 120 ## Installation 121 122 Currently `git-semver` can be installed with `go get` 123 124 ```sh 125 $ go get github.com/mdomke/git-semver 126 ``` 127 128 ## Docker usage 129 130 You can also use `git-semver` as a docker-container. E.g. 131 132 ```sh 133 docker run --rm -v `pwd`:/git-semver mdomke/git-semver 134 ```