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: replace directives are not thoroughly documented #32058

heschi opened this issue May 15, 2019 · 5 comments

cmd/go: replace directives are not thoroughly documented #32058

heschi opened this issue May 15, 2019 · 5 comments


Copy link

@heschi heschi commented May 15, 2019

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

$ go version
go version devel +f0c383b833 Wed May 1 16:53:19 2019 +0000 linux/amd64

Does this issue reproduce with the latest release?


What did you do?

Read go help modules and go help go.mod.

What did you expect to see?

Some discussion of what replacements are and what they do.

What did you see instead?

The only documentation I can find is these lines in go help go.mod:

	replace bad/thing v1.4.5 => good/thing v1.4.5
	replace, to replace a module version with a different module version.
Exclude and replace apply only in the main module's go.mod and are ignored
in dependencies.  See for details.

I think there's probably more to say about how replace works. For example, it doesn't explicitly state that the thing to replace is on the left side of the arrow. It also doesn't mention that the version on the left is optional.

@FiloSottile FiloSottile added this to the Go1.13 milestone May 15, 2019
@andybons andybons removed this from the Go1.13 milestone Jul 8, 2019
@andybons andybons added this to the Go1.14 milestone Jul 8, 2019
Copy link

@shivi28 shivi28 commented Aug 2, 2019

Hello @heschik Can I pick up this task

Copy link
Contributor Author

@heschi heschi commented Aug 2, 2019

@jayconrod or @bcmills would be the ones to review it, and they might be pretty busy getting 1.13 ready, so there might be a bit of delay on the review. For my part I say go for it.

Copy link

@bcmills bcmills commented Aug 2, 2019

A CL to document the existing behavior would be fine, but note that for Go 1.14 we're planning to both revamp the semantics of replace directives (#26904) and reorganize the modules documentation.

@rsc rsc removed this from the Go1.14 milestone Oct 9, 2019
@rsc rsc added this to the Backlog milestone Oct 9, 2019
Copy link

@gopherbot gopherbot commented Feb 19, 2020

Change mentions this issue: design/36460: add design for lazy module loading

gopherbot pushed a commit to golang/proposal that referenced this issue Mar 5, 2020
Updates golang/go#36460
Updates golang/go#27900
Updates golang/go#26955
Updates golang/go#30831
Updates golang/go#32058
Updates golang/go#32380
Updates golang/go#32419
Updates golang/go#33370
Updates golang/go#33669
Updates golang/go#36369

Change-Id: I1d4644e3e8b4e688c2fc5a569312495e5072b7d7
Reviewed-by: Russ Cox <>
Copy link

@bcmills bcmills commented Aug 3, 2020

We should also note that replace replaces the source code of the given version, rather than retargeting requirements on the given version to instead require something else.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
7 participants