JarCastingRead Me First.
- Convention Commit Changelog Generator (obviously for Git)
Getting Started.
Download an executable jar.
-
last version
-
Maven (all versions)
-
Download the executable jar from maven central (cocochagen-cli-1.0.4.jar). Can be renamed whatever.
<dependency> <groupId>org.icroco.cocochagen</groupId> <artifactId>cocochagen-cli</artifactId> <version>1.0.4</version> </dependency>
-
Maven: add to your build.
<plugin>
<groupId>org.icroco.cocochagen</groupId>
<artifactId>cocochagen-maven-plugin</artifactId>
<version>1.0.4</version>
<configuration>
<overrideExisting>true</overrideExisting>
<releaseCount>5</releaseCount>
<filterCommitTypes>*</filterCommitTypes>
</configuration>
</plugin>
- Use maven help to list all parameters:
mvn help:describe -DgroupId=org.icroco.cocochagen -DartifactId=cocochagen-maven-plugin -Ddetail
- to ask for a given version:
mvn help:describe -DgroupId=org.icroco.cocochagen -DartifactId=cocochagen-maven-plugin -Dversion=1.0.4 -Ddetail
- Have a look to this example for all configuration properties.
Gradle: add to your build.
TODO
CLI
Linux /Mac
./cococha -h
or
java -jar cococha.jar -h
Window
java -jar cococha.jar -h
Usage
Usage: cococha [-hrvV] [--[no-]commit-link] [--[no-]issue-link] [-c=<releaseCount>] [-F=<template>] [-g=<gitCommitUrl>] [-i=<issueUrl>]
[--issue-id-pattern=<issueIdRegex>] [-n=<releaseName>] [-o=<outputFile>] [-t=<commitType>[,<commitType>...]]...
[[--output-override] | [--output-append-start]]
Conventional Commit Changelog Generator
-c, --release-count=<releaseCount>
Last N releases to include into this changelog.
Default is: '1'
-F, --template-file=<template>
Template file path
Used to override the default changelog template. We use Mustache engine.
Option undefined means we'll pick up the embedded one
-g, --git-commit-url=<gitCommitUrl>
Remote url prefix to build commit link (github, gitlab ...)
Option undefined means we'll try to read from git remote (origin/master).
-h, --help Show this help message and exit.
-i, --issue-url=<issueUrl>
Tracker URL (Jira. github ...)
If a card/issue ID is found is will be tail at the end
Option undefined means we'll used github
--issue-id-pattern=<issueIdRegex>
a regexp to match an issue id
If a card ID is found it will be append at the end of tracker url.
Regex must contains 1 global group and 1 named capturing groups:
A global one used to identify an entirely issue id (ex: Closes: #1234)
Second one is named 'ID', used to extract the id that will be appended after issueUrl (ex: 1234)
Examples:
git: "(#(?<ID>\\d+))",
jira: "(?<ID>JIRA-\\d+)"
Strict conventional commit: "(Closes: )#(?<ID>\\d+)"
Advanced conventional commit: "(([Cc][Ll][Oo][Ss][Ee][Ss][ \t]*:[ \t]*)?#(?<ID>\\d+))"
Mix git and coco style: "(([Cc][Ll][Oo][Ss][Ee][Ss][ \t]*:[ \t]*)?#?(?<ID>\\d+))"
Regex must be java compatible: https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html
Default is git style optionally with prefix 'Closes: ' '(([Cc][Ll][Oo][Ss][Ee][Ss][ ]*:[ ]*)?#(?<ID>\d+))'
-n, --release-name=<releaseName>
Provide the name of this release
By default is automatically computed from last tag if you follow semantic versioning
Option undefined means automatic release name'
--[no-]commit-link Add git commit URL for change log
Default is: 'true'
--[no-]issue-link Append an issue link if an issue ID is found into short or full log message
Default is: 'true'
-o, --output=<outputFile>
output changelog filename
--output-append-start
Append the output on top of an existing file
Default is: 'false'
--output-override Override if output already exists
Default is: 'false'
-r, --remove-duplicate Remove duplicate commits based on description.
Commit IDs will be merged on same line.
Default is: 'true'.
-t, --commit-type=<commitType>[,<commitType>...]
Filter only those commits type
Default is: 'fix,feat,perf'
-v, --verbose print more information on console
Default is: 'false'
-V, --version Print version information and exit.
Features
- Simple Command line interface.
- Option to generate release note for last N releases.
- Option to filter convention commit.
- Option to provide your own custom template (mustache based. More info at samskivert ).
- Option to add your own Issuer URL (default is url based on git remote).
- Option to provide your own regex to match Issue ID.
- Option to add/hide: "commit ID", "issues ID", "Contributor".
- Maven Plugin.
- Merge similar commits description and support many CommitID links per line.
- Generate changelog at beginning of an existing one.
- Do not override existing changelog. add option to force overriding.
- Publish to maven central.
- Option to add/hide: "Contributor".
- Option to customize Commit Type label (Features, ...).
- Export report into json format.
- Add Travis.
- Gradle Plugin.
- Native CLI with GraalVM.
Trouble Shooting
- Runtime working dir: be careful, right now you won't have same results if your run with java -jar ... ot ./cocochgen.jar
- with java -jar working dir is the current dir where you launch the command
- running like an executable ./cococha.jar, the working dir will be where the jar is located.
example: './foo/bar/cocochagen.jar' is executing into the directory './foo/bar'
- If your changelog looks not as expected (missing items, ...), try to run with these options:
./cococha.jar -t '*' -c 10 >
- Finally, use -v to get more details on stdout.