loggit-maven-plugin

About

loggit-maven-plugin is a maven plugin that can generate a changelog from the git log of a project and output to a file in any text format. The output format is controlled by XSLT 3.0 that can be provided by the user in an external file.

Note: the API is currently unstable as we approach our first milestone.

For bugs or enhancements, please use our issue tracker.

Why another changelog plugin?

None of the other changelog plugins has the combinations of features that I need:

Markdown format
Smarter selection of commit ranges (including tags)
Project activity

Transform the git log into any format using XSLT 3.0.
Specify start and end tags to create a changelog that shows a slice of your git log
Filter commits based on regular expressions
Specify all configurations via the command line or settings.xml

Non goals

Performance: this plugin does not aim to be the fastest nor use the least resources nor have the smallest footprint

Usage

Include the plugin in your pom. Its only goal is changelog and is set to execute in the prepare-package phase by default. All configurations have default values and are optional (values shown below are default). They are also available from the command line if you prefix them with loggit. (eg. mvn loggit:changelog -Dloggit.maxEntries=50).

<build>
  <plugins>
    ...
    <plugin>
      <groupId>org.llorllale</groupId>
      <artifactId>loggit-maven-plugin</artifactId>
      <version>${pluginVersion}</version>
      <configuration>
        <repo>${basedir}</repo>
        <outputFile>/home/travis/build/llorllale/loggit-maven-plugin/target/gitlog.xml</outputFile>
        <format>default</format>
        <customFormatFile></customFormatFile> <!-- empty -->
        <branch>master</branch>
        <maxEntries>2147483647</maxEntries> <!-- Integer.MAX_VALUE -->
        <startTag></startTag> <!-- empty -->
        <endTag></endTag> <!-- empty -->
        <includeRegex>.*</includeRegex>
        <includeRegexFlags></includeRegexFlags> <!-- empty -->
        <excludeRegex>.*</excludeRegex> <!-- default value explained below -->
        <excludeRegexFlags></excludeRegexFlags> <!-- empty -->
        <startCommit></startCommit>   <!-- empty -->
      </configuration>
    </plugin>
    ...
  <plugins>
</build>

Configuration

<repo>: path to the root directory of the git repo
<outputFile>: path to the file where the changelog should be written to
<format>: desired output format (see relevant example below). Possible values are default, markdown, and custom
<customFormatFile>: path to the custom format file (used only when <format> is custom (see relevant example below))
<branch>: the git branch from which to read the changelog
<maxEntries>: the maximum number of entries to read into the changelog
<startTag>: if specified, will truncate the log starting at the commit with the given tag
<endTag>: if specified, will exclude all commits that appear before a commit with the given tag
<includeRegex>: includes only commits with messages that match the given regular expression
<includeRegexFlags>: flags for <includeRegex>. Supported values can be found here
<excludeRegex>: excludes commits with messages that match the given regular expression. Note: the default value is set to .* because we assume that this will never be used as a value in production use. If we need to exclude all commits, we just set <maxEntries> to 0. We use .* to determine whether or not a value was provided for <excludeRegex>.
<excludeRegexFlags>: flags for <excludeRegex>. Supported values can be found here
<startCommit>: if specified, will include commits until the given ID is found (inclusive)

How it works

Loggit is powered by jGit, XSLT 3.0, jcabi-xml, and saxon-HE). After reading the gitlog and creating an XML in compliance with this schema, everything else is done using XSLT. XSLT is an extremely powerful tool that lets you - the user - transform the git log into any textual format imaginable.

In three stages:

The git log is read and the XML is built (relevant configs: <repo>, <branch>)
The XML is pre-processed for common use cases (relevant configs: <maxEntries>, <startTag>, <endTag>, <includeRegex>, <includeRegexFlags>, <excludeRegex>, <excludeRegexFlags>, <startCommit>)
The XML is post-processed using XSLT and the result is written to file (relevant configs: <format>, <customFormatFile>, <outputFile>)

Examples

Default markdown format

The markdown transformation bundled with loggit is very primitive and basic. It is not really intended for much use outside of demonstration purposes. Assuming you want to use it:

<plugin>
  <groupId>org.llorllale</groupId>
  <artifactId>loggit-maven-plugin</artifactId>
  <version>${pluginVersion}</version>
  <configuration>
    <format>markdown</format>
  </configuration>
</plugin>

Then the output will look similar to this:

# CHANGELOG

* id: 9d45cab (by John Doe)
      Short message
* id: 177357d (by Smith Jones)
      Fixed typo.
* id: 3e64aa1 (by Alicia Banks)
      Initial commit.

Using a custom format

Use the following plugin configuration:

<plugin>
  <groupId>org.llorllale</groupId>
  <artifactId>loggit-maven-plugin</artifactId>
  <version>${pluginVersion}</version>
  <configuration>
    <format>custom</format>
    <customFormatFile>path/to/custom/xslt/file.xsl</customFormatFile>
  </configuration>
</plugin>

path/to/custom/xslt/file.xsl is the file where you’ll have your custom XSLT 3.0 transformation that can output to any format you want.

Icon made by Freepik from www.flaticon.com is licensed by CC BY 3.0