Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

cmd/go: document why go mod tidy adds entries beyond those added by go build #27633

opennota opened this issue Sep 12, 2018 · 2 comments
Documentation modules NeedsFix The path to resolution is known, but the work has not been done.


Copy link

opennota commented Sep 12, 2018

What version of Go are you using (go version)?

go1.11 linux/amd64

Does this issue reproduce with the latest release?


What operating system and processor architecture are you using (go env)?

GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build705714475=/tmp/go-build -gno-record-gcc-switches"

What did you do?

$ mkdir a && cd a

$ cat <<EOF > x.go
package main
import _ ""
func main() {}

$ cat <<EOF > go.mod

$ GO111MODULE=on go build
go: finding v1.3.1
go: downloading v1.3.1

$ cat go.mod

require v1.3.1

$ GO111MODULE=on go mod tidy
go: finding latest
go: finding latest
go: downloading v0.0.0-20180909124046-d0be0721c37e

$ cat go.mod

require ( v1.3.1 v0.0.0-20180909124046-d0be0721c37e // indirect

What did you expect to see?

go mod tidy doesn't add any new entries to go.mod.

What did you see instead?

An indirect dependency was added: v0.0.0-20180909124046-d0be0721c37e // indirect

Copy link

myitcv commented Sep 12, 2018

You can use go mod why -m to answer the question on why this (indirect) dependency is present:

export GOPATH=$(mktemp -d)
cd $(mktemp -d)
mkdir hello
cd hello
go mod init
cat <<EOF > x.go
package main
import _ ""
func main() {}
go mod tidy
go mod why -m



The reason is that go mod tidy is agnostic of GOOS/GOARCH or build tags; go build is lazy and only does the minimal amount of work required for the current GOOS/GOARCH and build tags.

cc @bcmills - I wonder whether we should update the documentation for go mod tidy to include some note about this operation being agnostic of GOOS/GOARCH and build tags:

usage: go mod tidy [-v]

Tidy makes sure go.mod matches the source code in the module.
It adds any missing modules necessary to build the current module's
packages and dependencies, and it removes unused modules that
don't provide any relevant packages. It also adds any missing entries
to go.sum and removes any unnecessary ones.

The -v flag causes tidy to print information about removed modules
to standard error.

Because one reading of the documentation is that go build and go mod tidy should leave go.mod in the same state.

Copy link

@myitcv @bcmills related to the documentation comment from @myitcv above, there is also this slightly older issue:

#26571 "cmd/go: clarify doc that go commands like 'go build' are not always sufficient to update go.mod and 'go mod -sync' is sometimes required to handle variability due to GOOS/GOARCH/build tags"

...which tries to highlight a few different places where the documentation seems to leave the impression with at least some readers that commands like go build are sufficient, e.g., this quote from the tip documentation:

Once the go.mod file exists, no additional steps are required: go commands like 'go build', 'go test', or even 'go list' will automatically add new dependencies as needed to satisfy imports.

That issue #26571 also cites the help for go mod -sync (which was how go mod tidy was spelled at the time) as missing any statement about GOOS/GOARCH.

And it is not that the doc is entirely missing the information, e.g., the "Maintaining module requirements" section says:

Any go command can determine that a module requirement is missing and must be added, even when considering only a single package from the module. On the other hand, determining that a module requirement is no longer necessary and can be deleted requires a full view of all packages in the module, across all possible build configurations (architectures, operating systems, build tags, and so on). The 'go mod tidy' command builds that view and then adds any missing module requirements and removes unnecessary ones.

But there are other pieces of the doc in other sections that seem to imply go build is just as comprehensive as go tidy at adding requirements (or at least it seems it can be read that way by some).

In short, I agree with @myitcv there is opportunity to clarify the documentation a bit on this topic.

@bcmills bcmills added Documentation NeedsFix The path to resolution is known, but the work has not been done. modules labels Sep 12, 2018
@bcmills bcmills added this to the Go1.12 milestone Sep 12, 2018
@bcmills bcmills changed the title cmd/go: go mod tidy adds an entry not added by go build cmd/go: document why go mod tidy adds entries beyond those added by go build Sep 12, 2018
@bcmills bcmills self-assigned this Dec 19, 2018
@andybons andybons modified the milestones: Go1.12, Go1.13 Feb 12, 2019
@andybons andybons modified the milestones: Go1.13, Go1.14 Jul 8, 2019
@rsc rsc modified the milestones: Go1.14, Backlog Oct 9, 2019
@rsc rsc unassigned bcmills Jun 23, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Documentation modules NeedsFix The path to resolution is known, but the work has not been done.
None yet

No branches or pull requests

6 participants