goreleaser/www/docs/customization/templates.md

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.

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

Key	Description
.ProjectName	the project name
.Version	the version being released1
.Branch	the current git branch
.PrefixedTag	the current git tag prefixed with the monorepo config tag prefix (if any)
.Tag	the current git tag
.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 version2
.Minor	the minor part of the version2
.Patch	the patch part of the version2
.Prerelease	the prerelease part of the version, e.g. beta2
.RawVersion	composed of {Major}.{Minor}.{Patch} 2
.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 version3
incminor "v1.2.4"	increments the minor of the given version3
incmajor "v1.2.4"	increments the major of the given version3
.ReleaseURL	the current release download url4

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

Key	Description
.Os	GOOS5
.Arch	GOARCH5
.Arm	GOARM5
.Mips	GOMIPS5
.Binary	binary name
.ArtifactName	archive name
.ArtifactPath	absolute path to artifact

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.

On all fields, you have these available functions:

Usage	Description
replace "v1.2" "v" ""	replaces all matches. See ReplaceAll
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

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

!!! success "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 config files.

Usage is as simple as you would expect:

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

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

!!! warning You won't be allowed to override GoReleaser "native" fields.

---

1. The v prefix is stripped and it might be changed in snapshot and nightly builds. ↩︎

2. Assuming Tag is a valid a SemVer, otherwise empty/zeroed. ↩︎

3. Will panic if not a semantic version. ↩︎

4. Composed from the current SCM's download URL and current tag. For instance, on GitHub, it'll be https://github.com/{owner}/{repo}/releases/tag/{tag}. ↩︎

5. Might have been replaced by archives.replacements. ↩︎