• Read Me First.
• Getting Started.
  • Download an executable jar.
  • Maven: add to your build.
  • Gradle: add to your build.
  • CLI
  • Usage
• Features
• Trouble Shooting

Read Me First.

• Convention Commit Changelog Generator (obviously for Git)

Getting Started.

• look at output example

Download an executable jar.

• last version

  • cococha

• 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.1.3</version>
    </dependency>

Maven: add to your build.

      <plugin>
          <groupId>org.icroco.cocochagen</groupId>
    <artifactId>cocochagen-maven-plugin</artifactId>
    <version>1.1.3</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 will 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: "(((Closes)\s*:)?\s*#(?<ID>\d+)\s*)"
                               Mix git and coco style: "(((Closes)\s*:)?\s*#?(?<ID>\d+)\s*)"
                           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: ' '(((Closes)\s*:)?\s*#(?<ID>\d+)\s*)'

  -n, --release-name=<releaseName>
                           Provide the name of a release from which we will start to analyze changes.
                           By default is automatically computed from last valid 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 group changes by major/minor.
• Option to add/hide: "Contributor".
• Option to customize Commit Type label (Features, ...).
• Export report into json format.
• Add github actions.
• Gradle Plugin.
• Native CLI with GraalVM.
• Maven plugin add skip option.

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.

Table of contents generated with markdown-toc