Skip to content

Commit

Permalink
Format README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
Rob Percival committed Nov 7, 2019
1 parent 4ad9cbd commit 6dee590
Showing 1 changed file with 33 additions and 13 deletions.
46 changes: 33 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
# Licenses tool

This tool analyzes the dependency tree of a Go package/binary. It can output a 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.
This tool analyzes the dependency tree of a Go package/binary. It can output a
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.

## Reports

Expand All @@ -16,17 +19,25 @@ github.com/prometheus/client_model/go,https://github.com/prometheus/client_model
github.com/beorn7/perks/quantile,https://github.com/beorn7/perks/blob/master/LICENSE,MIT
```

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.
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 will 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 will 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).

## Complying with license terms

```shell
$ licenses save "github.com/google/trillian/server/trillian_log_server" --save_dir="/tmp/trillian_log_server"
```

This command analyzes a binary/package's dependencies and determines what needs to be redistributed alongside that binary/package in order to comply with the 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_dir`.
This command analyzes a binary/package's dependencies and determines what needs
to be redistributed alongside that binary/package in order to comply with the
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_dir`.

## Checking for forbidden licenses.

Expand All @@ -43,27 +54,36 @@ for licenses considered forbidden.

## Warnings and errors

The tool will log warnings and errors in some scenarios. This section provides guidance on addressing them.
The tool will log warnings and errors in some scenarios. This section provides
guidance on addressing them.

### Dependency contains non-Go code

A warning will be logged when a dependency contains non-Go code. This is because it is not possible to check the non-Go code for further dependencies, which may conceal additional license requirements. You should investigate this code to determine whether it has dependencies and take action to comply with their license terms.
A warning will be logged when a dependency contains non-Go code. This is because
it is not possible to check the non-Go code for further dependencies, which may
conceal additional license requirements. You should investigate this code to
determine whether it has dependencies and take action to comply with their
license terms.

### Error discovering URL

In order to determine the URL where a license file can be viewed, this tool performs the following steps:
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.
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.

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:
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
```

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.
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.

0 comments on commit 6dee590

Please sign in to comment.