Name: bombora-auto-changelog
Owner: Bombora
Description: Command line tool for generating a changelog from git tags and commit history
Created: 2018-01-14 18:58:53.0
Updated: 2018-01-14 18:59:55.0
Pushed: 2018-01-19 00:49:43.0
Homepage: null
Size: 173
Language: JavaScript
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
Command line tool for generating a changelog from git tags and commit history
install -g auto-changelog
Simply run auto-changelog in the root folder of a git repository. git log is run behind the scenes in order to parse the commit history.
e: auto-changelog [options]
ons:
, --output [file] # output file, default: CHANGELOG.md
, --template [template] # specify template to use [compact, keepachangelog, json], default: compact
, --remote [remote] # specify git remote to use for links, default: origin
, --package # use version from package.json as latest release
, --latest-version [version] # use specified version as latest release
, --unreleased # include section for unreleased changes
, --commit-limit [count] # number of commits to display per release, default: 3
, --issue-url [url] # override url for issues, use {id} for issue id
--issue-pattern [regex] # override regex pattern for issues in commit messages
--ignore-commit-pattern [regex] # pattern to ignore when parsing commits
--starting-commit [hash] # starting commit to use for changelog generation
--tag-prefix [prefix] # prefix used in version tags, default: v
, --version # output the version number
, --help # output usage information
ite log to CHANGELOG.md in current directory
-changelog
ite log to HISTORY.md
-changelog --output HISTORY.md
ite log using keepachangelog template
-changelog --template keepachangelog
ite log using custom handlebars template in current directory
-changelog --template my-custom-template.hbs
ange rendered commit limit to 5
-changelog --commit-limit 5
sable the commit limit, rendering all commits
-changelog --commit-limit false
By default, changelogs will link to the appropriate pages for commits, issues and merge requests based on the origin remote of your repo. GitHub, BitBucket and GitLab are all supported. If you close issues using keywords but refer to issues outside of your repository, you can use --issue-url to link somewhere else:
nk all issues to redmine
-changelog --issue-url https://www.redmine.org/issues/{id}
Use --tag-prefix [prefix] if you prefix your version tags with a certain string:
en all versions are tagged like my-package/1.2.3
-changelog --tag-prefix my-package/
You can also set any option in package.json under the auto-changelog key, using camelCase options:
ame": "my-awesome-package",
ersion": "1.0.0",
cripts": {
// ...
uto-changelog": {
"output": "HISTORY.md",
"template": "keepachangelog",
"unreleased": true,
"commitLimit": false
auto-changelog is designed to be as flexible as possible, providing a clear changelog for any project. The only absolute requirement is that all versions are tagged using semver tag names. This happens by default when using npm version.
There are some less strict requirements to improve your changelog:
Install auto-changelog to dev dependencies:
install auto-changelog --save-dev
add auto-changelog --dev
Add auto-changelog -p && git add CHANGELOG.md to the version scripts in your package.json:
ame": "my-awesome-package",
ersion": "1.0.0",
evDependencies": {
"auto-changelog": "*"
cripts": {
"version": "auto-changelog -p && git add CHANGELOG.md"
Using -p or --package uses the version from package.json as the latest release, so that all commits between the previous release and now become part of that release. Essentially anything that would normally be parsed as Unreleased will now come under the version from package.json
Now every time you run npm version, the changelog will automatically update and be part of the version commit.
If you aren?t happy with the default templates or want to tweak something, you can point to a handlebars template in your local repo. Check out the existing templates to see what is possible.
Save changelog-template.hbs somewhere in your repo:
Changelog
ustom changelog template. Don?t worry about indentation here; it is automatically removed from the output.
ach releases}}
ery release has a {{title}} and a {{href}} you can use to link to the commit diff.
also has an {{isoDate}} and a {{niceDate}} you might want to use.
#each merges}}
- A merge has a {{message}}, an {{id}} and a {{href}} to the PR.
/each}}
#each fixes}}
- Each fix has a {{commit}} with a {{commit.subject}}, an {{id}} and a {{href}} to the fixed issue.
/each}}
#each commits}}
- Commits have a {{shorthash}}, a {{subject}} and a {{href}}, amongst other things.
/each}}
ach}}
Then just use --template to point to your template:
-changelog --template changelog-template.hbs
To see exactly what data is passed in to the templates, you can generate a JSON version of the changelog:
-changelog --template json --output changelog-data.json
By default, auto-changelog will parse GitHub-style issue fixes in your commit messages. If you use Jira or an alternative pattern in your commits to reference issues, you can pass in a custom regular expression to --issue-pattern along with --issue-url:
rse Jira-style issues in your commit messages, like PROJECT-418
-changelog --issue-pattern [A-Z]+-\d+ --issue-url https://issues.apache.org/jira/browse/{id}
Or, in your package.json:
ame": "my-awesome-package",
uto-changelog": {
"issueUrl": "https://issues.apache.org/jira/browse/",
"issuePattern": "[A-Z]+-\d+"
If you use a certain pattern before or after the issue number, like fixes {id}, just use a capturing group:
his commit fixes ISSUE-123" will now parse ISSUE-123 as an issue fix
-changelog --issue-pattern "[Ff]ixes ([A-Z]+-\d+)"
1.xIf you are upgrading from 0.x, the same options are still supported out of the box. Nothing will break, but your changelog may look slightly different:
compactkeepachangelog format, use --template keepachangelog- instead of * for lists--commit-limit to change this--unreleased to include themIf anything isn?t working correctly, open an issue.
See keepachangelog.com.
The command parses your git commit history and generates a changelog based on tagged versions, merged pull requests and closed issues. See a simple example in this very repo.
Because keeping a changelog can be tedious and difficult to get right. If you don?t have the patience for a hand-crafted, bespoke changelog then this makes keeping one rather easy. It also can be automated if you?re feeling extra lazy.