Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tomasbjerre/git-changelog-command-line
Command line tool to generate changelog, or releasenotes, from a git repository and a Handlebars template.
https://github.com/tomasbjerre/git-changelog-command-line
changelog conventional-commits releasenotes
Last synced: 4 days ago
JSON representation
Command line tool to generate changelog, or releasenotes, from a git repository and a Handlebars template.
- Host: GitHub
- URL: https://github.com/tomasbjerre/git-changelog-command-line
- Owner: tomasbjerre
- License: apache-2.0
- Created: 2016-01-27T17:32:46.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2024-10-16T20:35:02.000Z (3 months ago)
- Last Synced: 2024-12-23T00:09:45.390Z (11 days ago)
- Topics: changelog, conventional-commits, releasenotes
- Language: Java
- Homepage:
- Size: 994 KB
- Stars: 47
- Watchers: 3
- Forks: 13
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Git Changelog Command Line
[](https://maven-badges.herokuapp.com/maven-central/se.bjurr.gitchangelog/git-changelog-command-line)
[](https://www.npmjs.com/package/git-changelog-command-line)
[](https://www.npmjs.com/package/git-changelog-command-line)
[](https://hub.docker.com/r/tomasbjerre/git-changelog-command-line/)
This is a command line tool for generating a changelog, or releasenotes, from a GIT repository. It uses the [Git Changelog Lib](https://github.com/tomasbjerre/git-changelog-lib).
This is a Java application (runnable `jar`) packaged into an `NPM` package for convenience.
- The runnable `jar` can be found in [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22git-changelog-command-line%22) and used like `java -jar git-changelog-command-line-*.jar ....`.
- The `npm` package can be found in [NPM](https://www.npmjs.com/package/git-changelog-command-line).
- The `Docker` image can be found in [Dockerhub](https://hub.docker.com/r/tomasbjerre/git-changelog-command-line) and used like `docker run --mount src="$(pwd)",target=/usr/src/git-changelog-command-line,type=bind tomasbjerre/git-changelog-command-line:X --help`.
| Version | Java Version |
| ------------------------ | ------------ |
| version < 2.0.0 | 8 |
| 2.0.0 <= version < 2.3.0 | 11 |
| 2.3.0 <= version | 17 |
## Example - Simple
A changelog can be created like this.
```shell
npx git-changelog-command-line -std
```
Or, you can specify a template:
```shell
npx git-changelog-command-line -std -tec "
# Changelog
Changelog.
{{#tags}}
## {{name}}
{{#issues}}
{{#hasIssue}}
{{#hasLink}}
### {{name}} [{{issue}}]({{link}}) {{title}} {{#hasIssueType}} *{{issueType}}* {{/hasIssueType}} {{#hasLabels}} {{#labels}} *{{.}}* {{/labels}} {{/hasLabels}}
{{/hasLink}}
{{^hasLink}}
### {{name}} {{issue}} {{title}} {{#hasIssueType}} *{{issueType}}* {{/hasIssueType}} {{#hasLabels}} {{#labels}} *{{.}}* {{/labels}} {{/hasLabels}}
{{/hasLink}}
{{/hasIssue}}
{{^hasIssue}}
### {{name}}
{{/hasIssue}}
{{#commits}}
**{{{messageTitle}}}**
{{#messageBodyItems}}
* {{.}}
{{/messageBodyItems}}
[{{hash}}](https://github.com/{{ownerName}}/{{repoName}}/commit/{{hash}}) {{authorName}} *{{commitTime}}*
{{/commits}}
{{/issues}}
{{/tags}}
"
```
## Example - Semantic versioning from conventional commits
If you are using [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/):
```shell
[optional scope]:
[optional body]
[optional footer(s)]
```
The highest version can be determined with:
```shell
highestTag=$(npx git-changelog-command-line \
--print-highest-version-tag)
echo Last release detected as $highestTag
```
You can also get the tag with `--print-highest-version-tag`. Highest version may be `1.2.3` and highest tag may be `v1.2.3`.
Next version to release can be determined with:
```shell
nextVersion=$(npx git-changelog-command-line \
--print-next-version)
echo Next release based on commits is: $nextVersion
```
There are default patterns, but you can specify the patterns with:
- `--major-version-pattern REGEXP`
- `--minor-version-pattern REGEXP`
- `--patch-version-pattern REGEXP`
By default it will match anything as patch, like `chore: whatever` and not only `fix: whatever`. You can change that with:
```shell
highestVersion=$(npx git-changelog-command-line \
--print-highest-version)
highestVersionTag=$(npx git-changelog-command-line \
--print-highest-version-tag)
currentVersion=$(npx git-changelog-command-line \
--patch-version-pattern "^fix.*" \
--print-current-version)
if [ -z "$highestVersionTag" ]; then
echo "This is the first version in the repo, using 0.0.1 as version"
currentVersion=0.0.1
else if [ "$currentVersion" == "$highestVersion" ]; then
echo "No changes made that can be released"
else
echo "Changes detected and a new $currentVersion release can be made"
fi
```
A changelog can be rendered (using [Helpers](https://github.com/tomasbjerre/git-changelog-lib#Helpers)) like this:
```shell
npx git-changelog-command-line \
--to-ref HEAD \
--stdout \
--template-content "
# Changelog
{{#tags}}
{{#ifReleaseTag .}}
## [{{name}}](https://github.com/tomasbjerre/someproject/compare/{{name}}) ({{tagDate .}})
{{#ifContainsType commits type='feat'}}
### Features
{{#commits}}
{{#ifCommitType . type='feat'}}
- {{#eachCommitScope .}} **{{.}}** {{/eachCommitScope}} {{{commitDescription .}}} ([{{hash}}](https://github.com/tomasbjerre/someproject/commit/{{hashFull}}))
{{/ifCommitType}}
{{/commits}}
{{/ifContainsType}}
{{#ifContainsType commits type='fix'}}
### Bug Fixes
{{#commits}}
{{#ifCommitType . type='fix'}}
- {{#eachCommitScope .}} **{{.}}** {{/eachCommitScope}} {{{commitDescription .}}} ([{{hash}}](https://github.com/tomasbjerre/someproject/commit/{{hashFull}}))
{{/ifCommitType}}
{{/commits}}
{{/ifContainsType}}
{{/ifReleaseTag}}
{{/tags}}
"
```
Or you can prepend to the current changelog. You may get `$nextVersion` from `--print-next-version` and `$highestTag` from `--print-highest-version-tag`. Somehting like this:
```shell
npx git-changelog-command-line \
--from-ref $highestTag \
--to-ref HEAD \
--prepend-to-file CHANGELOG.md \
--template-content "
## $nextVersion
{{#ifContainsType commits type='feat'}}
## Features
{{#commits}}
{{#ifCommitType . type='feat'}}
{{#eachCommitScope .}} **{{.}}** {{/eachCommitScope}} {{{commitDescription .}}} ([{{hash}}](https://github.com/tomasbjerre/someproject/commit/{{hashFull}}))
{{/ifCommitType}}
{{/commits}}
{{/ifContainsType}}
{{#ifContainsType commits type='fix'}}
## Bug Fixes
{{#commits}}
{{#ifCommitType . type='fix'}}
{{#eachCommitScope .}} **{{.}}** {{/eachCommitScope}} {{{commitDescription .}}} ([{{hash}}](https://github.com/tomasbjerre/someproject/commit/{{hashFull}}))
{{/ifCommitType}}
{{/commits}}
{{/ifContainsType}}
"
```
### Example NPM and `package.json`
If you are using NPM, you may want to add this to your `package.json`:
```json
{
"scripts": {
"build": "echo build it...",
"release": "npm run set-version; npm run build && npm publish && npm run changelog",
"set-version": "npm version $(npx git-changelog-command-line --print-next-version)",
"changelog": "npx git-changelog-command-line -of CHANGELOG.md && git commit -a -m 'chore: changelog' && git push --follow-tags"
}
}
```
And if you do `npm run release` it will:
- Set version in `package.json`
- Build the repo
- Publish it
- Update CHANGELOG.md
## Example - custom helpers
You can supply your own helpers and use them in the template.
```shell
npx git-changelog-command-line \
--to-ref HEAD \
--stdout \
--template-content "
{{#commits}}
{{#startsWith messageTitle s='feat'}}
Starts with feat: "{{messageTitle}}"
first 10 letters of hash is: {{firstLetters hash number='10'}}
{{/startsWith}}
{{/commits}}
" \
--register-handlebars-helper "
Handlebars.registerHelper('firstLetters', function(input, options) {
const number = parseInt(options.hash['number'] || "0")
return input.substring(0,number);
});
Handlebars.registerHelper('startsWith', function(from, options) {
const s = options.hash['s']
if (new RegExp('^' + s + '.*').test(from)) {
return options.fn(this);
} else {
return options.inverse(this);
}
});
"
```
# Usage
Or from command line:
```shell
-cl, --custom-issue-link Custom issue link.
Supports variables like
${PATTERN_GROUP_1} to inject variables
from pattern.
: any string
Default: null
-cn, --custom-issue-name Custom issue name.
: any string
Default: null
-cp, --custom-issue-pattern Custom issue pattern.
: any string
Default: null
-ct, --custom-issue-title Custom issue title.
Supports variables like
${PATTERN_GROUP_1} to inject variables
from pattern.
: any string
Default: null
-df, --date-format Format to use when
printing dates.
: any string
Default: YYYY-MM-dd HH:mm:ss
-eh, --extended-headers Extended headers that
will send when access JIRA.
e.g. -eh CF-Access-
Client-ID:abcde12345xyz.access [Supports Multiple occurrences]
: any string
Default: Empty list
-en, --encoding Encoding to use when
writing content.
: any string
Default: UTF-8
-ex, --extended-variables Extended variables
that will be available as
{{extended.*}}. -ex "{\"var1\": \"
val1\"}" will print out "val1"
for a template like
"{{extended.var1}}"
: any string
Default:
-fre, --from-revision From revision.
: any string
Default: 0000000000000000000000000000000000000000
-frei, --from-revision-inclusiveness Include, or exclude,
specified revision.
: {INCLUSIVE | EXCLUSIVE | DEFAULT}
Default: DEFAULT
-gapi, --github-api GitHub API. Like:
https://api.github.
com/repos/tomasbjerre/git-changelog-command-line/
: any string
Default:
-ge, --github-enabled Enable parsing for
GitHub issues.
Default: disabled
-gl, --gitlab-enabled Enable parsing for
GitLab issues.
Default: disabled
-glp, --gitlab-issue-pattern GitLab issue pattern.
: any string
Default:
-glpn, --gitlab-project-name GitLab project name.
: any string
Default:
-gls, --gitlab-server GitLab server, like
https://gitlab.com/.
: any string
Default:
-glt, --gitlab-token GitLab API token.
: any string
Default:
-gtok, --github-token GitHub API OAuth2
token. You can get it from:
curl -u 'yourgithubuser' -d
'{"note":"Git Changelog Lib"}'
https://api.github.
com/authorizations
: any string
Default:
-h, --help : an argument to print help for
Default: If no specific parameter is given the whole usage text is given
-handlebars-helper-file, -hhf Can be used to add
extra helpers.
: a file path
Default: /home/bjerre/workspace/git-changelog/git-changelog-command-line/.
-ini, --ignore-commits-without-issue Ignore commits that is
not included in any issue.
Default: disabled
-iot, --ignore-older-than Ignore commits older
than yyyy-MM-dd HH:mm:ss.
: any string
Default:
-ip, --ignore-pattern Ignore commits where
pattern matches message.
: any string
Default: ^Merge.*
-itp, --ignore-tag-pattern Ignore tags that
matches regular expression.
Can be used to ignore
release candidates and only
include actual releases.
: any string
Default: null
-jaf, --jira-additional-field Adds an additional
field for Jira. When
configured, we will return from
Jira the result of this
field, if it exists. [Supports Multiple occurrences]
: any string
Default: Empty list
-jba, --jira-basic-auth Optional token to
authenticate with Jira.
: any string
Default: \\b[a-zA-Z]([a-zA-Z]+)-([0-9]+)\\b
-jbt, --jira-bearer Optional token to
authenticate with Jira.
: any string
Default: \\b[a-zA-Z]([a-zA-Z]+)-([0-9]+)\\b
-je, --jira-enabled Enable parsing for
Jira issues.
Default: disabled
-jp, --jira-pattern Jira issue pattern.
: any string
Default: \\b[a-zA-Z]([a-zA-Z]+)-([0-9]+)\\b
-jpw, --jira-password Optional password to
authenticate with Jira.
: any string
Default: \\b[a-zA-Z]([a-zA-Z]+)-([0-9]+)\\b
-js, --jiraServer, --jira-server Jira server. When a
Jira server is given, the
title of the Jira issues can
be used in the changelog.
: any string
Default: null
-ju, --jira-username Optional username to
authenticate with Jira.
: any string
Default: \\b[a-zA-Z]([a-zA-Z]+)-([0-9]+)\\b
-mavp, --major-version-pattern Commit messages
matching this, optional,
regular expression will
trigger new major version.
: any string
Default: null
-mivp, --minor-version-pattern Commit messages
matching this, optional,
regular expression will
trigger new minor version.
: any string
Default: ^[Ff]eat.*
-ni, --no-issue-name Name of virtual issue
that contains commits that
has no issue associated.
: any string
Default: No issue
-of, --output-file Write output to file.
: any string
Default:
-pavp, --patch-version-pattern Commit messages
matching this, optional,
regular expression will
trigger new patch version.
: any string
Default: null
-pcv, --print-current-version Like --print-next-
version unless the current
commit is tagged with a
version, if so it will print
that version.
Default: disabled
-pf, --path-filters Paths on the
filesystem to filter on. [Supports Multiple occurrences]
: any string
Default: Empty list
-phv, --print-highest-version Print the highest
version, determined by tags in
repo, and exit.
Default: disabled
-phvt, --print-highest-version-tag Print the tag
corresponding to highest version,
and exit.
Default: disabled
-pnv, --print-next-version Print the next
version, determined by commits
since highest version, and
exit.
Default: disabled
-ptf, --prepend-to-file Add the changelog to
top of given file.
: any string
Default: null
-r, --repo Repository.
: any string
Default: .
-re, --redmine-enabled Enable parsing for
Redmine issues.
Default: disabled
-rhh, --register-handlebars-helper Handlebar helpers,
https://handlebarsjs.
com/guide/block-helpers.html, to
register and use in given
template.
: any string
Default:
-ri, --remove-issue-from-message Dont print any issues
in the messages of
commits.
Default: disabled
-rmp, --redmine-pattern Redmine issue pattern.
: any string
Default: #([0-9]+)
-rmpw, --redmine-password Optional password to
authenticate with Redmine.
: any string
Default:
-rms, --redmine-server Redmine server. When a
Redmine server is given, the
title of the Redmine issues
can be used in the
changelog.
: any string
Default: null
-rmt, --redmine-token Optional token/api-key
to authenticate with
Redmine.
: any string
Default:
-rmu, --redmine-username Optional username to
authenticate with Redmine.
: any string
Default:
-rt, --readable-tag-name Pattern to extract
readable part of tag.
: any string
Default: /([^/]+?)$
-sf, --settings-file Use settings from file.
: any string
Default: null
--show-debug-info Please run your
command with this parameter
and supply output when
reporting bugs.
Default: disabled
-std, --stdout Print builder to
.
Default: disabled
-t, --template Template to use. A
default template will be used
if not specified.
: any string
Default: changelog.mustache
-tbd, --template-base-dir Base dir of templates.
: any string
Default: null
-tec, --template-content String to use as
template.
: any string
Default:
-tps, --template-partial-suffix File ending for
partials.
: any string
Default: .hbs
-tre, --to-revision To revision.
: any string
Default: refs/heads/master
-trei, --to-revision-inclusiveness Include, or exclude,
specified revision.
: {INCLUSIVE | EXCLUSIVE | DEFAULT}
Default: DEFAULT
-tz, --time-zone TimeZone to use when
printing dates.
: any string
Default: UTC
-ui, --use-integrations Use integrations to
get more details on
commits.
Default: disabled
-ut, --untagged-name When listing commits
per tag, this will by the
name of a virtual tag that
contains commits not available
in any git tag.
: any string
Default: No tag
```
## Usage - template base dir
You can use [partials](http://jknack.github.io/handlebars.java/reuse.html) in your templates.
`/dir/changelog.hbs`
```hbs
{{#commits}}
{{> commit}}
{{/commits}}
```
`/dir/base/commit.partial`
```hbs
## {{authorName}} - {{commitTime}}
[{{hashFull}}](https://server/{{hash}})
{{{message}}}
```
This is configured like:
```sh
npx git-changelog-command-line -std \
--template-base-dir /dir/base \
--template /dir/changelog.hbs
```
If partials have a different ending, you can specify that with `--template-partial-suffix`.