From d510abcd5e922ba0ddbc35f1867fc35f5a8e0103 Mon Sep 17 00:00:00 2001 From: Carlos Alexandro Becker Date: Mon, 4 Sep 2023 14:12:01 +0000 Subject: [PATCH] docs: improve docs Signed-off-by: Carlos Alexandro Becker --- www/docs/customization/archive.md | 6 +- www/docs/customization/git.md | 24 ++++- www/docs/customization/monorepo.md | 4 +- www/docs/customization/nfpm.md | 2 +- www/docs/customization/templates.md | 140 ++++++++++++++-------------- www/docs/customization/upx.md | 2 +- 6 files changed, 100 insertions(+), 78 deletions(-) diff --git a/www/docs/customization/archive.md b/www/docs/customization/archive.md index c5632b6070e..1440729bc1d 100644 --- a/www/docs/customization/archive.md +++ b/www/docs/customization/archive.md @@ -136,14 +136,14 @@ archives: # # Default: copied from the source file info: - # Templateable (since v1.14.0) + # Templateable (since v1.14) owner: root - # Templateable (since v1.14.0) + # Templateable (since v1.14) group: root # Must be in time.RFC3339Nano format. - # Templateable (since v1.14.0) + # Templateable (since v1.14) mtime: "{{ .CommitDate }}" # File mode. diff --git a/www/docs/customization/git.md b/www/docs/customization/git.md index 289a42497c1..868472510a6 100644 --- a/www/docs/customization/git.md +++ b/www/docs/customization/git.md @@ -1,6 +1,6 @@ # Git -> Since v1.14.0. +> Since v1.14 This allows you to change the behavior of some Git commands. @@ -29,3 +29,25 @@ git: - nightly - "{{.Env.FOO}}.*" ``` + +## Semver sorting + +> Since v1.21 (pro) + +This allows you to sort tags by semver: + +```yaml +# .goreleaser.yml +git: + tag_sort: semver +``` + +It'll parse all tags, ignoring non-semver-compatible tags, and sort from newest +to oldest, so the latest tag is returned. + +This has the effect of sorting non-pre-release tags before pre-release ones, +which is different from what other git sorting options might give you. + +!!! success "GoReleaser Pro" + + Semver sorting is a [GoReleaser Pro feature](/pro/). diff --git a/www/docs/customization/monorepo.md b/www/docs/customization/monorepo.md index df4086e890c..3c4a3cacdbb 100644 --- a/www/docs/customization/monorepo.md +++ b/www/docs/customization/monorepo.md @@ -1,6 +1,7 @@ # Monorepo !!! success "GoReleaser Pro" + The monorepo support is a [GoReleaser Pro feature](/pro/). If you want to use GoReleaser within a monorepo and use tag prefixes to mark @@ -12,7 +13,7 @@ You project falls into either one of these categories: 1. tags are like `subproject1/v1.2.3` and `subproject2/v1.2.3`; 1. tags are like `@user/thing@v1.2.3` (for a NPM package, for example) - and `v1.2.3` for the rest of the (Go) code. + and `v1.2.3` for the rest of the (Go) code. ## Usage @@ -54,7 +55,6 @@ Then, the following is different from a "regular" run: The rest of the release process should work as usual. - ### Category 2 You'll need to create a `.goreleaser.yaml` for your Go code in the root of the diff --git a/www/docs/customization/nfpm.md b/www/docs/customization/nfpm.md index e0f721e5f14..caa1bbf55a9 100644 --- a/www/docs/customization/nfpm.md +++ b/www/docs/customization/nfpm.md @@ -260,7 +260,7 @@ nfpms: # Keys are the possible targets during the installation process # Values are the paths to the scripts which will be executed. # - # Templates: allowed (since v1.20). + # Templates: allowed (since v1.20) scripts: preinstall: "scripts/preinstall.sh" postinstall: "scripts/postinstall.sh" diff --git a/www/docs/customization/templates.md b/www/docs/customization/templates.md index 37910e67355..75cc5874569 100644 --- a/www/docs/customization/templates.md +++ b/www/docs/customization/templates.md @@ -10,48 +10,48 @@ support templating. In fields that support templates, these fields are always available: -| Key | Description | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------- | -| `.ProjectName` | the project name | -| `.Version` | the version being released[^version-prefix] | -| `.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 | -| `.IsGitDirty` | whether or not current git state is dirty. Since v1.19. | -| `.Major` | the major part of the version[^tag-is-semver] | -| `.Minor` | the minor part of the version[^tag-is-semver] | -| `.Patch` | the patch part of the version[^tag-is-semver] | -| `.Prerelease` | the prerelease part of the version, e.g. `beta`[^tag-is-semver] | -| `.RawVersion` | composed of `{Major}.{Minor}.{Patch}` [^tag-is-semver] | -| `.ReleaseNotes` | the generated release notes, available after the changelog step has been executed | -| `.IsDraft` | `true` if `release.draft` is set in the configuration, `false` otherwise. Since v1.17. | -| `.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 | -| `.Now` | current UTC date as `time.Time` struct, allows all `time.Time` functions (e.g. `{{ .Now.Format "2006" }}`) . Since v1.17. | -| `.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[^panic-if-not-semver] | -| `incminor "v1.2.4"` | increments the minor of the given version[^panic-if-not-semver] | -| `incmajor "v1.2.4"` | increments the major of the given version[^panic-if-not-semver] | -| `.ReleaseURL` | the current release download url[^scm-release-url] | -| `.Summary` | the git summary, e.g. `v1.0.0-10-g34f56g3`[^git-summary] | -| `.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[^git-tag-subject]. Since v1.2. | -| `.TagContents` | the annotated tag message, or the message of the commit it points out[^git-tag-body]. Since v1.2. | -| `.TagBody` | the annotated tag message's body, or the message's body of the commit it points out[^git-tag-body]. 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. | +| Key | Description | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| `.ProjectName` | the project name | +| `.Version` | the version being released[^version-prefix] | +| `.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 | +| `.IsGitDirty` | whether or not current git state is dirty. Since v1.19 | +| `.Major` | the major part of the version[^tag-is-semver] | +| `.Minor` | the minor part of the version[^tag-is-semver] | +| `.Patch` | the patch part of the version[^tag-is-semver] | +| `.Prerelease` | the prerelease part of the version, e.g. `beta`[^tag-is-semver] | +| `.RawVersion` | composed of `{Major}.{Minor}.{Patch}` [^tag-is-semver] | +| `.ReleaseNotes` | the generated release notes, available after the changelog step has been executed | +| `.IsDraft` | `true` if `release.draft` is set in the configuration, `false` otherwise. Since v1.17 | +| `.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 | +| `.Now` | current UTC date as `time.Time` struct, allows all `time.Time` functions (e.g. `{{ .Now.Format "2006" }}`) . Since v1.17 | +| `.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[^panic-if-not-semver] | +| `incminor "v1.2.4"` | increments the minor of the given version[^panic-if-not-semver] | +| `incmajor "v1.2.4"` | increments the major of the given version[^panic-if-not-semver] | +| `.ReleaseURL` | the current release download url[^scm-release-url] | +| `.Summary` | the git summary, e.g. `v1.0.0-10-g34f56g3`[^git-summary] | +| `.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[^git-tag-subject]. Since v1.2 | +| `.TagContents` | the annotated tag message, or the message of the commit it points out[^git-tag-body]. Since v1.2 | +| `.TagBody` | the annotated tag message's body, or the message's body of the commit it points out[^git-tag-body]. 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) | [^version-prefix]: The `v` prefix is stripped, and it might be changed in @@ -96,29 +96,29 @@ You should be able to use all its fields on each item: 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. | +| 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 In the nFPM name template field, you can use those extra fields: -| 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.[^arm-names] | -| `.ConventionalExtension` | conventional package extension as provided by nFPM. Since v1.16. | +| 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.[^arm-names] | +| `.ConventionalExtension` | conventional package extension as provided by nFPM. Since v1.16 | [^arm-names]: Please beware: some OSs might have the same names for different @@ -130,9 +130,9 @@ In the nFPM name template field, you can use those extra fields: In the `release.body` field, you can use these extra fields: -| Key | Description | -| ------------ | ------------------------------------------------------------------------------------ | -| `.Checksums` | the current checksum file contents. Only available in the release body. Since v1.19. | +| Key | Description | +| ------------ | ----------------------------------------------------------------------------------- | +| `.Checksums` | the current checksum file contents. Only available in the release body. Since v1.19 | ## Functions @@ -141,7 +141,7 @@ On all fields, you have these available functions: | Usage | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | `replace "v1.2" "v" ""` | replaces all matches. See [ReplaceAll](https://golang.org/pkg/strings/#ReplaceAll). | -| `split "1.2" "."` | split string at separator. See [Split](https://golang.org/pkg/strings/#Split). Since v1.11. | +| `split "1.2" "."` | split string at separator. See [Split](https://golang.org/pkg/strings/#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](https://golang.org/pkg/strings/#ToLower). | | `toupper "v1.2"` | makes input string uppercase. See [ToUpper](https://golang.org/pkg/strings/#ToUpper). | @@ -149,13 +149,13 @@ On all fields, you have these available functions: | `trimprefix "v1.2" "v"` | removes provided leading prefix string, if present. See [TrimPrefix](https://golang.org/pkg/strings/#TrimPrefix). | | `trimsuffix "1.2v" "v"` | removes provided trailing suffix string, if present. See [TrimSuffix](https://pkg.go.dev/strings#TrimSuffix). | | `dir .Path` | returns all but the last element of path, typically the path's directory. See [Dir](https://golang.org/pkg/path/filepath/#Dir). | -| `base .Path` | returns the last element of path. See [Base](https://golang.org/pkg/path/filepath/#Base). Since v1.16. | +| `base .Path` | returns the last element of path. See [Base](https://golang.org/pkg/path/filepath/#Base). Since v1.16 | | `abs .ArtifactPath` | returns an absolute representation of path. See [Abs](https://golang.org/pkg/path/filepath/#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](https://pkg.go.dev/golang.org/x/text/cases#Title). Since v1.14. | -| `mdv2escape "foo"` | escape characters according to MarkdownV2, especially useful in the Telegram integration. Since v1.19. | -| `envOrDefault "NAME" "value"` | either gets the value of the given environment variable, or the given default. Since v1.19. | +| `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](https://pkg.go.dev/golang.org/x/text/cases#Title). Since v1.14 | +| `mdv2escape "foo"` | escape characters according to MarkdownV2, especially useful in the Telegram integration. Since v1.19 | +| `envOrDefault "NAME" "value"` | either gets the value of the given environment variable, or the given default. Since v1.19 | With all those fields, you may be able to compose the name of your artifacts pretty much the way you want: diff --git a/www/docs/customization/upx.md b/www/docs/customization/upx.md index 30daf97e716..b0de80466e5 100644 --- a/www/docs/customization/upx.md +++ b/www/docs/customization/upx.md @@ -24,7 +24,7 @@ and now UPX has its own configuration section: upx: - # Whether to enable it or not. # - # Templates: allowed (since v1.21). + # Templates: allowed (since v1.21) enabled: true # Filter by build ID.