With bundler and other dependency management tools, it's easy for your project to depend on many packages. This decomposition is nice, but managing licenses becomes difficult. License Finder gathers info about the licenses of the packages in your project.
License Finder currently supports ruby gems, python eggs, and node modules. If you are looking to manage licenses on a java/maven project, we recommend using the license maven plugin.
Add license_finder to your project's Gemfile and bundle
:
gem 'license_finder'
License finder will generate reports of action items - i.e., dependencies that do not fall within your license "whitelist".
$ license_finder
(Note) If you wish to run license_finder without the progress spinner use the --quiet option.
License finder will include packages for all supported languages, as long as that language has a Gemfile/requirements.txt/package.json in the project directory.
On a brand new Rails project, you could expect license_finder
to output something like the following
(assuming you whitelisted the MIT license -- see Configuration):
Dependencies that need approval:
highline, 1.6.14, ruby
json, 1.7.5, ruby
mime-types, 1.19, ruby
rails, 3.2.8, other
rdoc, 3.12, other
rubyzip, 0.9.9, ruby
xml-simple, 1.1.1, other
The executable task will also write out a dependencies.db, dependencies.csv, and dependencies.html file in the doc/ directory (by default -- see Configuration).
The latter two files are human readable reports that you could send to your non-technical business partners, lawyers, etc.
license_finder
will also return a non-zero exit status if there are
unapproved dependencies. You could use this in a CI build, for example, to alert you whenever someone adds an
unapproved dependency to the project.
Run license_finder help
to see other available commands.
When license_finder
reports that a dependency's license is 'other', you should manually research what the actual
license is. When you have established the real license, you can record it with:
$ license_finder license MIT my_unknown_dependency
This command would assign the MIT license to the dependency my_unknown_dependency
.
Whenever you have a dependency that falls outside of your whitelist, license_finder
will tell you.
If your business decides that this is an acceptable risk, you can manually approve the dependency by using the
license_finder approve
command.
For example, lets assume you've only
whitelisted the "MIT" license in your config/license_finder.yml
. You then add the awesome_gpl_gem
to your Gemfile,
which we'll assume is licensed with the GPL
license. You then run license_finder
and see
the gem listed in the output:
awesome_gpl_gem, 1.0.0, GPL
Your business tells you that in this case, it's acceptable to use this gem. You now run:
$ license_finder approve awesome_gpl_gem
If you rerun license_finder
, you should no longer see awesome_gpl_gem
in the output.
Licenses can be added to a whitelist that tells LicenseFinder to automatically approve dependencies using the specified licenses.
These licenses can be managed with the whitelist
command.
To list licenses currently on the whitelist:
$ license_finder whitelist list
To add a licenses to the whitelist:
$ license_finder whitelist add MIT [BSD [...]]
To remove a licenses from the whitelist:
$ license_finder whitelist remove MIT [BSD [...]]
Bundler groups can be added to an ignore list which will prevent LicenseFinder from evaluating their licenses.
These groups can be managed with the ignored_bundler_groups
command.
To list currently ignored Bundler groups:
$ license_finder ignored_bundler_groups list
To add a group to the ignored Bundler groups:
$ license_finder ignored_bundler_groups add development
To remove a group from the ignored Bundler groups:
$ license_finder ignored_bundler_groups remove development
license_finder can track dependencies that Bundler/PyPi/NPM doesn't know about (JS libraries that don't appear in your Gemfile/requirements.txt/package.json, etc.)
$ license_finder dependencies add MIT my_js_dep 0.1.2
To automatically approve a non-bundler dependency when you add it, use:
$ license_finder dependencies add MIT my_js_dep 0.1.2 --approve
The version is optional. Run license_finder dependencies help
for additional documentation about
managing non-Bundler dependencies.
license_finder cannot automatically detect when a non-Bundler dependency has been removed from your project, so you can use:
$ license_finder dependencies remove my_js_dep
The HTML report generated by license_finder will have the name of your project at the top. By default, this is set to the name of your working directory. However, this can be changed using the command line:
$ license_finder project_name set 'My Project Name'
The changes will be reflected in the report the next time you run license_finder.
The first time you run license_finder
it will create a default configuration file ./config/license_finder.yml
:
---
whitelist:
#- MIT
#- Apache 2.0
ignore_groups:
#- test
#- development
dependencies_file_dir: './doc/'
project_name: My Project Name
By modifying this file, you can configure license_finder's behavior. Whitelisted
licenses will be automatically approved
and ignore_groups
will limit which dependencies are included in your license report. You can store the license database
and text files in another directory by changing dependencies_file_dir
.
The HTML report generated by license_finder has two sections, an overview at the top, and then a series of dependency summaries afterwards.
The individual dependency summary follows a pattern like this:
If you wish to cleanup your root directory you can run:
$ license_finder move
This will move your dependencies.* files to the /doc directory and update the config.
license_finder is compatible with ruby >= 1.9, and jruby.
For the good of humanity, please add a license to your gemspec!
Gem::Specification.new do |s|
s.name = "my_great_gem"
s.license = "MIT"
end
And add a LICENSE
file to your gem that contains your license text.
- Send an email to the list: [email protected]
- View the project backlog at Pivotal Tracker: https://www.pivotaltracker.com/s/projects/234851
- Fork the project
- Create a feature branch
- Make your feature addition or bug fix (with tests)
- Rebase on top of master
- Send a pull request
To successfully run the test suite, you will need node.js, and python installed.
LicenseFinder is released under the MIT License. http://www.opensource.org/licenses/mit-license