iru-setup-go-gitignore
Create or update the root `.gitignore` for a Go repository — the command-line tool layout `iru-setup-go-cli` produces (`go.mod`, `cmd/<bin>/`, `internal/`, `tools/gendocs`, `testdata/script/`) or any
SKILL.md.claude/skills/iru-setup-go-gitignore/SKILL.md
GitHubSetup Go Gitignore
Create or refresh the root .gitignore of a Go module — typically a command-line tool scaffolded by
iru-setup-go-cli. The template is a trimmed, house-style version of GitHub's Go.gitignore extended with what this
catalog's scaffold, gates and release tooling actually write. Never overwrite an existing .gitignore without showing
the user exactly what would change and getting explicit approval first — it can carry hand-added, project-specific
entries that must not be dropped silently.
Step 0 — Resolve inputs
Parse args as key: value lines, skipping any question already answered:
bin-name— the binary name(s) to ignore at the root, comma-separated. Default (Step 1): every directory undercmd/that holds amain.go, else the last element of themodulepath ingo.mod(minus a/vNsuffix) when a rootmain.godeclarespackage main, else none.vendor: yes|no—yes= dependencies are vendored (vendor/is committed, never ignored);no= ignore/vendor/. Default: detected in Step 1, asked only when ambiguous.mode: new|existing— if omitted, detected: a root.gitignoremeansexisting.mode: existingnever means "update silently" — the existing file still goes through Step 5's question unlesson-existingdecides.on-existing: ask|keep|update|replace— defaultask;keep/update/replaceapplies that choice without asking (the warning and diff are still printed). Only for scripted runs; an orchestrator passes it only if its ownargsreceived it.
Any other key (e.g. the full shared-args set iru-setup-cli-repository may forward: language, ui, distribution,
…) is ignored and named in the report.
Step 1 — Survey the repository
Detect, before composing anything:
go.modat the root (read itsmoduleline). None → warn that this skill targets Go modules and ask whether to continue.- The binary names (
cmd/*/main.go, or a rootmain.gowithpackage main) forbin-name's default. - Vendoring:
vendor/modules.txttracked (git ls-files vendor/modules.txt) or present →vendor: yes, no question. Novendor/directory at all → ask withAskUserQuestion(unlessargsset it): Not vendoring (Recommended) — "Ignore/vendor/so a straygo mod vendoris never committed; the module cache andgo.sumpin dependencies." / Vendoring — "You'll rungo mod vendorand commitvendor/(builds without network access);/vendor/is not ignored." Avendor/directory that exists but is untracked → ask the same question, saying it exists. - Workspace:
go.worktracked (git ls-files go.work) → the repository deliberately shares a workspace: don't ignorego.workorgo.work.sum(commit both —go.work.sumholds checksums for the workspace modules' dependencies that no singlego.sumrecords). Otherwise ignore both (see the note in Step 2). .goreleaser.yaml/.goreleaser.yml(→dist/is GoReleaser's),tools/gendocs/(→build/gendocs/),docs/antora.ymlordocs/antora-playbook.yml(→ Antora section), a rootpackage.json(→ Node section).- Tracked files under a path the template would ignore (
git ls-files -- build dist '*.test' coverage.out '<bin>') — flag each in the report: writing.gitignorenever untracks anything. - The root
.gitignore, if present — read it.
Then tell the user which of the two this run is doing:
- Creating from scratch — no root
.gitignore: write Step 4's content without asking. - Updating existing — a root
.gitignoreexists: warn up front that Step 5 will ask whether to Update, Keep as is, or Replace it (or applyon-existing) rather than overwrite anything silently.
Step 2 — The base template
Unconditional except for the marked lines — every line flush-left in the written file (git doesn't trim leading
whitespace). <bin> lines repeat per binary name; with no binary name, drop that section.
# Binaries built at the repository root (`go build ./cmd/<bin>`)
/<bin>
/<bin>.exe
# Test binaries (`go test -c`) and CPU/memory profiles
*.test
*.pprof
# Coverage profiles (`go test -coverprofile`, `go build -cover` + GOCOVERDIR)
coverage.out
*.coverprofile
coverage.html
/covdata/
# Build and report output: coverage (build/coverage/), generated docs (build/gendocs/), local binaries
/build/
# GoReleaser output (`goreleaser release --snapshot --clean`)
/dist/
# Go workspace files: per-developer, this repository is a single module
go.work
go.work.sum
# Dependencies are not vendored (`go mod vendor` output)
/vendor/
# Environment files (never commit real secrets)
.env
.env.*
!.env.example
# Repository-wide lock serializing container-backed test runs
.integration-test.lock/
# OS files
.DS_Store
Thumbs.db
# Editors
.idea/
*.swp
*~
.vscode/*
!.vscode/settings.json
!.vscode/extensions.json
!.vscode/launch.json
!.vscode/tasks.json
Notes on specific lines:
/<bin>is root-anchored on purpose: an unanchored<bin>would also ignorecmd/<bin>/— the entry point's directory. If a root directory has the binary's name, drop the line and say so (go build -o build/<bin>is the scaffold's own habit anyway)./build/holds only regenerated output in this catalog's layout:build/coverage/cover.out(iru-go-coverage, the workflows),build/gendocs/{man,markdown,completions}(go run ./tools/gendocs, GoReleaser's before-hook) andbuild/<bin>smoke-test binaries. Ifgit ls-files buildis non-empty, ask whether to keep ignoring the directory (and untrack it) or narrow the entry to/build/coverage/and/build/gendocs/./dist/is GoReleaser's output (--cleandeletes it); keep the line even without a.goreleaser.yamlonly if adist/directory is untracked, otherwise drop it when Step 1 found no GoReleaser config.go.work/go.work.sum: a workspace file points at local checkouts on one developer's machine, so for a single-module repository it is personal state (GitHub'sGo.gitignoreignores both for the same reason, and the Go docs advise against committinggo.workfor a single module).go.work.sumonly exists alongside ago.workand is ignored with it. A repository that tracksgo.work(a deliberate multi-module workspace) gets neither line./vendor/only withvendor: no(Step 1). Withvendor: yes, omit the section — and say that CI then builds with-mod=vendorautomatically (Go usesvendor/when it is consistent withgo.mod).- Never ignored — and if an existing
.gitignoreignores one, propose removing that line (named in Step 5's question):go.mod,go.sum(the dependency checksums — always committed, for applications and libraries alike),testdata/(Go's test fixture convention; the testscript scripts live intestdata/script/),.golangci.yml,.goreleaser.yaml,.secrets.baseline(iru-check-security's triaged baseline),.env.example.
Step 3 — Detect project-specific additions
Only add a section when Step 1 found what it targets:
- Antora (
docs/antora.ymlordocs/antora-playbook.yml):
The generated# Antora documentation build output (see iru-setup-antora) docs/build/ docs/node_modules/docs/modules/ROOT/pages/cli-reference.adocstays tracked — it is a site page, regenerated and diffed like any other source. - Node tooling at the root (
package.json):node_modules/andnpm-debug.log*. - Terminal UI (
charm.land/bubbletea/v2orgithub.com/charmbracelet/bubbleteaingo.mod, or a root.ui-quality.yml/.ui-screenshots/):# UI test captures (UI contract: .ui-screenshots/<kind>/<Id>/<state>--<direction>--<theme>.txt), regenerated every run .ui-screenshots/.ui-quality.yml(the accessibility level and capture matrix) stays tracked; the documentation skills copy the captures they use into the Antoraimages/ui/tree, which is committed. - Don't invent entries beyond what was detected.
Step 4 — Compose the proposed content
Step 2's template (with the per-repository choices applied) plus the Step 3 sections that matched, each under its
comment header. If a root .gitignore exists, merge: keep every existing line not already covered (hand-added
ignores survive), don't repeat a line already present verbatim or in a path-equivalent form (dist / dist/ /
/dist/), keep ! negations after the patterns they re-include, and remove an ignore line for go.sum/go.mod
— the one deliberate kind of deletion, listed in Step 5's question. A whole-directory .vscode/ line in the existing
file wins over the template's .vscode/* block (git can't re-include files under an excluded directory).
Before proposing, check the draft doesn't hide source the scaffold commits — write it to a temp path, then run
git -c core.excludesFile=<draft> check-ignore --no-index (or temporarily in a scratch copy) on whichever of these
exist and refuse any line that matches one: go.mod, go.sum, cmd/*/main.go, internal/**/*.go,
tools/gendocs/main.go, testdata/script/*.txtar, .golangci.yml, .goreleaser.yaml, .env.example,
docs/modules/ROOT/pages/cli-reference.adoc, .ui-quality.yml, internal/tui/ui_screenshots_test.go,
docs/modules/ROOT/images/ui/**.
Step 5 — If a .gitignore already existed, warn and ask Update / Keep as is / Replace
Skip when Step 1 found no root .gitignore — write it straight away.
Otherwise, if the proposed content differs from disk:
- Show the proposed Update content as a diff (
git diff --no-index <current> <draft>). Say which hand-added lines a Replace would drop, and name any conflicting existing line (e.g.go.sum, which must be committed; an unanchored<bin>that hidescmd/<bin>/;vendor/in a vendoring repository;testdata/). - Unless
on-existingiskeep/update/replace(apply it, still printing the warning and diff), ask viaAskUserQuestion, with the consequence in each option:- Update (Recommended) — "Merge: add the template lines this file is missing; keep every hand-added line. Your
customizations survive." — plus, when it applies, "…except the
go.sumignore line, which is removed so the checksums are committed". - Keep as is — "Leave the file untouched. Nothing you customized changes, but the missing lines in the diff (e.g.
/dist/,coverage.out,/build/) stay unignored — the report lists them." - Replace — "Overwrite with this skill's template only. Matches the house pattern exactly, but every hand-added line is lost (recoverable only from git history)." If the user wants only some lines, let them say so in free text and revise the draft.
- Update (Recommended) — "Merge: add the template lines this file is missing; keep every hand-added line. Your
customizations survive." — plus, when it applies, "…except the
Step 6 — Write and report
Write the chosen draft to .gitignore (or nothing, if kept as is). Then verify with git itself (read-only), for the
paths that exist or with throwaway empty files in a scratch copy:
# must print nothing (exit 1): the module files, sources, scripts and configs stay tracked
git check-ignore go.mod go.sum cmd/<bin>/main.go internal/cli/root.go testdata/script/greet.txtar .golangci.yml .goreleaser.yaml .env.example
# should list each generated path with the line that ignores it
git check-ignore -v <bin> build/coverage/cover.out build/gendocs dist coverage.out cli.test .env .integration-test.lock 2>/dev/null
# terminal UI only: the captures are ignored, the config and the helper are not
git check-ignore -v .ui-screenshots/screen/Model/default--ltr--no-color.txt; git check-ignore .ui-quality.yml internal/tui/ui_screenshots_test.go
Summarize: whether this run created from scratch or updated an existing file, the action taken — created /
updated / replaced / kept as is — and whether it came from the user or on-existing (when kept, the template lines it
still lacks); the binary names used; the vendoring and workspace decisions and why; which Step 3 sections were included
vs. skipped and why; whether a go.sum ignore line was removed; the git check-ignore result; and any already-tracked
file under a newly ignored path, with the git rm -r --cached <path> it needs.
Warn explicitly:
- Review the generated/updated
.gitignorebefore committing — detection is heuristic. - Writing
.gitignorealone never untracks a committed file (a root binary,dist/,coverage.out): rungit rm -r --cached <path>for each after reviewing. - Commit
go.modandgo.sumalways; commitvendor/only if you chose to vendor; commitgo.work/go.work.sumonly for a deliberate multi-module workspace. - A committed
.envmay contain credentials: rotate them, since they remain in git history.
Sources
- GitHub's
github/gitignoreGo.gitignore(binaries,*.test,*.out,go.work,go.work.sum,vendor/as an opt-in) andGlobal/editor/OS templates. - Go: go.dev/ref/mod (
go.sum"should be committed", vendoring and-mod=vendor, workspaces), go.dev/doc/tutorial/workspaces, go.dev/blog/integration-test-coverage (GOCOVERDIR). - GoReleaser: goreleaser.com/customization/dist/ (
dist/,--clean). - This catalog:
iru-setup-go-cli's scaffold contract (build/coverage/,build/gendocs/,testdata/script/), andiru-setup-windows-gitignore/iru-setup-python-gitignore(structure).
Verification notes
Verified on 2026-10-16 in $TMPDIR/iru-verify/cli/iru-setup-go-gitignore-2/ (outside this repository): the base
template for bin-name: hello-cli with vendor: no and the Antora section, written into a git init-ed directory
seeded with one file per pattern and per source file the scaffold commits. git check-ignore -q reported 24/24
generated paths ignored — hello-cli, hello-cli.exe, cli.test, cpu.pprof, coverage.out, x.coverprofile,
coverage.html, covdata/covmeta.1, build/coverage/cover.out, build/gendocs/man/hello-cli.1, dist/SHA256SUMS,
dist/hello-cli_linux_amd64_v1/hello-cli, go.work, go.work.sum, vendor/modules.txt, .env, .env.local,
.integration-test.lock/owner, docs/build/site/index.html, docs/node_modules/x, .DS_Store, .idea/x,
.vscode/x.json, a.swp — and git check-ignore on the 16 files that must stay tracked (go.mod, go.sum,
cmd/hello-cli/main.go, cmd/hello-cli/main_test.go, internal/cli/root.go, internal/version/version.go,
tools/gendocs/main.go, testdata/script/greet.txtar, internal/cli/testdata/x.golden, .golangci.yml,
.goreleaser.yaml, .env.example, .vscode/settings.json, docs/modules/ROOT/pages/cli-reference.adoc,
docs/antora.yml, .secrets.baseline) printed nothing and exited 1; git status --porcelain -uall listed exactly
those 16 files plus .gitignore. In particular cmd/hello-cli/main.go is not hidden by /hello-cli. The paths
match what iru-setup-go-cli's verification actually produced (build/coverage/cover.out, build/gendocs/,
dist/ from goreleaser release --snapshot --clean). The terminal-UI section (added for the UI contract) was checked
the same way in a scratch repository: .ui-screenshots/screen/Model/default--ltr--no-color.txt ignored;
.ui-quality.yml, internal/tui/ui_screenshots_test.go and docs/modules/ROOT/images/ui/screen/Model/… not.