cmd/go: document import path meta tag discovery in go help remote

R=golang-dev, rsc CC=golang-dev https://golang.org/cl/5787059

cmd/go: document import path meta tag discovery in go help remote
R=golang-dev, rsc CC=golang-dev https://golang.org/cl/5787059
312ff5b5 · Brad Fitzpatrick · 2c46569f · 312ff5b5 · 312ff5b5
Commit 312ff5b5 authored Mar 08, 2012 by Brad Fitzpatrick
Hide whitespace changes
Inline Side-by-side

Showing with 84 additions and 2 deletions

src/cmd/go/doc.go src/cmd/go/doc.go +42 -1

src/cmd/go/help.go src/cmd/go/help.go +42 -1

No files found.
--- a/src/cmd/go/doc.go
+++ b/src/cmd/go/doc.go
@@ -564,7 +564,12 @@ A few common code hosting sites have special syntax:
 		import "launchpad.net/~user/project/branch"
 		import "launchpad.net/~user/project/branch/sub/directory"

-For code hosted on other servers, an import path of the form
+For code hosted on other servers, import paths may either be qualified
+with the version control type, or the go tool can dynamically fetch
+the import path over https/http and discover where the code resides
+from a <meta> tag in the HTML.
+
+To declare the code location, an import path of the form

 	repository.vcs/path

@@ -593,6 +598,42 @@ When a version control system supports multiple protocols,
 each is tried in turn when downloading.  For example, a Git
 download tries git://, then https://, then http://.

+If the import path is not a known code hosting site and also lacks a
+version control qualifier, the go tool attempts to fetch the import
+over https/http and looks for a <meta> tag in the document's HTML
+<head>.
+
+The meta tag has the form:
+
+	<meta name="go-import" content="import-prefix vcs repo-root">
+
+The import-prefix is the import path correponding to the repository
+root. It must be a prefix or an exact match of the package being
+fetched with "go get". If it's not an exact match, another http
+request is made at the prefix to verify the <meta> tags match.
+
+The vcs is one of "git", "hg", "svn", etc,
+
+The repo-root is the root of the version control system
+containing a scheme and not containing a .vcs qualifier.
+
+For example,
+
+	import "example.org/pkg/foo"
+
+will result in the following request(s):
+
+	https://example.org/pkg/foo?go-get=1 (preferred)
+	http://example.org/pkg/foo?go-get=1  (fallback)
+
+If that page contains the meta tag
+
+	<meta name="go-import" content="example.org git https://code.org/r/p/exproj">
+
+the go tool will verify that https://example.org/?go-get=1 contains the
+same meta tag and then git clone https://code.org/r/p/exproj into
+GOPATH/src/example.org.
+
 New downloaded packages are written to the first directory
 listed in the GOPATH environment variable (see 'go help gopath').


--- a/src/cmd/go/help.go
+++ b/src/cmd/go/help.go
@@ -96,7 +96,12 @@ A few common code hosting sites have special syntax:
 		import "launchpad.net/~user/project/branch"
 		import "launchpad.net/~user/project/branch/sub/directory"

-For code hosted on other servers, an import path of the form
+For code hosted on other servers, import paths may either be qualified
+with the version control type, or the go tool can dynamically fetch
+the import path over https/http and discover where the code resides
+from a <meta> tag in the HTML.
+
+To declare the code location, an import path of the form

 	repository.vcs/path

@@ -125,6 +130,42 @@ When a version control system supports multiple protocols,
 each is tried in turn when downloading.  For example, a Git
 download tries git://, then https://, then http://.

+If the import path is not a known code hosting site and also lacks a
+version control qualifier, the go tool attempts to fetch the import
+over https/http and looks for a <meta> tag in the document's HTML
+<head>.
+
+The meta tag has the form:
+
+	<meta name="go-import" content="import-prefix vcs repo-root">
+
+The import-prefix is the import path correponding to the repository
+root. It must be a prefix or an exact match of the package being
+fetched with "go get". If it's not an exact match, another http
+request is made at the prefix to verify the <meta> tags match.
+
+The vcs is one of "git", "hg", "svn", etc,
+
+The repo-root is the root of the version control system
+containing a scheme and not containing a .vcs qualifier.
+
+For example,
+
+	import "example.org/pkg/foo"
+
+will result in the following request(s):
+
+	https://example.org/pkg/foo?go-get=1 (preferred)
+	http://example.org/pkg/foo?go-get=1  (fallback)
+
+If that page contains the meta tag
+
+	<meta name="go-import" content="example.org git https://code.org/r/p/exproj">
+
+the go tool will verify that https://example.org/?go-get=1 contains the
+same meta tag and then git clone https://code.org/r/p/exproj into
+GOPATH/src/example.org.
+
 New downloaded packages are written to the first directory
 listed in the GOPATH environment variable (see 'go help gopath').