https://github.com/llorllale/loggit-maven-plugin
Generates changelog and release notes for projects using git
https://github.com/llorllale/loggit-maven-plugin
changelog changelog-generator git maven maven-plugin release-automation release-notes
Last synced: 3 months ago
JSON representation
Generates changelog and release notes for projects using git
- Host: GitHub
- URL: https://github.com/llorllale/loggit-maven-plugin
- Owner: llorllale
- License: apache-2.0
- Created: 2018-01-25T15:22:16.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2018-09-11T20:51:02.000Z (about 7 years ago)
- Last Synced: 2025-03-22T22:11:47.083Z (8 months ago)
- Topics: changelog, changelog-generator, git, maven, maven-plugin, release-automation, release-notes
- Language: Java
- Homepage: https://llorllale.github.io/loggit-maven-plugin/
- Size: 289 KB
- Stars: 10
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# loggit-maven-plugin 
[](http://www.elegantobjects.org)
[](https://codecov.io/gh/llorllale/loggit-maven-plugin)
[](https://travis-ci.org/llorllale/loggit-maven-plugin)
[](https://maven-badges.herokuapp.com/maven-central/org.llorllale/loggit-maven-plugin)
[](http://www.0pdd.com/p?name=llorllale/loggit-maven-plugin)
[](https://llorllale.github.io/loggit-maven-plugin/license.html)
## 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](https://www.w3.org/TR/xslt-30/).
* 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`).
```xml
...
org.llorllale
loggit-maven-plugin
${pluginVersion}
${basedir}
${project.build.directory}/gitlog.xml
default
master
2147483647
.*
.*
...
```
### Configuration
* ``: path to the root directory of the git repo
* ``: path to the file where the changelog should be written to
* ``: desired output format (see relevant example below). Possible values are `default`, `markdown`, and `custom`
* ``: path to the custom format file (used only when `` is `custom` (see relevant example below))
* ``: the git branch from which to read the changelog
* ``: the maximum number of entries to read into the changelog
* ``: if specified, will truncate the log starting at the commit with the given tag
* ``: if specified, will exclude all commits that appear *before* a commit with the given tag
* ``: includes only commits with messages that match the given regular expression
* ``: flags for ``. Supported values can be found [here](https://www.w3.org/TR/xpath-functions-30/#flags)
* ``: 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 `` to `0`. We use `.*` to determine whether or not a value was provided for ``.
* ``: flags for ``. Supported values can be found [here](https://www.w3.org/TR/xpath-functions-30/#flags)
* ``: if specified, will include commits until the given ID is found (inclusive)
## How it works
*Loggit* is powered by [jGit](https://www.eclipse.org/jgit/), [XSLT 3.0](https://www.w3.org/TR/xslt-30/), [jcabi-xml](https://github.com/jcabi/jcabi-xml), and [saxon-HE](http://saxon.sourceforge.net/)). After reading the gitlog and creating an XML in compliance with [this schema](src/main/resources/xsd/schema.xsd), 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: ``, ``)
2. The XML is pre-processed for common use cases (relevant configs: ``, ``, ``, ``, ``, ``, ``, ``)
3. The XML is post-processed using XSLT and the result is written to file (relevant configs: ``, ``, ``)
## Examples
### Default markdown format
The markdown transformation [bundled](src/main/resources/xsl/post/markdown.xsl) 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:
```xml
org.llorllale
loggit-maven-plugin
${pluginVersion}
markdown
```
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:
```xml
org.llorllale
loggit-maven-plugin
${pluginVersion}
custom
path/to/custom/xslt/file.xsl
```
`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](https://github.com/llorllale/loggit-maven-plugin/issues/).
## How to contribute?
See [CONTRIBUTING](./CONTRIBUTING.md).
## License
`loggit-maven-plugin` is licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0). A copy of the license has been included in [LICENSE](./LICENSE).