proposal: cmd/go: add -buildversion build flag #77020

Update: 2026-09-15:

The latest version of the proposal is in #77020 (comment) below, with some earlier rationale in #77020 (comment).

A separate proposal #79789 would help this proposal by making it more convenient to obtain VCS info for later use with the new -buildversion flag in some cases, such as when a project owner might be doing a docker build without VCS visible to go build as described here. However, the -buildversion flag proposal is still useful without #79789, and #79789 can likely be treated separately.

-- The @golang/go-command working group

Background

I yearn for the day debug.BuildInfo.Main.Version is all a binary needs to know its own version.

buildInfo, ok := debug.ReadBuildInfo()
if !ok {
	panic("can't retrieve version: this binary must be built with Go modules")
}
fmt.Println(buildInfo.Main.Version)

There are four common scenarios for building Go binaries:

1. go install example.com/cli@latest
2. git clone example.com/cli; cd cli; go build
3. Package managers, which know the version they are building
4. Download source tarball and go build

(1) always worked with debug.BuildInfo.Main.Version.

(2) has worked since #50603.

This proposal would address (3).

I can't think of a way to address (4) without taking the version from a file, which feels error prone. I welcome ideas/opinions.

Proposal

Add the -buildversion build flag, to let build processes that know the version provide it to cmd/go, in a similar way to how the version is stamped from VCS info with -buildvcs.

-buildversion version
	The version of the main module being built. This overrides the version
	derived from -buildvcs information. It is an error to use this flag with
	"go install" with a version suffix. version must be a valid semver string
	with a "v" prefix.

(While implementing this, we should also document debug.BuildInfo.Main.Version sources, I can't find anything in the docs about #50603.)