doc: update README.md for v1.1 release

README.md

@@ -7,42 +7,78 @@ report on the libraries used and under what license they can be used. It can
 also collect all of the license documents, copyright notices and source code
 into a directory in order to comply with license terms on redistribution.
 
+## Before you start
+
+To use this tool, make sure:
+
+* [You have Go v1.16 or later installed](https://golang.org/dl/)
+* Change directory to your go project, for example:
+
+  ```shell
+  git clone [email protected]:google/go-licenses.git
+  cd go-licenses
+  ```
+
+* Download required modules:
+
+  ```shell
+  go mod download
+  ```
+
 ## Installation
 
-To download and install this tool, make sure
-[you have Go v1.13 or later installed](https://golang.org/dl/), then run the
-following command:
+Use the following command to download and install this tool:
 
 ```shell
-$ go get github.com/google/go-licenses
+go install github.com/google/go-licenses@latest
 ```
 
+If you were using `go get` to install this tool, note that
+[starting in Go 1.17, go get is deprecated for installing binaries](https://go.dev/doc/go-get-install-deprecation).
+
 ## Reports
 
 ```shell
-$ go-licenses csv "github.com/google/trillian/server/trillian_log_server"
-google.golang.org/grpc,https://github.com/grpc/grpc-go/blob/master/LICENSE,Apache-2.0
-go.opencensus.io,https://github.com/census-instrumentation/opencensus-go/blob/master/LICENSE,Apache-2.0
-github.com/google/certificate-transparency-go,https://github.com/google/certificate-transparency-go/blob/master/LICENSE,Apache-2.0
-github.com/jmespath/go-jmespath,https://github.com/aws/aws-sdk-go/blob/master/vendor/github.com/jmespath/go-jmespath/LICENSE,Apache-2.0
-golang.org/x/text,https://go.googlesource.com/text/+/refs/heads/master/LICENSE,BSD-3-Clause
-golang.org/x/sync/semaphore,https://go.googlesource.com/sync/+/refs/heads/master/LICENSE,BSD-3-Clause
-github.com/prometheus/client_model/go,https://github.com/prometheus/client_model/blob/master/LICENSE,Apache-2.0
-github.com/beorn7/perks/quantile,https://github.com/beorn7/perks/blob/master/LICENSE,MIT
+$ go-licenses csv github.com/google/go-licenses
+github.com/emirpasic/gods,https://github.com/emirpasic/gods/blob/v1.12.0/LICENSE,BSD-2-Clause
+github.com/golang/glog,https://github.com/golang/glog/blob/23def4e6c14b/LICENSE,Apache-2.0
+github.com/golang/groupcache/lru,https://github.com/golang/groupcache/blob/41bb18bfe9da/LICENSE,Apache-2.0
+github.com/google/go-licenses,https://github.com/google/go-licenses/blob/HEAD/LICENSE,Apache-2.0
+github.com/google/go-licenses/internal/third_party/pkgsite,https://github.com/google/go-licenses/blob/HEAD/internal/third_party/pkgsite/LICENSE,BSD-3-Clause
+github.com/google/licenseclassifier,https://github.com/google/licenseclassifier/blob/3043a050f148/LICENSE,Apache-2.0
+github.com/google/licenseclassifier/stringclassifier,https://github.com/google/licenseclassifier/blob/3043a050f148/stringclassifier/LICENSE,Apache-2.0
+github.com/jbenet/go-context/io,https://github.com/jbenet/go-context/blob/d14ea06fba99/LICENSE,MIT
+github.com/kevinburke/ssh_config,https://github.com/kevinburke/ssh_config/blob/01f96b0aa0cd/LICENSE,MIT
+github.com/mitchellh/go-homedir,https://github.com/mitchellh/go-homedir/blob/v1.1.0/LICENSE,MIT
+github.com/otiai10/copy,https://github.com/otiai10/copy/blob/v1.6.0/LICENSE,MIT
+github.com/sergi/go-diff/diffmatchpatch,https://github.com/sergi/go-diff/blob/v1.2.0/LICENSE,MIT
+github.com/spf13/cobra,https://github.com/spf13/cobra/blob/v1.3.0/LICENSE.txt,Apache-2.0
+github.com/spf13/pflag,https://github.com/spf13/pflag/blob/v1.0.5/LICENSE,BSD-3-Clause
+github.com/src-d/gcfg,https://github.com/src-d/gcfg/blob/v1.4.0/LICENSE,BSD-3-Clause
+github.com/xanzy/ssh-agent,https://github.com/xanzy/ssh-agent/blob/v0.2.1/LICENSE,Apache-2.0
+go.opencensus.io,https://github.com/census-instrumentation/opencensus-go/blob/v0.23.0/LICENSE,Apache-2.0
+golang.org/x/crypto,https://cs.opensource.google/go/x/crypto/+/5e0467b6:LICENSE,BSD-3-Clause
+golang.org/x/mod/semver,https://cs.opensource.google/go/x/mod/+/v0.5.1:LICENSE,BSD-3-Clause
+golang.org/x/net,https://cs.opensource.google/go/x/net/+/69e39bad:LICENSE,BSD-3-Clause
+golang.org/x/sys,https://cs.opensource.google/go/x/sys/+/5a964db0:LICENSE,BSD-3-Clause
+golang.org/x/tools,https://cs.opensource.google/go/x/tools/+/v0.1.9:LICENSE,BSD-3-Clause
+golang.org/x/xerrors,https://cs.opensource.google/go/x/xerrors/+/5ec99f83:LICENSE,BSD-3-Clause
+gopkg.in/src-d/go-billy.v4,https://github.com/src-d/go-billy/blob/v4.3.2/LICENSE,Apache-2.0
+gopkg.in/src-d/go-git.v4,https://github.com/src-d/go-git/blob/v4.13.1/LICENSE,Apache-2.0
+gopkg.in/warnings.v0,https://github.com/go-warnings/warnings/blob/v0.1.2/LICENSE,BSD-2-Clause
 ```
 
 This command prints out a comma-separated report (CSV) listing the libraries
 used by a binary/package, the URL where their licenses can be viewed and the
 type of license. A library is considered to be one or more Go packages that
 share a license file.
 
-URLs may not be available if the library is not checked out as a Git repository
-(e.g. as is the case when Go Modules are enabled).
+URLs are versioned based on go modules metadata.
 
-## Complying with license terms
+## Save licenses, copyright notices and source code (depending on license type)
 
 ```shell
-$ go-licenses save "github.com/google/trillian/server/trillian_log_server" --save_path="/tmp/trillian_log_server"
+go-licenses save "github.com/google/go-licenses" --save_path="/tmp/go-licenses-cli"
 ```
 
 This command analyzes a binary/package's dependencies and determines what needs
@@ -51,7 +87,7 @@ license terms. This typically includes the license itself and a copyright
 notice, but may also include the dependency's source code. All of the required
 artifacts will be saved in the directory indicated by `--save_path`.
 
-## Checking for forbidden licenses.
+## Checking for forbidden licenses
 
 ```shell
 $ go-licenses check github.com/logrusorgru/aurora
@@ -64,14 +100,44 @@ considered forbidden by the license classifer. See
 
 for licenses considered forbidden.
 
+## Usages
+
+Report usage:
+
+```shell
+go-licenses csv <package>
+```
+
+Save licenses, copyright notices and source code (depending on license type):
+
+```shell
+go-licenses save <package> --save_path=<save_path>
+```
+
+Checking for forbidden licenses usage:
+
+```shell
+go-licenses check <package>
+```
+
+go-licenses expects the same package argument format as `go build`. For example,
+it can be:
+
+* A rooted import path like `github.com/google/go-licenses`.
+* A relative path that denotes the package in that directory, like `.` or `./cmd/some-command`.
+
+To learn more about package argument, run `go help packages`.
+
+To learn more about go-licenses usages, run `go-licenses help`.
+
 ## Build tags
 
 To read dependencies from packages with
 [build tags](https://golang.org/pkg/go/build/#hdr-Build_Constraints). Use the
 `$GOFLAGS` environment variable.
 
 ```shell
-$ GOFLAGS="-tags=tools" licenses csv google.golang.org/grpc/test/tools
+$ GOFLAGS="-tags=tools" go-licenses csv google.golang.org/grpc/test/tools
 github.com/BurntSushi/toml,https://github.com/BurntSushi/toml/blob/master/COPYING,MIT
 google.golang.org/grpc/test/tools,Unknown,Apache-2.0
 honnef.co/go/tools/lint,Unknown,BSD-3-Clause
@@ -99,23 +165,11 @@ license terms.
 ### Error discovering URL
 
 In order to determine the URL where a license file can be viewed, this tool
-performs the following steps:
-
-1.  Locates the license file on disk.
-2.  Assuming that it is in a Git repository, inspects the repository's config to
-    find the URL of the remote "origin" repository.
-3.  Adds the license file path to this URL.
+generally performs the following steps:
 
-For this to work, the remote repository named "origin" must have a HTTPS URL.
-You can check this by running the following commands, inserting the path
-mentioned in the log message:
-
-```shell
-$ cd "path/mentioned/in/log/message"
-$ git remote get-url origin
-https://github.com/google/trillian.git
-```
+1. Locates the license file on disk.
+2. Parses go module metadata and finds the remote repo and version.
+3. Adds the license file path to this URL.
 
-If you want the tool to use a different remote repository, use the
-`--git_remote` flag. You can pass this flag repeatedly to make the tool try a
-number of different remotes.
+There are cases this tool finds an invalid/incorrect URL or fails to find the URL.
+Welcome [creating an issue](https://github.com/google/go-licenses/issues).