Use a forked Go module

Whenever I want to work with a forked Go module, I have to look up how to do so. It doesn’t feel immediately obvious what to change. This note documents my current approach.

I need to do this when a third party module I depend on doesn’t include features I need. I fork the third party module and make some changes. But these changes are only available in my fork. These may get merged into a new version of the module but in the meantime I want to continue working off my fork.

In the example below, I’m working on a consumer of the Govmoni module that wraps the vSphere API. I want to use my forked version of the Govmoni module. In the root of my project, I run the following to replace the Govmoni module with my fork.

go mod edit -replace github.com/vmware/govmomi=github.com/billglover/govmomi

This modifies your go.mod file to include a replace statement like this:

module github.com/vmware/terraform-provider-namespace-management

go 1.18

require (
	...
	github.com/vmware/govmomi v0.28.0
)

require (
	...
)

replace github.com/vmware/govmomi => github.com/billglover/govmomi v0.28.1-0.20220530114342-728e458327e8

With this replacement, I can continue to use the original import path throughout my code. The Go module system will handle the replacement during build.

I’m unsure if this is the canonical way is to work on a forked Go module. This is one of those things that doesn’t come up often and so I end up looking up what to do each time I need it. If you do something different, I’d love to hear from you.