Understanding Go Vanity URLs: How go get -x Reveals the Full ?go-get=1 Handshake

Go packages use vanity URLs —custom domain import paths like k8s.io/api or go.uber.org/zap —instead of raw repository URLs to present a clean, branded identity and avoid name collisions.

Why vanity URLs exist

Establish brand authority and trust.

Allow code to move between hosting platforms without changing import paths.

Provide shorter, more readable import statements.

Prevent impersonation by similarly named repositories.

Core protocol

The Go toolchain resolves a vanity import by sending an HTTP request with the query parameter ?go-get=1. The server returns a plain‑text HTML page containing two meta tags: # GET https://k8s.io/api?go-get=1 1. go-import – tells go get the VCS type and the real repository URL. Example:

<meta name="go-import" content="go.uber.org/zap git https://github.com/uber-go/zap">

2. go-source – used by the official documentation site ( pkg.go.dev) to build source‑code links. Example:

<meta name="go-source" content="go.uber.org/zap https://github.com/uber-go/zap https://github.com/uber-go/zap/tree/master{/dir} https://github.com/uber-go/zap/blob/master{/dir}/{file}#L{line}">

Live trace with go get -x

Running the command with GOPROXY=direct disables the module proxy and prints every external call:

$ GOPROXY=direct go get -x -v go.uber.org/zap
# get https://go.uber.org/?go-get=1
# get https://go.uber.org/zap?go-get=1
# get https://go.uber.org/?go-get=1: 200 OK (2.336s)
# get https://go.uber.org/zap?go-get=1: 200 OK (2.336s)
get "go.uber.org/zap": found meta tag vcs.metaImport{Prefix:"go.uber.org/zap", VCS:"git", RepoRoot:"https://github.com/uber-go/zap", SubDir:""} at //go.uber.org/zap?go-get=1
mkdir -p $GOPATH/pkg/mod/cache/vcs
cd $GOPATH/pkg/mod/cache/vcs/[hash]; git ls-remote -q --end-of-options origin
# … additional steps for dependencies such as go.uber.org/multierr …
go: added go.uber.org/multierr v1.10.0
go: added go.uber.org/zap v1.28.0

The log shows the stages:

Probe the domain boundaries with two parallel ?go-get=1 requests.

Parse the go-import meta tag to obtain the VCS mapping.

Create a local cache directory and lock file.

Invoke git to fetch the repository.

Verify module checksums against sum.golang.org.

Recursively repeat the process for transitive dependencies.

Interaction with the proxy and index

If GOPROXY is not set to direct, the default proxy.golang.org will first fetch the code, cache it, and record the module name in the public index index.golang.org. This index drives the background workers of pkg.go.dev, which later retrieve the same go-source meta tag and the zipped source archive.

Documentation rendering

The documentation server uses the go-source template to generate static hyperlinks that point directly to the source file and line number on GitHub. Hovering over a symbol such as NewProduction in the UI shows a link that opens the exact location in the upstream repository.

Summary

The three‑part protocol ( ?go-get=1, go-import, go-source) connects the Go CLI and the documentation ecosystem, enabling seamless source retrieval and rich, source‑linked documentation for packages that use vanity domains.