auto-authors

Command line tool for generating a list of authors from git commit history and github.

Created in the spirit of auto-changelog.

Installation

$ npm install auto-authors

# or globally, if you like

$ npm install -g auto-authors

Usage

NOTE: You may need to provide your github access token to get past API limits, see below.

$ auto-authors 

This will create a AUTHORS.md file with all authors of a given repo, in the order of contribution, using the compact template.

Options

auto-authors can also take some argument, which you can use to control its output. You can use --help to see this list as well.

options | default | description ------- | ------- | ----------- template | compact | The template to use, either one of the provided tempates (compact, complete, or json) or the path to a custom template. output | AUTHORS.md | The file to write the author info to.

Optional Authentication

To get around GitHub's API rate limiting you can provide a personal OAuth2 access token, e.g.

$ OAUTH_TOKEN=b2935592ba8667b668d4a433162bc3d2b96e9e1b auto-authors

You can create and revoke personal access tokens in your account settings. For this use case no special permissions are required, so public access is sufficient.

Automatic authors generation

Running the script as part of the npm publishing workflow can automatically update the authors list. The simplest way to do this is via the version npm script.

"scripts": {
  "version": "auto-authors && git add AUTHORS.md"
}

Now when you use npm version to increment your package's version, the updated authors file will be committed with the version commit. Adjust that command as needed based on your desired template and output file.

Programmatic Usage

If you'd like to use this module in node, it exports 3 methods, all of which return promises:

method | description ------ | ----------- githubAuthors() | Resolves to an array of objects for each author. The objects contain name, email, and username depending on what information is available, and uses the Github API to get the username. gitAuthors() | Resolves to an array of objects for each author. The objects contain name and email and does not use the Github API at all. compileTemplate(template, data) | Resolves to a string, containing the markdown output given the template and data. data should be an object with an authors property that contains an array of authors (from githubAuthors or gitAuthors).

License

MIT © David Trejo, Joe Fleming