+There's a lot that you can do with GoReleaser. These are the things that we've
+found the most useful for the majority of projects:
+
+- Basic Usage & Versioning
+- Publishing Builds to GitHub
+- Publishing to Gitea and Gitlab
+- Building for RPi et al
+- Building from one or more `cmd/`s
+- Cross-Compiling with cgo
+- Full `.goreleaser.yml` example
+
+## Basic Usage & Versioning
+
+To create an example `.goreleaser.yaml` file, and test the configuration:
+
+```bash
+goreleaser init
+goreleaser --snapshot --skip-publish --rm-dist
+```
+
+- `--snapshot` allows "dirty" builds (when the repo has uncommitted changes)
+- `--skip-publish` will NOT publish to GitHub, etc
+- `--rm-dist` will automatically remove the `./dist/` directory
+
+The default `.goreleaser.yml` works well for projects for which `package main`
+is at the root.
+
+GoReleaser provides version information. Here's a good, generic way to print it
+out:
+
+```go
+package main
+
+var (
+ // these will be replaced by goreleaser
+ version = "v0.0.0"
+ date = "0001-01-01T00:00:00Z"
+ commit = "0000000"
+)
+
+func main() {
+ if len(os.Args) >= 2 && "version" == strings.TrimPrefix(os.Args[1]) {
+ fmt.Printf("YOUR_CLI_NAME v%s %s (%s)\n", version, commit[:7], date)
+ }
+
+ // ...
+}
+```
+
+### How to Publish Builds to GitHub
+
+You'll need a **Personal Access Token** with the `repo` scope. \
+You can get one at <https://github.com/settings/tokens/new>.
+
+You can export the environment variable:
+
+```bash
+export GITHUB_TOKEN="YOUR_GITHUB_TOKEN"
+```
+
+Or place the token in the default config location:
+
+```bash
+~/.config/goreleaser/github_token
+```
+
+You can also set `env_files` in `.goreleaser.yml`:
+
+```yml
+env_files:
+ github_token: ~/.config/goreleaser/github_token
+```
+
+Running GoReleaser without `--snapshot` must use the latest
+[Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) of your repository.
+Create a tag and push it to Git:
+
+```bash
+git tag -a v1.0.0 -m "First release"
+git push origin v1.0.0
+```
+
+Running GoReleaser without `--skip-publish` will publish the builds:
+
+```bash
+goreleaser --rm-dist
+```
+
+Check the console output to make sure that there are no messages about a failed
+publish. \
+If all is well you should the git tag on the releases page updated with a ChangeLog
+and the published binaries.
+
+### How to Publish to Gitea and others
+
+Gitea Token: https://try.gitea.io/user/settings/applications