Name Templates¶

Several fields in GoReleaser's config file support templating.

Those fields are often suffixed with _template, but sometimes they may not be. The documentation of each section should be explicit about which fields support templating.

Common Fields¶

On fields that support templating, these fields are always available:

Key	Description
`.ProjectName`	the project name
`.Version`	the version being released¹
`.Branch`	the current git branch
`.PrefixedTag`	the current git tag prefixed with the monorepo config tag prefix (if any)
`.Tag`	the current git tag
`.PrefixedPreviousTag`	the previous git tag prefixed with the monorepo config tag prefix (if any)
`.PreviousTag`	the previous git tag, or empty if no previous tags
`.ShortCommit`	the git commit short hash
`.FullCommit`	the git commit full hash
`.Commit`	the git commit hash (deprecated)
`.CommitDate`	the UTC commit date in RFC 3339 format
`.CommitTimestamp`	the UTC commit date in Unix format
`.GitURL`	the git remote url
`.Major`	the major part of the version²
`.Minor`	the minor part of the version²
`.Patch`	the patch part of the version²
`.Prerelease`	the prerelease part of the version, e.g. `beta`²
`.RawVersion`	composed of `{Major}.{Minor}.{Patch}` ²
`.ReleaseNotes`	the generated release notes, available after the changelog step has been executed
`.IsSnapshot`	`true` if `--snapshot` is set, `false` otherwise
`.IsNightly`	`true` if `--nightly` is set, `false` otherwise
`.Env`	a map with system's environment variables
`.Date`	current UTC date in RFC 3339 format
`.Timestamp`	current UTC time in Unix format
`.ModulePath`	the go module path, as reported by `go list -m`
`incpatch "v1.2.4"`	increments the patch of the given version³
`incminor "v1.2.4"`	increments the minor of the given version³
`incmajor "v1.2.4"`	increments the major of the given version³
`.ReleaseURL`	the current release download url⁴
`.Summary`	the git summary, e.g. `v1.0.0-10-g34f56g3`⁵
`.PrefixedSummary`	the git summary prefixed with the monorepo config tag prefix (if any)
`.TagSubject`	the annotated tag message subject, or the message subject of the commit it points out⁶. Since v1.2.
`.TagContents`	the annotated tag message, or the message of the commit it points out⁷. Since v1.2.
`.TagBody`	the annotated tag message's body, or the message's body of the commit it points out⁷. Since v1.2.
`.Runtime.Goos`	equivalent to `runtime.GOOS`. Since v1.5.
`.Runtime.Goarch`	equivalent to `runtime.GOARCH`. Since v1.5.
`.Artifacts`	the current artifact list. See table bellow for fields. Since v1.16-pro.

Artifacts¶

If you use the .Artifacts field, it evaluates to an artifact.Artifact list. You should be able to use all its fields on each item:

.Name
.Path
.Goos
.Goarch
.Goarm
.Gomips
.Goamd64
.Type
.Extra

GoReleaser Pro

The .Artifacts template variable is GoReleaser Pro feature.

Single-artifact extra fields¶

On fields that are related to a single artifact (e.g., the binary name), you may have some extra fields:

Key	Description
`.Os`	`GOOS`⁸
`.Arch`	`GOARCH`⁸
`.Arm`	`GOARM`⁸
`.Mips`	`GOMIPS`⁸
`.Amd64`	`GOAMD64`⁸
`.Binary`	binary name
`.ArtifactName`	archive name
`.ArtifactPath`	absolute path to artifact
`.ArtifactExt`	binary extension (e.g. `.exe`). Since v1.11.

nFPM extra fields¶

On the nFPM name template field, you can use those extra fields as well:

Key	Description
`.Release`	release from the nfpm config
`.Epoch`	epoch from the nfpm config
`.PackageName`	package the name. Same as `ProjectName` if not overridden.
`.ConventionalFileName`	conventional package file name as provided by nFPM⁹

Functions¶

On all fields, you have these available functions:

Usage	Description
`replace "v1.2" "v" ""`	replaces all matches. See ReplaceAll.
`split "1.2" "."`	split string at separator. See Split. Since v1.11.
`time "01/02/2006"`	current UTC time in the specified format (this is not deterministic, a new time for every call).
`tolower "V1.2"`	makes input string lowercase. See ToLower.
`toupper "v1.2"`	makes input string uppercase. See ToUpper.
`trim " v1.2 "`	removes all leading and trailing white space. See TrimSpace.
`trimprefix "v1.2" "v"`	removes provided leading prefix string, if present. See TrimPrefix.
`trimsuffix "1.2v" "v"`	removes provided trailing suffix string, if present. See TrimSuffix.
`dir .Path`	returns all but the last element of path, typically the path's directory. See Dir.
`abs .ArtifactPath`	returns an absolute representation of path. See Abs.
`filter "text" "regex"`	keeps only the lines matching the given regex, analogous to `grep -E`. Since v1.6.
`reverseFilter "text" "regex"`	keeps only the lines not matching the given regex, analogous to `grep -vE`. Since v1.6.
`title "foo"`	"titlenize" the string using english as language. See Title. Since v1.14.

With all those fields, you may be able to compose the name of your artifacts pretty much the way you want:

example_template: '{{ tolower .ProjectName }}_{{ .Env.USER }}_{{ time "2006" }}'

For example, if you want to add the go version to some artifact:

foo_template: 'foo_{{ .Env.GOVERSION }}'

And then you can run:

GOVERSION_NR=$(go version | awk '{print $3;}') goreleaser

Warning

Note that those are hypothetical examples and the fields foo_template and example_template are not valid GoReleaser configurations.

Custom variables¶

GoReleaser Pro

Custom template variables support is a GoReleaser Pro feature.

You can also declare custom variables. This feature is specially useful with includes, so you can have more generic configuration files.

Usage is as simple as you would expect:

# .goreleaser.yaml
variables:
  description: my project description
  somethingElse: yada yada yada
  empty: ""

And then you can use those fields as {{ .Var.description }}, for example.

The v prefix is stripped, and it might be changed in snapshot and nightly builds. ↩
Assuming Tag is a valid a SemVer, otherwise empty/zeroed. ↩↩↩↩↩
Will panic if not a semantic version. ↩↩↩
Composed of the current SCM's download URL and current tag. For instance, on GitHub, it'll be https://github.com/{owner}/{repo}/releases/tag/{tag}. ↩
It is generated by git describe --dirty --always --tags, the format will be {Tag}-$N-{CommitSHA} ↩
As reported by git tag -l --format='%(contents:subject)' ↩
As reported by git tag -l --format='%(contents)' ↩↩
Might have been replaced by archives.replacements. ↩↩↩↩↩
Please beware: some OSs might have the same names for different ARM versions, for example, for Debian both ARMv6 and ARMv7 are called armhf. Make sure that's not your case otherwise you might end up with colliding names. It also does not handle multiple GOAMD64 versions. ↩