Skip to content

Commit

Permalink
doc: update README.md for v1.1 release
Browse files Browse the repository at this point in the history
  • Loading branch information
@Bobgy
Bobgy committed Mar 12, 2022
1 parent d483853 commit a7103d5
Showing 1 changed file with 91 additions and 37 deletions.
128 changes: 91 additions & 37 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 git@github.com: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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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).

0 comments on commit a7103d5

Please sign in to comment.