# licensor: plop a license in there

Are you tired of copying and pasting licenses into your new projects?
Do you always forget what the dang github api thing is?
Or I don't know, have some other reason why doing licenses is hard?

Well now you don't have to worry!
Just run `licensor` in your new repo and BLAMMO!
Done.

## Installing

`licensor` comes with a Makefile for ease-of-installing, but it's just a shell
script.  You can drop it in your `$PATH`.

## Usage

literally taken from `licensor -h`:

```
licensor: easily provide a license for a project
USAGE: licensor [-h|-l|-L]
licensor -s QUERY
licensor [FLAGS] [OPTIONS] [LICENSE]

FLAGS:
-h   Display this help and exit.
-l   List available licenses and exit.
-L   List available licenses, disregarding cache.
     This flag will re-download the license repo.

-f   Overwrite existing license.
-q   Be quiet (don't log anything).
-z   Fold output to 70 characters (see -w).
-Z   Disable folding of output.
-p   Include "optional" license content.
-P   Don't include "optional" content.

OPTIONS:
-s QUERY        Search for a license matching QUERY.
                Only license titles are searched.

-y YEARS        Set copyright date(s) to YEARS.
                Default: $(date +%Y).
-a AUTHORS      Set copyright holder(s) to AUTHOR.
                Default: use the first of
                 - git config --get user.name
                 - getent password $USER
                 - $USER
 -e EMAILS         Set AUTHOR's EMAIL address.
                Default: $(git config --get user.email),
                or stay blank.
 -c COPYRIGHT   Set the entire COPYRIGHT string to print.
                By default, it's built from the above information:
                "Copyright (C) <year> <author> <email>".
 -w WIDTH       Fold the output to WIDTH characters.
                Default: 70.
 -o FILE        Output the fetched license to FILE.
                Default: $PWD/COPYING.

PARAMETERS:
 LICENSE        The license to use.
                Default: MIT.
```

You can use an output file of `-` (i.e., `licensor -o-`) to print the license to
stdout.

### Available licenses

Licenses are pulled from [SPDX][]'s [git repository of licenses][spdx-git].
This includes all of the more common licenses, and honestly, if you're wanting
to do something weird is `licensor` the right project for you?

*That being said, adding the ability for arbitrary license "repositories" is
probably for the best.*

[SPDX]: https://spdx.org/licenses/
[spdx-git]: https://github.com/spdx/license-list-data/

### Templating

SPDX uses a [particular templating format][spdx-template-format] that `licensor`
can read and use.  As of v1.0, only `beginOptional`/`endOptional` and
`var;name="copyright"` fields are filled in; all others are stripped from output.

## Configuring

There are some environment variables you can set to change `licensor`'s default
behavior:

- `LICENSE_REPO_VERSION` : 3.17
- `LICENSE_REPO_URL` : `https://github.com/spdx/license-list-data/archive/refs/tags/v$LICENSE_REPO_VERSION.tar.gz`
- `LICENSE_REPO_PATH` : `license-list-data-$LICENSE_REPO_VERSION/template`
- `LICENSOR_LICENSE` : MIT
- `LICENSOR_OUTPUT_FILE` : COPYING

## Contributing

Send me an [email](mailto:acdw@acdw.net).

## License

MIT, baby.

See [COPYING](https://git.acdw.net/licensor/tree/COPYING) for details.

## Author

Case Duckworth <acdw@acdw.net> wrote this.
He did not look around for existing solutions.