The Maven 2 plugin registry (~/.m2/plugin-registry.xml) is a mechanism to help the user exert some control over their build environment. Rather than simply fetching the latest version of every plugin used in a given build, this registry allows the user to peg a plugin to a particular version, and only update to newer versions under certain restricted circumstances. There are various ways to configure or bypass this feature, and the feature itself can be managed on either a per-user or global level.
The plugin registry is currently in a semi-dormant state within Maven 2. This is because it has been shown to have some subtle behavior that is not quite intuitive. While we believe it's important to allow the user to pin down which version of a particular plugin is used across all builds, it's not clear that this type of information should be machine-specific (i.e. tied to something outside the project directory).
Users should be cautious when attempting to use the plugin-registry.xml. Redesign of this feature in upcoming 2.1 and/or 2.2 is likely.
For now, Maven should keep using the same version of a plugin - assuming a different version is not specified in the POM - until the user chooses to run with the -U option explicitly enabled.
The plugin registry file (per-user: ~/.m2/plugin-registry.xml, global: $M2_HOME/conf/plugin-registry.xml) contains a set of plugin-version registrations, along with some configuration parameters for the registry itself.
Currently, the plugin registry supports configuration options for the following:
Combined with the lastChecked plugin attribute, this determines whether a particular plugin will be checked for updates during a given build. Valid settings are: never, always, and interval:TTT (TTT is a short specification for a time interval, which follows the pattern /([0-9]+[wdhm])+/). Intervals are specified down to the minute resolution. An example of an interval specification might be:
interval:4w2h30m (check every 4 weeks, 2 hours, and 30 minutes)
LATEST metadata is always published when a plugin is installed or deployed to a repository, and so will always reference the newest copy of the plugin, regardless of whether this is a snapshot version or not.
NOTE: Registered plugins will currently only ever be updated with the results of RELEASE metadata resolution.
Obviously, the plugin registry also contains information about resolved plugin versions. The following information is tracked for each registered plugin:
There are many ways you can override the default plugin registry settings. Often, this will be desirable for a single, one-off build of a project that deviates from your normal environment configuration. However, before discussing these options, it's important to understand how the plugin registry resolves versions for unregistered plugins, along with plugins in need of an update check.
The plugin registry uses a relatively straightforward algorithm for resolving plugin versions. However, considerations for when to check, when to prompt the user, and when to persist resolved plugin versions complicate this implementation considerably. In general, plugin versions are resolved using a four-step process:
If the plugin is due for an update check, the plugin-artifact's RELEASE metadata is resolved. Resolution of this metadata may trigger a prompt to notify the user of the new version, and/or persistence of the new version in the registry. If the update is performed, the lastChecked attribute is updated to reflect this.
If this metadata is resolved successfully, that version is used. This may trigger a prompt to ask the user whether to register the plugin, and a successive persistence step for the new plugin version.
I've alluded to prompting the user and persisting the plugin version into the registry. Now, let's examine the circumstances under which these steps actually take place.
There are two cases where the user may be prompted to change the plugin registry; when the plugin is not registered, and when the plugin is registered, but an updated version is discovered. By default, the user is prompted to save the resolved version for each plugin, with the option of specifying that a decision should be remembered and applied to all (either yes to all, or no to all) plugins registry updates. However, it is also possible to bypass this behavior in the following ways:
These force all registered plugins to be updated. The user will still be prompted to approve plugin versions, unless one of the above switches is also provided.
The following summary of command line options is provided for quick reference:
Synonyms: --update-plugins -up -cpu