scm-metadata:metadata
Full name:
zone.gryphon.maven.plugins:scm-metadata-maven-plugin:1.8:metadata
Description:
Generates metadata about the project's SCM, and injects it into the
build context as Maven
Properties for re-use by other plugins.
For example, the elements of the path /alpha/bravo can be accessed via the following indices:
See the remotePathNotation configuration for details
about the format of the remote.path.segment
properties.
Metadata Calculated:
- revision - the current project revision (e.g. git commit SHA)
- revision.short - a potentially truncated version of the revision property
- branch - the current SCM branch (e.g. master)
- dirty - true if there are any uncommitted local changes in files which are not excluded from SCM, false otherwise (equivalent to checking git status --porcelain)
Remote Path Segment Properties
Additionally, properties prefixed with remote.path.segment will be injected for each path segment in the scm.developerConnection configuration (or scm.connection if scm.developerConnection is not set). Each segment can be accessed by its positive 0 based index in the path, as well as a negative index based on its position relative to the end of the path (i.e. the last path segment can be accessed at index -1, the second to last at -2, etc...).For example, the elements of the path /alpha/bravo can be accessed via the following indices:
| Segment | Index | Negative Index |
|---|---|---|
| alpha | 0 | -2 |
| bravo | 1 | -1 |
Property Prefix
Note that the name of each property is prefixed with the value of the prefix configuration option, meaning the properties set when using the default configuration are:- scm.metadata.revision
- scm.metadata.revision.short
- scm.metadata.branch
- scm.metadata.dirty
- scm.metadata.remote.path.segment[*]
Attributes:
- Requires a Maven project to be executed.
- Since version: 1.0.
- Binds by default to the lifecycle phase: initialize.
Optional Parameters
| Name | Type | Since | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| <directory> | File | 1.0 | Directory to start search for SCM configuration in. Parent
directories will be recursively checked until the SCM configuration
is discovered, or the root folder is reached. Default value is: ${project.basedir}. |
|||||||||||||||
| <prefix> | String | 1.0 | Prefix to apply to all property names. Default value is: scm.metadata.. |
|||||||||||||||
| <remotePathNotation> | String | 1.0 | A comma separated list of values indicating the format to use for
the remote SCM path properties. Valid values which can be included in the list:
Concrete examples of the properties generated for an SCM with a remote path of /alpha/bravo:
Default value is: ARRAY. |
|||||||||||||||
| <rename> | Map | 1.0 | A map of String to String which allows
for properties to be renamed before they're set. Each key is the
name of a property (after the prefix is applied), and
the value is what the property should be renamed to. For example, if using the default prefix "scm.metadata.", a map entry "scm.metadata.revision" -> "foo" would result in the plugin setting the property "foo" instead of "scm.metadata.revision" (the value of the property is unaffected). Since the rename happens after the prefix is applied, any custom prefix should be included in the map key. For example, if using the custom prefix "bar.", the map entry "bar.revision" -> "foo" would result in the plugin setting the property "foo" instead of "bar.revision" (again, the value of the property is unaffected). When configuring the value in the POM, the more compact map syntax should be used:
<configuration>
<rename>
<scm.metadata.revision>foo</scm.metadata.revision>
</rename>
</configuration>
|
|||||||||||||||
| <shortRevisionLength> | int | 1.0 | The maximum length of revision.short. Default value is: 8. |
|||||||||||||||
| <skip> | boolean | 1.0 | If true, plugin execution will be skipped Default value is: false. |
|||||||||||||||
| <type> | String | 1.0 | SCM implementation to use when calculating metadata. Valid options:
Default value is: auto. |
Parameter Details
<directory>
Directory to start search for SCM configuration in. Parent
directories will be recursively checked until the SCM configuration
is discovered, or the root folder is reached.
- Type: java.io.File
- Since: 1.0
- Required: No
- Default: ${project.basedir}
<prefix>
Prefix to apply to all property names.
- Type: java.lang.String
- Since: 1.0
- Required: No
- Default: scm.metadata.
<remotePathNotation>
A comma separated list of values indicating the format to use for
the remote SCM path properties.
Valid values which can be included in the list:
Concrete examples of the properties generated for an SCM with a remote path of /alpha/bravo:
Valid values which can be included in the list:
- NONE
- Don't inject any properties for the remote SCM path. Note that if there are other values in the list, they will still be injected.
- ARRAY
- Properties will be injected using the syntax "remote.path.segment[*]". This syntax is easily human readable, but can cause potential issues due to the fact that neither "[" nor "]" can be included in XML tag names, meaning for example that the properties cannot be renamed using the rename configuration option.
- PROPERTY
- Properties will be injected using the syntax "remote.path.segment.*". This syntax is less readable, however the generated properties are valid XML tag names, meaning they're more compatible with the Maven POM (for example, they can be renamed using the rename configuration option).
Concrete examples of the properties generated for an SCM with a remote path of /alpha/bravo:
| PROPERTY notation | ARRAY notation | Property Value |
|---|---|---|
| remote.path.segment.0 | remote.path.segment[0] | alpha |
| remote.path.segment.1 | remote.path.segment[1] | bravo |
| remote.path.segment.-1 | remote.path.segment[-1] | bravo |
| remote.path.segment.-2 | remote.path.segment[-2] | alpha |
- Type: java.lang.String
- Since: 1.0
- Required: No
- Default: ARRAY
<rename>
A map of String to String which allows
for properties to be renamed before they're set. Each key is the
name of a property (after the prefix is applied), and
the value is what the property should be renamed to.
For example, if using the default prefix "scm.metadata.", a map entry "scm.metadata.revision" -> "foo" would result in the plugin setting the property "foo" instead of "scm.metadata.revision" (the value of the property is unaffected).
Since the rename happens after the prefix is applied, any custom prefix should be included in the map key. For example, if using the custom prefix "bar.", the map entry "bar.revision" -> "foo" would result in the plugin setting the property "foo" instead of "bar.revision" (again, the value of the property is unaffected).
When configuring the value in the POM, the more compact map syntax should be used:
For example, if using the default prefix "scm.metadata.", a map entry "scm.metadata.revision" -> "foo" would result in the plugin setting the property "foo" instead of "scm.metadata.revision" (the value of the property is unaffected).
Since the rename happens after the prefix is applied, any custom prefix should be included in the map key. For example, if using the custom prefix "bar.", the map entry "bar.revision" -> "foo" would result in the plugin setting the property "foo" instead of "bar.revision" (again, the value of the property is unaffected).
When configuring the value in the POM, the more compact map syntax should be used:
<configuration>
<rename>
<scm.metadata.revision>foo</scm.metadata.revision>
</rename>
</configuration>
- Type: java.util.Map
- Since: 1.0
- Required: No
<shortRevisionLength>
The maximum length of revision.short.
- Type: int
- Since: 1.0
- Required: No
- Default: 8
<skip>
If true, plugin execution will be skipped
- Type: boolean
- Since: 1.0
- Required: No
- Default: false
<type>
SCM implementation to use when calculating metadata. Valid options:
- none - don't inject SCM metadata (equivalent to setting skip to true
- auto - attempt to automatically determine the SCM implementation based on the scm.connection value set in the POM
- git - use git to look up SCM information
- Type: java.lang.String
- Since: 1.0
- Required: No
- Default: auto