How about adding a help page for the go command for this? Like go help testflags we could have go help reproducible?

That's also an option, but I think we've been gradually moving the documentation to the website. Note how go help modules now points to pages like https://go.dev/ref/mod, for example.

Which, as a consummate terminal user, I think is not a good evolution. For an example of what i like better, git help even opens man pages. For longer topics go help could open or refer to go doc pages.

If you want to suggest a different overall strategy to documentation, I would suggest to open a new issue, because otherwise we're going to get off-topic. This thread is about adding one new documentation page.

I think probably the wiki is the right answer for the moment. We'd like to move that to Gerrit (with self-review allowed by known contributors) at some point, which will help with the "anyone can edit" part and also with search engines indexing the wiki.

Re-reading #51812, and looking at go help build, I seem to understand that setting -trimpath doens't affect -buildvcs. However, in that thread, @rsc says:

We're not going to make a -reproducible flag disable cgo. That's mixing two unrelated things. At that point I don't see the difference between -reproducible and -trimpath.
[...]
So probably -trimpath is the reproducibility flag.

With cgo disabled, -trimpath isn't really a reproducibility flag today. In a local build, if I do CGO_ENABLED=0 go build -trimpath, the result is not guaranteed to be reproducible - the -buildvcs information will be stamped if the local code is a git checkout and the git tool is installed, but if I downloaded the source from a zip archive (like many packagers do, for efficiency) or don't have git installed, the information will be omitted.

So it seems to me that, if we do want -trimpath to be the reproducibility flag modulo cgo, it should enforce either -buildvcs=true or -buildvcs=false for the sake of consistent and reproducible behavior. Alternatively, combining the two flags would be "the reproducibility mode", but that doesn't feel as nice to me.

Personally I would lean towards -buildvcs=false, assuming that with #50603 implemented, we would still stamp the binary with a main module version. Project authors definitely want release binaries to include their own versions, and it would be ideal for the end user to be able to reproduce those binaries easily.

Another reason to lean towards -buildvcs=false for the "canonical" way to reproducible builds is that a build via GOPROXY, e.g. go install -trimpath foo.com/bar@v1.2.3, would never be able to embed VCS information into the binary. So it would be a shame if a git clone+checkout of the same git tag, and swapping go install [...]@latest with go build, would then break reproducibility unless you also add -buildvcs=false yourself.

This is a great effort. Appreciate the care about raising awareness about -buildvcs, which I mentioned back in #57120 (comment)

So it would be a shame if a git clone+checkout of the same git tag, and swapping go install [...]@latest with go build, would then break reproducibility unless you also add -buildvcs=false yourself.

Much agreed. But adding various behaviour to -trimpath also feels like overloading it. At the same time I understood that one reason behind not adding -reproducible was that it ought not to modificed CGO_ENABLED, and would thus not be "complete" (for at least that reason). Perhaps documentation of the needed flags is the right way? For visibility, I would place such docs in go help build (at least).

Documenting -buildvcs=false as one extra step for a standard reproducible build would be fine with me as well, although it would be more typing. I only raise this because earlier -trimpath had been described as the reproducibility flag modulo cgo, so I'm not sure if we're parting from that. Clear docs would be necessary either way for sure.