Skip to content

Commit 1c2c502

Browse files
alies-devalies-dev
committed
Add Go documentation
Provide detailed usage examples and AI-friendly flags for Go tools, including go build, go test, go vet, go mod, golangci-lint, staticcheck, gofmt, goimports, and govulncheck. Expand Go ecosystem tool list in README.md.
1 parent c07d059 commit 1c2c502

2 files changed

Lines changed: 194 additions & 8 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ AI agents don't need progress bars, color codes, banners, or interactive prompts
1515
- [Node.js](node.md) - npm, npx, yarn, pnpm, eslint, prettier, biome, jest, vitest, mocha, tsc, playwright, cypress
1616
- [Python](python.md) - pip, uv, poetry, pytest, ruff, mypy, pyright, black, flake8, pylint, isort, bandit, coverage, tox, django, flask
1717
- [PHP](php.md) - php-cs-fixer, phpcs, phpstan, psalm, phpunit, pest
18+
- [Go](go.md) - go build, go test, go vet, go mod, golangci-lint, staticcheck, gofmt, goimports, govulncheck
1819
- [Rust](rust.md) - WIP
19-
- [Go](go.md) - WIP
2020
- [Ruby](ruby.md) - WIP
2121
- [Java](java.md) - WIP
2222
- [.NET](dotnet.md) - WIP

‎go.md‎

Lines changed: 193 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,209 @@
1-
WIP
2-
31
# Go
42

3+
## Quick Reference
4+
5+
| Tool | AI-Friendly Flags |
6+
|-------------------|---------------------------------------------------------------------------|
7+
| go build | No flags needed (no colors, no progress bars) |
8+
| go test | `-v` (individual test names), `-json` (NDJSON) |
9+
| go vet | No flags needed (output is `file:line:col: message`) |
10+
| go mod tidy | No flags needed (silent on success) |
11+
| golangci-lint run | `--color=never --show-stats=false --output.text.print-issued-lines=false` |
12+
| staticcheck | No flags needed (output is `file:line:col: message (CODE)`) |
13+
| gofmt | `-l` (list files) or `-d` (diffs) |
14+
| goimports | `-l` (list files) or `-d` (diffs) |
15+
| govulncheck | No flags needed (text output is already clean) |
16+
517
## go build
618

19+
```bash
20+
go build ./...
21+
```
22+
23+
Go's compiler output is already AI-friendly — no colors, no progress bars, no banners. Errors print to stderr in `file:line:col: message` format, one per line.
24+
25+
- `-json` — emits build output as JSON (one event per line)
26+
727
## go test
828

29+
```bash
30+
# Default — only failures and summary
31+
go test ./...
32+
33+
# Verbose — shows all test names
34+
go test -v ./...
35+
36+
# Structured JSON output
37+
go test -json ./...
38+
```
39+
40+
- `-v` — shows individual test names with PASS/FAIL status and `t.Log` output
41+
- `-json` — NDJSON with `Action`, `Package`, `Test`, `Output` fields per event
42+
- `-count=1` — disables test result caching (useful for re-runs)
43+
- `-failfast` — stops after first test failure
44+
- `-run regexp` — runs only matching tests
45+
- `-short` — tells long-running tests to shorten their run time
46+
- `-fullpath` — shows full file paths in error messages instead of relative
47+
48+
Single test: `go test -v -run TestName ./path/to/pkg`
49+
50+
Default output is already minimal — only failures and a one-line summary per package. No colors, no progress bars. The `-v` flag adds individual test names, which is useful for agents to understand what passed.
51+
52+
### Coverage
53+
54+
```bash
55+
# Inline coverage percentage
56+
go test -cover ./...
57+
58+
# Generate coverage profile
59+
go test -coverprofile=cover.out ./...
60+
61+
# Function-level coverage report
62+
go tool cover -func=cover.out
63+
```
64+
65+
- `-cover` — appends coverage percentage to each package's summary line
66+
- `-coverprofile=file` — writes coverage data to file for analysis
67+
- `go tool cover -func=file` — shows per-function coverage in `file:line: funcName percentage` format
68+
969
## go vet
1070

11-
## go mod
71+
```bash
72+
go vet ./...
73+
```
74+
75+
- `-json` — outputs JSON diagnostics
76+
- `-fix` — applies automatic fixes instead of printing diagnostics
77+
- `-fix -diff` — prints fixes as unified diffs instead of applying them (`-diff` requires `-fix`)
78+
79+
Default output is `file:line:col: message` — already compact. `go vet` runs automatically as part of `go test` (disable with `-vet=off`).
80+
81+
## go mod tidy
82+
83+
```bash
84+
go mod tidy
85+
```
86+
87+
Silent on success. Prints errors to stderr only when there are unresolvable dependency issues. No flags needed for AI agents.
88+
89+
- `-v` — prints information about removed modules to stderr
1290

1391
## golangci-lint
1492

