iru-go-bump-version
Set a Go module's in-tree version to an exact value — a Cobra command-line tool scaffolded by `iru-setup-go-cli` (`internal/version/version.go`: `var Version = "0.1.0-dev"`, overridden at release time
SKILL.md.claude/skills/iru-go-bump-version/SKILL.md
GitHubGo Bump Version
Set a Go project's in-tree version literal to an exact value across every file that must agree with it, check that
the release build's -ldflags -X override still points at it, and, optionally, update README/Antora version
mentions. This skill never computes a version itself: it applies exactly the string it's given, validated for shape.
The "which version comes next" logic belongs to the caller (typically iru-release) and is defined in Step 5, the same
contract iru-dotnet-bump-version, iru-python-bump-version and the other iru-<key>-bump-version skills define for
their ecosystems. It never commits, tags, builds a release, or edits go.mod.
Step 0 — Resolve inputs
- The positional argument is
<new-version>(e.g.1.4.0,1.5.0-dev). Missing → ask for it before doing anything else; never guess or compute one here. args(key: valuelines), if present:sync-files: yes|no— also update README/Antora mentions (Step 7). Omitted → ask once withAskUserQuestionafter Step 3 shows such mentions exist; don't ask when none do.next-version: <upcoming-version>— the upcoming development version (e.g.1.5.0-dev) that "Current development version" markers should show after a release, while "Latest release" markers show<new-version>. Only meaningful withsync-files: yes; validated like<new-version>.files: <comma list>— only look at these.gofiles (passed to the helper as--files=); default: every git-tracked non-test.gofile outsidevendor/,testdata/,dist/.dry-run: yes|no— defaultno.yesruns everything through showing the diff, then stops: nothing is written; say so plainly in the report.
Reject before touching anything a value that is obviously not a version (empty, or containing whitespace).
Step 1 — Validate the version string
Go module versions are semantic versions with a v prefix on the tag (v1.4.0); the in-tree literal, the
-ldflags -X value GoReleaser injects ({{.Version}} strips the v), and this catalog's convention carry no
prefix — X.Y.Z or X.Y.Z-dev:
python3 -c 'import re,sys; sys.exit(0 if re.fullmatch(r"\d+\.\d+\.\d+(-dev)?", sys.argv[1]) else 1)' "<new-version>"
- No match but
v-prefixed (v1.4.0) → strip thev, say so, and continue (the tag keeps it; the literal doesn't). - No match but still SemVer (
X.Y.Z-<pre-release>, e.g.-rc.1,-beta.2) → warn that it doesn't follow the-devconvention and ask whether to proceed (goorders any SemVer pre-release correctly, and GoReleaser marks such a release as a pre-release). - Anything else (
1.0,1.2.3.4, build metadata+x— which Go module versions forbid on tags) → refuse.
Anything with a - suffix counts as a pre-release.
Step 2 — Write the helper and survey the version locations
| Location | Rewritten to | When |
|---|---|---|
var Version = "…" (or var Version string = "…", or a Version = "…" line in a var (…) block) in a non-test .go file — internal/version/version.go in this catalog's scaffold |
<new-version> |
always |
const Version = "…" (alone or in a const (…) block) |
<new-version> |
always — but reported: -ldflags -X can't override a constant (verified: the build succeeds and the binary keeps the literal), so a release pipeline injecting the tag has no effect |
-X <import path>.Version=… in .goreleaser.y*ml, Makefile, Taskfile.y*ml, justfile, .github/workflows/*.y*ml |
never rewritten — checked: the path must be <module>/<dir>.Version of a var (or main.Version for package main) |
reported ok or MISMATCH |
Generated files (// Code generated … DO NOT EDIT.), _test.go files, vendor/, testdata/ and dist/ are never
touched. Other …Version identifiers (MinVersion, APIVersion, SchemaVersion) don't match the pattern and stay
untouched; a Commit/Date stamped next to Version is release-time metadata, not a version — left alone.
mkdir -p "$TMPDIR/iru-go-bump-version"
cat > "$TMPDIR/iru-go-bump-version/go_version.py" <<'PY'
import difflib, pathlib, re, subprocess, sys
def read(p):
return p.read_bytes().decode("utf-8") # no newline translation: CRLF files stay CRLF
args = sys.argv[1:]
dry, force = "--dry-run" in args, "--force" in args
files_arg = next((a.split("=", 1)[1] for a in args if a.startswith("--files=")), "")
args = [a for a in args if not a.startswith("--")]
new = args[0] if args else None # None => --list
root = pathlib.Path(".")
SKIP = {"vendor", "testdata", "node_modules", ".git", "dist"}
# var Version = "x" | const Version = "x" | var Version string = "x" | a `Version = "x"` line inside a var (...) block
DECL = re.compile(r'^(?P<pre>\s*(?:(?:var|const)\s+)?Version(?:\s+string)?\s*=\s*")(?P<val>[^"\n]*)(?P<post>")', re.M)
def go_files():
if files_arg:
return [pathlib.Path(f) for f in files_arg.split(",") if f]
try:
out = subprocess.run(["git", "ls-files", "*.go"], capture_output=True, text=True, check=True).stdout.split()
cand = [pathlib.Path(p) for p in out]
except (FileNotFoundError, subprocess.CalledProcessError):
cand = sorted(root.rglob("*.go"))
return [p for p in cand if p.exists() and not p.name.endswith("_test.go")
and not any(part in SKIP for part in p.parts)]
found = [] # (path, line, value, kind, match)
for p in go_files():
text = read(p)
if re.search(r"^// Code generated .* DO NOT EDIT\.$", text, re.M):
continue
for m in DECL.finditer(text):
line_start = text.rfind("\n", 0, m.start()) + 1
block = text[:m.start()]
kind = "const" if re.search(r"(?:^|\n)\s*const\b[^\n]*$", text[line_start:m.end()]) or \
(block.rfind("const (") > block.rfind(")") and not m.group("pre").lstrip().startswith("var")) else "var"
found.append((p, text.count("\n", 0, m.start()) + 1, m.group("val"), kind, m))
for p, line, val, kind, _ in found:
print(f"{p.as_posix()}:{line}: {val} [{kind} Version]")
if kind == "const":
print(f"note: {p.as_posix()} declares Version as a const — -ldflags -X can only override a package-level string var")
if not found:
sys.exit('No `var Version = "…"` / `const Version = "…"` literal found in any non-test .go file')
mod = pathlib.Path("go.mod")
modpath = re.search(r"^module\s+(\S+)", read(mod), re.M).group(1) if mod.exists() else ""
print(f"module: {modpath}")
# -ldflags -X references must name <import path>.Version of a var, or the linker silently ignores them
targets = set()
for p, _, _, kind, _ in found:
if kind != "var":
continue
pkg = re.search(r"^package\s+(\w+)", read(p), re.M).group(1)
d = p.parent.as_posix()
targets.add("main.Version" if pkg == "main" else f"{modpath}.Version" if d == "." else f"{modpath}/{d}.Version")
for cfg in [*root.glob(".goreleaser.y*ml"), *root.glob("Makefile"), *root.glob("Taskfile.y*ml"), *root.glob("justfile"),
*root.glob(".github/workflows/*.y*ml")]:
for n, line in enumerate(cfg.read_text(encoding="utf-8", errors="replace").splitlines(), 1):
for ref in re.findall(r"-X[ =]['\"]?([\w./-]+\.Version)=", line):
ok = "ok" if ref in targets else f"MISMATCH — no var at that path (expected one of {sorted(targets)}); the linker ignores it silently"
print(f"ldflags: {cfg.as_posix()}:{n}: -X {ref} [{ok}]")
values = sorted({f[2] for f in found})
if len(values) > 1:
print(f"WARNING: Version literals disagree: {values}", file=sys.stderr)
if new is not None and not force:
sys.exit("Refusing to write: confirm with the user, then re-run with --force to align every literal")
if len(values) == 1:
print(f"current: {values[0]}")
if new is None:
sys.exit(0)
major = int(re.match(r"v?(\d+)", new).group(1))
suffix = re.search(r"/v(\d+)$", modpath)
if major >= 2 and (not suffix or int(suffix.group(1)) != major):
print(f"WARNING: major version {major} needs the module path to end in /v{major} (go.mod says {modpath!r}); "
f"consumers can't `go get` v{major}.x tags otherwise — changing it is a breaking import-path change, not done here",
file=sys.stderr)
if major < 2 and suffix:
print(f"WARNING: module path {modpath!r} has a /v{suffix.group(1)} suffix but the new version is {new}", file=sys.stderr)
edits = {}
for p, _, _, _, _ in found:
text = edits.get(p, read(p))
edits[p] = DECL.sub(lambda m: m.group("pre") + new + m.group("post"), text)
for p, text in edits.items():
old = read(p)
if text == old:
continue
if dry:
sys.stdout.writelines(difflib.unified_diff(old.splitlines(True), text.splitlines(True), str(p), str(p)))
continue
p.write_bytes(text.encode("utf-8"))
print(f"updated {p.as_posix()}")
PY
python3 "$TMPDIR/iru-go-bump-version/go_version.py" --list
Run it from the module root (the directory holding go.mod; in a go.work workspace, the root of the module that
builds the binary). Output: one <file>:<line>: <value> [var|const Version] line per literal, note: lines,
module: <path>, one ldflags: <file>:<line>: -X <ref> [ok|MISMATCH …] line per reference, and a current: line.
Then:
- No literal anywhere (non-zero exit:
No var Version … found) — common for a Go library, whose version is its git tag:go get example.com/lib@v1.4.0resolves the tag, and nothing in the tree needs to change. Report "version comes from git tags (latest:git describe --tags --abbrev=0)", change nothing, and letiru-releasetreat the tag as the version (as for a Swift library). For a CLI that relies only ondebug.ReadBuildInfo()— Go ≥ 1.24 stamps the main module's version from the VCS tag (verified:go version -mshowedv0.1.0+dirtyfor a build at tagv0.1.0with a modified tree) andgo install …@vX.Y.ZstampsvX.Y.Z— the same applies. Otherwise ask whether to addinternal/version/version.gowithvar Version = "<new-version>"(the scaffold's layout) and re-run--list— never invent it silently. - Literals disagree (
WARNING: Version literals disagree) — show the list and ask whether to align them all to<new-version>(Step 4 then passes--force) or which to leave (edit the others by hand and say so in the report). const Versionnote — tell the user an-ldflags -Xoverride can't work with it; suggest changingconsttovar(a one-word code change the user approves — not made here).ldflags … MISMATCH— the release build injects a version into a path with no suchvar(a moved package, a renamed module, a typo); the linker ignores it silently (verified), so released binaries would print the committed literal. Report it prominently; fixing the pipeline file is a follow-up for the user oriru-setup-cli-github-workflows.- The current version for the report, and for
iru-release(which reads it this way), is thecurrent:line.
Step 3 — Look for mirrored mentions
grep -n -i "latest release\|current development version\|go install \|go get \|@v[0-9]" README.md 2>/dev/null
grep -rln -i "latest release\|go install \|go get " docs/modules/ROOT/pages 2>/dev/null; grep -n '^version:' docs/antora.yml 2>/dev/null
Only when something turns up is sync-files worth asking about (Step 0). go install …@latest snippets need no
change; @vX.Y.Z pins do (Step 7). Golden files of a --version test (testdata/script/*.txtar matching
version 0.1.0-dev, testdata/*.golden) also mirror the literal — list them in the report as tests the caller must
update (this skill doesn't edit tests); a scaffold that reads version.Version in its assertions needs nothing.
Step 4 — Preview (dry-run: yes) or apply
python3 "$TMPDIR/iru-go-bump-version/go_version.py" "<new-version>" --dry-run # unified diff only
python3 "$TMPDIR/iru-go-bump-version/go_version.py" "<new-version>" # write
Add --force only after the user confirmed aligning disagreeing literals (Step 2), and --files=<a.go>,<b.go> when
files: was given. The helper rewrites only the string inside each matched Version literal, keeping CRLF line
endings and everything else byte-for-byte. A WARNING: major version N needs the module path to end in /vN on stderr
→ include it in the report verbatim (Step 5). A non-zero exit at any point → stop, show the error, and treat nothing as
updated; never fall back to hand edits.
Step 5 — The Go-catalog pre-release convention (for iru-release and other callers)
The Go equivalent of iru-java-bump-version's -SNAPSHOT and iru-dotnet-bump-version's -dev — the contract
iru-release calls this skill against (two calls per release, each passing a computed <new-version>), and the one
the sync.yml written by iru-setup-cli-github-workflows and the iru-setup-go-cli scaffold use:
- Current development version:
x.y.z-dev(e.g.1.4.0-dev) in theVersionliteral on the gitflow integration branch. SemVer orders1.4.0-devbefore1.4.0and after1.3.0. A localgo buildprints it; a main-only repository has no development marker — the literal is always the last or next releasex.y.z. - The git tag is the source of truth for module consumers: releases are tagged
vX.Y.Z(with thev— the go command ignores tags without it).go install <module>/cmd/<bin>@vX.Y.Zbuilds from the tag without any-ldflags, so the committed literal is what those users see — which is why the release commit carriesX.Y.Z, notX.Y.Z-dev. The release workflow (GoReleaser) injects the tag again via-X …Version={{.Version}}and checks that the tag minusvequals the literal. Never tag-devversions. - Major version 2 and above: Go's semantic import versioning requires the module path to end in
/vN(module github.com/acme/tool/v2) and every internal import to use it. The helper warns when<new-version>'s major is ≥ 2 and the suffix is missing or different; the path change is a breaking, repository-wide import rewrite the user does deliberately (and announces) — never part of a version bump. Acmd/binary that nobody imports is still affected:go install …@v2.0.0fails without the/v2path. - Cutting a release: strip the suffix —
x.y.z-dev→x.y.z. Call this skill with<new-version>: x.y.z, commit, tagvx.y.z. - Opening the next development cycle: bump the minor (this catalog's default, matching
iru-release's recommended "minor bump" and thesync.ymlworkflow) and re-append-dev—x.y.z→x.(y+1).0-dev; a patch or major bump is the caller's choice. Call this skill again (or letsync.ymldo it after the release is published) with that exact value — this skill never decides which component to bump. - Tag-only projects (no literal — Step 2): the release is the git tag.
iru-releaseskips its "must currently be a pre-release" check and its next-version question for them, exactly as for a Swift library. In a multi-module repository, a nested module's tags carry its directory prefix (tools/v1.2.0) — say so whengo.modisn't at the repository root.
Step 6 — Sanity check
Skip with dry-run: yes. Otherwise:
python3 "$TMPDIR/iru-go-bump-version/go_version.py" --list # every literal shows the new value, no warning
go build -o build/iru-go-bump-version-bin ./cmd/<bin> && ./build/iru-go-bump-version-bin --version
rm -f build/iru-go-bump-version-bin
The binary must print <new-version> (a CLI with a different version command, e.g. <bin> version, is run that way;
a library with no binary just needs go build ./... and go vet ./<version package> to pass). Without a Go
toolchain, say the build check wasn't run rather than assume it passed.
Step 7 — Optionally sync other files that mirror the version
Ask (or honor sync-files) whether to update the mentions Step 3 found, mapping each by what it names — the same rule
as iru-java-bump-version's Step 7:
- "Latest release" markers (and a
Latest releaserow in the README's status table) and pinned install snippets (go install <module>/cmd/<bin>@vX.Y.Z,go get <module>@vX.Y.Z— note thev), Homebrew/Scoop/WinGet commands pinned to a version →<new-version>(withvwhere the snippet uses a tag) only when it is a release. - "Current development version" markers →
next-versionwhen given; otherwise<new-version>only if it is a-devvalue, and untouched (warn in Step 8 that the caller should passnext-version) when it's a release — never regress a development marker to a release value. docs/antora.ymlversion:→<new-version>only for a release (Antora's component version names released versions; skip-dev), if the site tracks the release version at all.- Antora pages under
docs/modules/ROOT/pages/with the same markers/snippets → as for the README. A generated CLI reference page (written by the scaffold'sgendocstool) is regenerated, not hand-edited — mention it.
Targeted, scoped substitutions only — never a repository-wide replace of the old string. A README badge pulling the version live (GitHub release, pkg.go.dev, Homebrew shields) must not be rewritten.
Step 8 — Report
- Every literal from
--listwith its old and new value,constnotes, and every-ldflags -Xreference withok/MISMATCH. - Every file changed (by the script and by Step 7), or that nothing changed because the version comes from git tags.
- Any disagreement aligned with
--forceafter the user confirmed, golden/test files that mirror the old value, and whether this was adry-run; the Step 6 result (--listagreement,--versionoutput or "not run"). - Warn explicitly: review the diff before committing (this skill commits and tags nothing); tag releases as
v<new-version>; a major ≥ 2 needs the/vNmodule path (with the helper's warning verbatim) before it can be consumed withgo get/go install.
Verification notes
Verified in $TMPDIR/iru-verify/cli/go-gates/demo (Go 1.27.2, host python3 3.9, a throwaway Cobra CLI module
committed to a throwaway git repository) by running the exact helper above:
--liston the scaffold layout (internal/version/version.go:var Version = "0.1.0-dev") printed the literal,module: github.com/example/democtl,current: 0.1.0-dev, and for a.goreleaser.yamlwith-X github.com/example/democtl/internal/version.Version={{.Version}}→[ok], while a second-X …/internal/versionX.Version=…line →MISMATCH.0.1.0 --dry-runprinted the unified diff and left the file unchanged;0.1.0rewrote it;2.0.0-dev --dry-runwarnedmajor version 2 needs the module path to end in /v2. Avar (…)block,const Version = "…"andVersion string = "…"insideconst (…)were found, the two constants with the-ldflags -Xnote; a second literal inpackage mainproducedVersion literals disagree, a refusal without--force, and both rewritten with it (expected-Xtargetmain.Versionlisted).go build -ldflags "-X …/internal/version.Version=9.9.9"→democtl version 9.9.9; the same flag against aconst Version, and against a misspelled package path, built without error and printed0.1.0-dev— the silent no-op the helper's checks exist for.go version -mon a binary built at tagv0.1.0(dirty tree) showedmod github.com/example/democtl v0.1.0+dirty(Go ≥ 1.24 VCS version stamping).- Not verified:
go install …@vX.Y.Zfrom a published module (needs a public repository), nested-module tag prefixes, and CRLF files on Windows (the helper reads/writes bytes without newline translation).
Sources
- go.dev/ref/mod (module paths,
/vNmajor version suffixes, version queries, tagsvX.Y.Z, nested-module tag prefixes); go.dev/doc/modules/version-numbers and go.dev/doc/modules/major-version - go.dev:
go doc cmd/link(-X importpath.name=value— string variables only), Go 1.24 release notes (main-module version from VCS in build info), pkg.go.dev/runtime/debug#ReadBuildInfo - GoReleaser docs (goreleaser.com): builds
ldflags,{{.Version}}(tag withoutv) - irurueta docs: ai/cli-for-agents/self-describing-help.adoc (
--versionon stdout,version --jsonbuild metadata), ai/cli-for-agents/packaging-and-distribution.adoc (versioned release archives, tags)