Quilt Licenser Gradle Plugin

A license header manager for Gradle.

Its goal is to ensure that the source files contains a predefined license header determined by some rules, and optionally generate them automatically with a Gradle task.

Depreciation Notice

Since October 2023, the Quilt Licenser Gradle plugin is deprecated.
This plugin suffers from critical design flaws which leads to some OS-specific bugs and to a low ability to expand the plugin further in the future.

To remedy those issues a rewrite was needed and the original author of this plugin has done such rewrite under a separate organization. The replacement plugin is the Yumi Gradle Licenser Plugin.

Migration

For those who wish to continue to use this kind of license header management plugin, the Yumi Gradle Licenser Plugin can be used as the replacement.

That replacement plugin fixes some issues with this one:

• Windows-specific license header detection issues are fixed.
• Date-detection issues are fixed.
• Kotlin is properly supported.

For most cases the migration is a matter of a few line changes.

In buildscripts the plugin identifier needs to be changed:

-	id 'org.quiltmc.gradle.licenser' version '2.+'
+	id 'dev.yumi.gradle.licenser' version '1.1.+'

The license block in buildscripts does not require any change.

The format for license header files change significantly, the full documentation can be found here.

Changes include:

• Replace the ${YEAR} variable with ${CREATION_YEAR}.
• Addition of the ${FILE_NAME} variable.
• Metadata statements prefixed with ;; are replaced with pre-processor statements prefixed with #:
  • the year_selection statement is the same;
  • the year_display statement no longer exists, but similar behavior can be achieved through the use of type statements:

    - ;;year_display: list
    + #type YEAR YEAR_LIST

    Please note that the type statement defines a new variable.
  • the match_from statement does not currently have an equivalent, but should not be an issue in most cases and only influenced initial runs of the applyLicenses task;
  • a new kind of statement is available: optional, this allows to add optional parts to license headers.

Usage

For a project you need to apply the plugin to your project:

plugins {
	id 'org.quiltmc.gradle.licenser' version '2.+'
}

Quilt Gradle Licenser is available on the Gradle Plugin Portal or the Quilt Maven.

Tasks

Name	Description
applyLicenses	Updates the license headers in the selected source files.
checkLicenses	Verifies the license headers for the selected source files.

Configuration

The plugin can be configured using the license extension on the project.

license {
	// Add a license header rule, at least one must be present.
	rule file("codeformat/HEADER")

	// Exclude/include certain file types: (Default: Excludes files without standard comment format and binary files)
	include '**/*.java' // Apply license header ONLY to Java files
	// OR
	exclude '**/*.properties' // Apply license header NOT to properties files
}

More configuration options may come in the future.

License header rule

The way this plugin works is a license header have multiple header rules. This allows to select and apply specific headers for some files.

An example file can be found in this repository: codeformat/HEADER.

Format

A license header rule contains the license header text, and metadata prefixed with ;;. License header text can contain variables formatted as the following ${VARIABLE}.

This would give a file:

License text ${YEAR}

;;metadata: hello
;;more metadata: hi!
;;key: value

Variables

Currently, only the ${YEAR} variable is available.

Metadata

• match_from
  No default value.
  Regular expressions the file can match against to select this header rule. Each declaration of match_from is added to the global regex with an OR relation. The regular expression only match against the beginning of the file.
• year_display
  Default value: creation_only
  Describes how the year variable should look like.
  Available values are:
  • creation_only for only the year of creation,
  • list for a list of years,
  • lenient_range for a range between the absolute minimum year and last modification year
• year_selection
  Default value: project
  Describes how the modification year should be fetched, Git commits are used to determine the last modification year.
  Available values are:
  • project for which the project is used as reference,
  • file for which each file can have its own last modification year