loggit-maven-plugin

Why another changelog plugin?

None of the other changelog plugins have the right combination of features that I need:

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

Features

• 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>${project.build.directory}/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:

1. The git log is read and the XML is built (relevant configs: <repo>, <branch>)
2. The XML is pre-processed for common use cases (relevant configs: <maxEntries>, <startTag>, <endTag>, <includeRegex>, <includeRegexFlags>, <excludeRegex>, <excludeRegexFlags>, <startCommit>)
3. 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.

Feedback

Please direct any questions, feature requests or bugs to the issue tracker.

How to contribute?

See CONTRIBUTING.

License

loggit-maven-plugin is licensed under the Apache License, Version 2.0. A copy of the license has been included in LICENSE.

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