93+
```bash
94+
# Compact one-line-per-issue (no source code, no stats)
95+
golangci-lint run --color=never --show-stats=false --output.text.print-issued-lines=false ./...
96+
97+
# Fix auto-fixable issues
98+
golangci-lint run --fix --color=never ./...
99+
```
100+
101+
- `--color=never` — disables ANSI colors (default is `auto`, which enables colors in TTY)
102+
- `--show-stats=false` — removes the per-linter stats summary at the end
103+
- `--output.text.print-issued-lines=false` — removes source code lines below each diagnostic (biggest savings)
104+
- `--output.text.print-linter-name` — appends linter name in parentheses (default: true, useful for agents)
105+
- `--output.text.colors=false` — disables colors in text output (alternative to `--color=never`)
106+
- `--fix` — applies auto-fixes from linters and formatters that support it
107+
108+
Default output includes source code snippets and a stats summary — 2-3x more verbose than the compact form above. With `--output.text.print-issued-lines=false` and `--show-stats=false`, output is one line per issue: `file:line:col: message (linter-name)`.
109+
110+
Other output formats: `--output.json.path=stdout` (JSON), `--output.checkstyle.path=stdout`, `--output.sarif.path=stdout`, `--output.junit-xml.path=stdout`, `--output.code-climate.path=stdout`.
111+
112+
> **Note:** golangci-lint v2 (2025+) changed the output flag syntax from `--out-format` to `--output.<format>.path`. If using v1, use `--out-format=line-number` instead.
113+
15114
## staticcheck
16115

17-
## gofmt / goimports
116+
```bash
117+
staticcheck ./...
118+
```
119+
120+
- `-f text` — default: `file:line:col: message (CODE)` — already compact
121+
- `-f json` — NDJSON: one JSON object per diagnostic with `code`, `severity`, `location`, `message`
122+
- `-f stylish` — grouped by file with decorative formatting and summary count (more verbose)
123+
- `-checks "all,-ST1000"` — configure which checks to run
124+
125+
Default text output is already one of the cleanest in the Go ecosystem. No colors, no banners, one line per issue.
126+
127+
## gofmt
128+
129+
```bash
130+
# Check which files need formatting
131+
gofmt -l .
132+
133+
# Show diffs
134+
gofmt -d .
135+
136+
# Fix formatting in place
137+
gofmt -w .
138+
```
139+
140+
- `-l` — lists files whose formatting differs from gofmt's (one path per line)
141+
- `-d` — displays unified diffs without modifying files
142+
- `-w` — rewrites files in place
143+
- `-s` — simplify code (e.g., `s[a:len(s)]` to `s[a:]`)
144+
- `-e` — report all errors (not just the first 10 on different lines)
145+
146+
gofmt produces no output when all files are correctly formatted. No colors, no banners.
147+
148+
## goimports
149+
150+
```bash
151+
# Check which files need import fixes
152+
goimports -l .
153+
154+
# Show diffs
155+
goimports -d .
156+
157+
# Fix imports and formatting in place
158+
goimports -w .
159+
```
160+
161+
- `-l` — lists files that need changes
162+
- `-d` — displays unified diffs
163+
- `-w` — rewrites files in place
164+
- `-local prefix` — puts imports beginning with prefix after third-party packages (e.g., `-local github.com/myorg`)
165+
166+
goimports is a superset of gofmt — it also adds missing imports and removes unused ones. Same output format as gofmt.
167+
168+
## govulncheck
169+
170+
```bash
171+
# Scan for known vulnerabilities
172+
govulncheck ./...
173+
```
174+
175+
- `-format json` — structured JSON output with full vulnerability details and SBOM
176+
- `-format sarif` — SARIF format for integration with security tools
177+
- `-format openvex` — OpenVEX format
178+
- `-scan module` — scan at module level (faster, less precise)
179+
- `-scan package` — scan at package level (middle ground)
180+
- `-scan symbol` — default: scan at symbol level (most precise, only reports vulns in code paths actually used)
181+
- `-show traces` — shows call stacks from your code to the vulnerable function
182+
- `-test` — include test files in the analysis
183+
184+
Default text output prints "No vulnerabilities found." on success, or a structured report with vulnerability ID, description, and affected packages on failure. No colors.
185+
186+
## AGENTS.md / CLAUDE.md Template
18187

19-
## delve (dlv)
188+
Copy this into your project's AGENTS.md or CLAUDE.md:
20189

21-
## goreleaser
190+
```markdown
191+
## Running Tools
22192

23-
## air
193+
- Build: `go build ./...`
194+
- Tests: `go test ./...`
195+
- Tests (verbose): `go test -v ./...`
196+
- Tests (single): `go test -v -run TestName ./path/to/pkg`
197+
- Tests (no cache): `go test -count=1 ./...`
198+
- Coverage: `go test -cover ./...`
199+
- Vet: `go vet ./...`
200+
- Lint: `golangci-lint run --color=never --show-stats=false --output.text.print-issued-lines=false ./...`
201+
- Lint fix: `golangci-lint run --fix --color=never ./...`
202+
- Static analysis: `staticcheck ./...`
203+
- Format check: `gofmt -l .`
204+
- Format fix: `gofmt -w .`
205+
- Import check: `goimports -l .`
206+
- Import fix: `goimports -w .`
207+
- Vulnerability scan: `govulncheck ./...`
208+
- Tidy deps: `go mod tidy`
209+
```

0 commit comments

Comments
 (0)