go-template

A batteries-included Go project template optimised for PoC and hobby projects. Clone it, rename the module, run make init, and you're coding.

---

Features

Area	Tool	Purpose
Language	Go 1.25	Modules, toolchain directive
Logging	standard log/slog	Structured JSON/text logging + WithField extension
Config	standard flag	CLI flags with defaults, no config files
Linting	golangci-lint	Aggregated linters, one config file
Security	gosec + govulncheck	SAST + dependency vulnerability scan
Tests	standard testing	Table-driven tests, manual fakes, no third-party test framework
Git hooks	custom pre-push	gofmt + go vet + golangci-lint + gosec on every push
Tool versions	tools.versions + go run	Pinned versions without polluting go.mod
Dev environment	devcontainer	Reproducible VSCode / GitHub Codespaces setup
IDE	VSCode	Launch configs, tasks, recommended settings

---

Getting started

Prerequisites

• Go 1.25+
• Git
• (Optional) VSCode + Go extension
• (Optional) Docker for devcontainer

1. Clone and rename

git clone https://gitea.djmil.dev/djmil/go-template my-project
cd my-project

# Interactive rename — updates module path, config, devcontainer, and docs:
./rename.sh

2. Init (run once)

make init   # fetches deps, installs tools, configures git hooks

3. Build and run

make build  # compiles to ./bin/app
make run    # go run with default flags

---

Daily workflow

make test          # run all tests
make test-race     # … with race detector
make lint          # go vet + golangci-lint
make lint-fix      # go fix + golangci-lint auto-fix
make security      # gosec + govulncheck

Keyboard shortcut (VSCode): Ctrl+Shift+B → build, Ctrl+Shift+T → test.

---

Project structure

.
├── cmd/
│   └── app/
│       └── main.go          # Composition root (thin — just wiring)
├── internal/
│   ├── config/              # flag-based config (config.Load)
│   ├── logger/              # slog wrapper with WithField / WithFields
│   └── greeter/             # Example domain package (replace with yours)
├── .devcontainer/           # VSCode / Codespaces container definition
├── .githooks/               # pre-push hook (installed by `make setup`)
├── .vscode/                 # launch, tasks, editor settings
├── tools.versions           # Pinned tool versions (Makefile + hook source this)
├── .golangci.yml            # Linter configuration
└── Makefile                 # All development commands

---

Configuration

All configuration is via CLI flags with sensible defaults:

./bin/app -help
  -env string       environment: dev | staging | prod (default "dev")
  -log-level string log level: debug | info | warn | error (default "info")
  -name string      application name (default "go-template")
  -port int         listen port (default 8080)

Override at runtime:

./bin/app -port 9090 -env prod -log-level warn

---

Logging

The logger wrapper adds WithField and WithFields for ergonomic context chaining on top of the standard log/slog package:

log.WithField("request_id", rid).
    WithField("user", uid).
    Info("handling request")

log.WithFields(map[string]any{
    "component": "greeter",
    "name":      name,
}).Debug("generating greeting")

In production (app.env != dev) the output is JSON (slog.NewJSONHandler). In development, logger.NewDevelopment() uses the human-friendly text handler.

---

Testing

Tests use the standard testing package. Concrete types are returned from constructors — consumers (including tests) define their own minimal interfaces and satisfy them with manual fakes. No code generation required.

// Interface declared in the consumer (or _test.go), not in greeter package.
type greeter interface {
    Greet(name string) result.Expect[string]
}

type fakeGreeter struct {
    greetFn func(name string) result.Expect[string]
}

func (f *fakeGreeter) Greet(name string) result.Expect[string] {
    return f.greetFn(name)
}

func TestSomething(t *testing.T) {
    fake := &fakeGreeter{
        greetFn: func(name string) result.Expect[string] {
            return result.Ok("Hello, " + name + "!")
        },
    }
    // pass fake to the system under test
}

---

Git hooks

The pre-push hook runs gofmt + go vet + golangci-lint + gosec against the full codebase before every git push. Running on push (not commit) keeps the inner commit loop fast while still blocking bad code from reaching the remote.

govulncheck is intentionally excluded (it makes network calls and can be slow). Run it manually with make security.

To skip the hook in an emergency:

git push --no-verify

---

Tool version management

Tool versions are pinned in tools.versions — a plain KEY=value file that both the Makefile and the pre-push hook source directly.

Why not tools.go + go.mod?

The conventional //go:build tools approach adds development tools (linters, scanners, debuggers) as entries in go.mod. This is fine for applications, but it's a problem when the repo is intended to publish reusable packages: consumers who go get your package see those tool dependencies in the module graph, even though they are never compiled into the binary. Keeping go.mod clean makes the module honest — it declares only what the package code actually needs.

Instead, go run tool@version is used in Makefile targets and the pre-push hook. Go caches downloaded tools in the module cache, so after the first run there is no extra download cost.

To update a tool, edit the version in tools.versions:

GOLANGCI_LINT_VERSION=v1.64.8   ← change this

Both make lint and the pre-push hook pick up the new version automatically. Run make tools if you also want the updated binary installed to GOPATH/bin (e.g. for IDE integration or direct CLI use).

---

Devcontainer

Open this repo in VSCode and choose "Reopen in Container" — the Go toolchain and all tools (golangci-lint, gosec, govulncheck) are installed automatically via make init.

Works with GitHub Codespaces out of the box.

---

Next steps (not included)

• HTTP server — add chi or gin
• Database — add sqlx or ent
• CI — add .github/workflows/ci.yml running make lint test security
• Docker — add a multi-stage Dockerfile for the binary
• OpenTelemetry — add tracing with go.opentelemetry.io/otel