github.com/goreleaser/goreleaser@v1.25.1/www/docs/customization/templates.md (about) 1 # Name Templates 2 3 Several fields in GoReleaser's config file support templating. 4 5 Those fields are often suffixed with `_template`, but sometimes they may not 6 be. The documentation of each section should be explicit about which fields 7 support templating. 8 9 ## Common Fields 10 11 In fields that support templates, these fields are always available: 12 13 | Key | Description | 14 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | 15 | `.ProjectName` | the project name | 16 | `.Version` | the version being released[^version-prefix] | 17 | `.Branch` | the current git branch | 18 | `.PrefixedTag` | the current git tag prefixed with the monorepo config tag prefix (if any) | 19 | `.Tag` | the current git tag | 20 | `.PrefixedPreviousTag` | the previous git tag prefixed with the monorepo config tag prefix (if any) | 21 | `.PreviousTag` | the previous git tag, or empty if no previous tags | 22 | `.ShortCommit` | the git commit short hash | 23 | `.FullCommit` | the git commit full hash | 24 | `.Commit` | the git commit hash (deprecated) | 25 | `.CommitDate` | the UTC commit date in RFC 3339 format | 26 | `.CommitTimestamp` | the UTC commit date in Unix format | 27 | `.GitURL` | the git remote url | 28 | `.GitTreeState` | either 'clean' or 'dirty'. Since v1.24 | 29 | `.IsGitClean` | whether or not current git state is clean. Since v1.24 | 30 | `.IsGitDirty` | whether or not current git state is dirty. Since v1.19 | 31 | `.Major` | the major part of the version[^tag-is-semver] | 32 | `.Minor` | the minor part of the version[^tag-is-semver] | 33 | `.Patch` | the patch part of the version[^tag-is-semver] | 34 | `.Prerelease` | the prerelease part of the version, e.g. `beta`[^tag-is-semver] | 35 | `.RawVersion` | composed of `{Major}.{Minor}.{Patch}` [^tag-is-semver] | 36 | `.ReleaseNotes` | the generated release notes, available after the changelog step has been executed | 37 | `.IsDraft` | `true` if `release.draft` is set in the configuration, `false` otherwise. Since v1.17 | 38 | `.IsSnapshot` | `true` if `--snapshot` is set, `false` otherwise | 39 | `.IsNightly` | `true` if `--nightly` is set, `false` otherwise | 40 | `.Env` | a map with system's environment variables | 41 | `.Date` | current UTC date in RFC 3339 format | 42 | `.Now` | current UTC date as `time.Time` struct, allows all `time.Time` functions (e.g. `{{ .Now.Format "2006" }}`) . Since v1.17 | 43 | `.Timestamp` | current UTC time in Unix format | 44 | `.ModulePath` | the go module path, as reported by `go list -m` | 45 | `incpatch "v1.2.4"` | increments the patch of the given version[^panic-if-not-semver] | 46 | `incminor "v1.2.4"` | increments the minor of the given version[^panic-if-not-semver] | 47 | `incmajor "v1.2.4"` | increments the major of the given version[^panic-if-not-semver] | 48 | `.ReleaseURL` | the current release download url[^scm-release-url] | 49 | `.Summary` | the git summary, e.g. `v1.0.0-10-g34f56g3`[^git-summary] | 50 | `.PrefixedSummary` | the git summary prefixed with the monorepo config tag prefix (if any) | 51 | `.TagSubject` | the annotated tag message subject, or the message subject of the commit it points out[^git-tag-subject]. Since v1.2 | 52 | `.TagContents` | the annotated tag message, or the message of the commit it points out[^git-tag-body]. Since v1.2 | 53 | `.TagBody` | the annotated tag message's body, or the message's body of the commit it points out[^git-tag-body]. Since v1.2 | 54 | `.Runtime.Goos` | equivalent to `runtime.GOOS`. Since v1.5 | 55 | `.Runtime.Goarch` | equivalent to `runtime.GOARCH`. Since v1.5 | 56 | `.Artifacts` | the current artifact list. See table below for fields. Since v1.16 (pro) | 57 58 [^version-prefix]: 59 The `v` prefix is stripped, and it might be changed in 60 `snapshot` and `nightly` builds. 61 62 [^tag-is-semver]: Assuming `Tag` is a valid a SemVer, otherwise empty/zeroed. 63 [^panic-if-not-semver]: Will panic if not a semantic version. 64 [^scm-release-url]: 65 Composed of the current SCM's download URL and current tag. 66 For instance, on GitHub, it'll be 67 `https://github.com/{owner}/{repo}/releases/tag/{tag}`. 68 69 [^git-summary]: 70 It is generated by `git describe --dirty --always --tags`, the 71 format will be `{Tag}-$N-{CommitSHA}` 72 73 [^git-tag-subject]: As reported by `git tag -l --format='%(contents:subject)'` 74 [^git-tag-body]: As reported by `git tag -l --format='%(contents)'` 75 76 ## Artifacts 77 78 If you use the `.Artifacts` field, it evaluates to an 79 [`artifact.Artifact` list](https://pkg.go.dev/github.com/goreleaser/goreleaser@main/internal/artifact#Artifact). 80 You should be able to use all its fields on each item: 81 82 - `.Name` 83 - `.Path` 84 - `.Goos` 85 - `.Goarch` 86 - `.Goarm` 87 - `.Gomips` 88 - `.Goamd64` 89 - `.Type` 90 - `.Extra` 91 92 !!! success "GoReleaser Pro" 93 94 The `.Artifacts` template variable is [GoReleaser Pro feature](/pro/). 95 96 ## Single-artifact extra fields 97 98 On fields that are related to a single artifact (e.g., the binary name), you 99 may have some extra fields: 100 101 | Key | Description | 102 | --------------- | ------------------------------------------- | 103 | `.Os` | `GOOS` | 104 | `.Arch` | `GOARCH` | 105 | `.Arm` | `GOARM` | 106 | `.Mips` | `GOMIPS` | 107 | `.Amd64` | `GOAMD64` | 108 | `.Binary` | binary name | 109 | `.ArtifactName` | archive name | 110 | `.ArtifactPath` | absolute path to artifact | 111 | `.ArtifactExt` | binary extension (e.g. `.exe`). Since v1.11 | 112 113 ## nFPM extra fields 114 115 In the nFPM name template field, you can use those extra fields: 116 117 | Key | Description | 118 | ------------------------ | --------------------------------------------------------------- | 119 | `.Release` | release from the nfpm config | 120 | `.Epoch` | epoch from the nfpm config | 121 | `.PackageName` | package the name. Same as `ProjectName` if not overridden. | 122 | `.ConventionalFileName` | conventional package file name as provided by nFPM.[^arm-names] | 123 | `.ConventionalExtension` | conventional package extension as provided by nFPM. Since v1.16 | 124 | `.Format` | package format. Since v1.24 | 125 126 [^arm-names]: 127 Please beware: some OSs might have the same names for different 128 ARM versions, for example, for Debian both ARMv6 and ARMv7 are called `armhf`. 129 Make sure that's not your case otherwise you might end up with colliding 130 names. It also does not handle multiple GOAMD64 versions. 131 132 ## Release body extra fields 133 134 In the `release.body` field, you can use these extra fields: 135 136 | Key | Description | 137 | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | 138 | `.Checksums` | the current checksum file contents, or a map of filename/checksum contents if `checksum.split` is set. Only available in the release body. Since v1.19 | 139 140 ## Functions 141 142 On all fields, you have these available functions: 143 144 | Usage | Description | 145 | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | 146 | `replace "v1.2" "v" ""` | replaces all matches. See [ReplaceAll](https://golang.org/pkg/strings/#ReplaceAll). | 147 | `split "1.2" "."` | split string at separator. See [Split](https://golang.org/pkg/strings/#Split). Since v1.11 | 148 | `time "01/02/2006"` | current UTC time in the specified format (this is not deterministic, a new time for every call). | 149 | `contains "foobar" "foo"` | checks whether the first string contains the second. See [ToLower](https://golang.org/pkg/strings/#Contains). Since 1.24 | 150 | `tolower "V1.2"` | makes input string lowercase. See [ToLower](https://golang.org/pkg/strings/#ToLower). | 151 | `toupper "v1.2"` | makes input string uppercase. See [ToUpper](https://golang.org/pkg/strings/#ToUpper). | 152 | `trim " v1.2 "` | removes all leading and trailing white space. See [TrimSpace](https://golang.org/pkg/strings/#TrimSpace). | 153 | `trimprefix "v1.2" "v"` | removes provided leading prefix string, if present. See [TrimPrefix](https://golang.org/pkg/strings/#TrimPrefix). | 154 | `trimsuffix "1.2v" "v"` | removes provided trailing suffix string, if present. See [TrimSuffix](https://pkg.go.dev/strings#TrimSuffix). | 155 | `dir .Path` | returns all but the last element of path, typically the path's directory. See [Dir](https://golang.org/pkg/path/filepath/#Dir). | 156 | `base .Path` | returns the last element of path. See [Base](https://golang.org/pkg/path/filepath/#Base). Since v1.16 | 157 | `abs .ArtifactPath` | returns an absolute representation of path. See [Abs](https://golang.org/pkg/path/filepath/#Abs). | 158 | `filter "text" "regex"` | keeps only the lines matching the given regex, analogous to `grep -E`. Since v1.6 | 159 | `reverseFilter "text" "regex"` | keeps only the lines **not** matching the given regex, analogous to `grep -vE`. Since v1.6 | 160 | `title "foo"` | "titlenize" the string using english as language. See [Title](https://pkg.go.dev/golang.org/x/text/cases#Title). Since v1.14 | 161 | `mdv2escape "foo"` | escape characters according to MarkdownV2, especially useful in the Telegram integration. Since v1.19 | 162 | `envOrDefault "NAME" "value"` | either gets the value of the given environment variable, or the given default. Since v1.19 | 163 | `$m := map "KEY" "VALUE"` | creates a map from a list of key and value pairs. Both keys and values must be of type `string`. Since v1.21 | 164 | `indexOrDefault $m "KEY" "value"` | either gets the value of the given key or the given default value from the given map. Since v1.21 | 165 166 With all those fields, you may be able to compose the name of your artifacts 167 pretty much the way you want: 168 169 ```yaml 170 example_template: '{{ tolower .ProjectName }}_{{ .Env.USER }}_{{ time "2006" }}' 171 ``` 172 173 For example, if you want to add the go version to some artifact: 174 175 ```yaml 176 foo_template: "foo_{{ .Env.GOVERSION }}" 177 ``` 178 179 And then you can run: 180 181 ```sh 182 GOVERSION_NR=$(go version | awk '{print $3;}') goreleaser 183 ``` 184 185 !!! warning 186 187 Note that those are hypothetical examples and the fields `foo_template` and 188 `example_template` are not valid GoReleaser configurations. 189 190 ## Custom variables 191 192 !!! success "GoReleaser Pro" 193 194 Custom template variables support is a [GoReleaser Pro feature](/pro/). 195 196 You can also declare custom variables. This feature is specially useful with 197 [includes](/customization/includes/), so you can have more generic configuration 198 files. 199 200 Usage is as simple as you would expect: 201 202 ```yaml 203 # .goreleaser.yaml 204 variables: 205 description: my project description 206 somethingElse: yada yada yada 207 empty: "" 208 ``` 209 210 And then you can use those fields as `{{ .Var.description }}`, for example.