diff options
author | Alan Donovan <adonovan@google.com> | 2015-09-01 22:26:03 +0000 |
---|---|---|
committer | android-build-merger <android-build-merger@google.com> | 2015-09-01 22:26:03 +0000 |
commit | a227aebfe38d87dc82a6d4be883208adf00f2f3f (patch) | |
tree | c4336f80baf9f406cbd78c01112f8a2e3167d6b5 | |
parent | d7b963bda9cca44530a5b8c0b1f60e2be62cbdd9 (diff) | |
parent | 680b4cd5a825aeeab55760b43131fce777d5b602 (diff) | |
download | tools-a227aebfe38d87dc82a6d4be883208adf00f2f3f.tar.gz |
cmd/fiximports: added package-level documentation
automerge: 680b4cd
* commit '680b4cd5a825aeeab55760b43131fce777d5b602':
cmd/fiximports: added package-level documentation
-rw-r--r-- | cmd/fiximports/main.go | 64 |
1 files changed, 64 insertions, 0 deletions
diff --git a/cmd/fiximports/main.go b/cmd/fiximports/main.go index 5a912e8..86ae777 100644 --- a/cmd/fiximports/main.go +++ b/cmd/fiximports/main.go @@ -5,6 +5,68 @@ // The fiximports command fixes import declarations to use the canonical // import path for packages that have an "import comment" as defined by // https://golang.org/s/go14customimport. +// +// +// Background +// +// The Go 1 custom import path mechanism lets the maintainer of a +// package give it a stable name by which clients may import and "go +// get" it, independent of the underlying version control system (such +// as Git) or server (such as github.com) that hosts it. Requests for +// the custom name are redirected to the underlying name. This allows +// packages to be migrated from one underlying server or system to +// another without breaking existing clients. +// +// Because this redirect mechanism creates aliases for existing +// packages, it's possible for a single program to import the same +// package by its canonical name and by an alias. The resulting +// executable will contain two copies of the package, which is wasteful +// at best and incorrect at worst. +// +// To avoid this, "go build" reports an error if it encounters a special +// comment like the one below, and if the import path in the comment +// does not match the path of the enclosing package relative to +// GOPATH/src: +// +// $ grep ^package $GOPATH/src/github.com/bob/vanity/foo/foo.go +// package foo // import "vanity.com/foo" +// +// The error from "go build" indicates that the package canonically +// known as "vanity.com/foo" is locally installed under the +// non-canonical name "github.com/bob/vanity/foo". +// +// +// Usage +// +// When a package that you depend on introduces a custom import comment, +// and your workspace imports it by the non-canonical name, your build +// will stop working as soon as you update your copy of that package +// using "go get -u". +// +// The purpose of the fiximports tool is to fix up all imports of the +// non-canonical path within a Go workspace, replacing them with imports +// of the canonical path. Following a run of fiximports, the workspace +// will no longer depend on the non-canonical copy of the package, so it +// should be safe to delete. It may be necessary to run "go get -u" +// again to ensure that the package is locally installed under its +// canonical path, if it was not already. +// +// The fiximports tool operates locally; it does not make HTTP requests +// and does not discover new custom import comments. It only operates +// on non-canonical packages present in your workspace. +// +// The -baddomains flag is a list of domain names that should always be +// considered non-canonical. You can use this if you wish to make sure +// that you no longer have any dependencies on packages from that +// domain, even those that do not yet provide a canical import path +// comment. For example, the default value of -baddomains includes the +// moribund code hosting site code.google.com, so fiximports will report +// an error for each import of a package from this domain remaining +// after canonicalization. +// +// To see the changes fiximports would make without applying them, use +// the -n flag. +// package main import ( @@ -50,6 +112,8 @@ The package... arguments specify a list of packages in the style of the go tool; see "go help packages". Hint: use "all" or "..." to match the entire workspace. +For details, see http://godoc.org/golang.org/x/tools/cmd/fiximports. + Flags: -n: dry run: show changes, but don't apply them -baddomains a comma-separated list of domains from which packages |