diff --git a/versions-enforcer/src/main/java/org/apache/maven/plugins/enforcer/MaxDependencyUpdates.java b/versions-enforcer/src/main/java/org/apache/maven/plugins/enforcer/MaxDependencyUpdates.java
index 8b0fa4b00..921f2421d 100644
--- a/versions-enforcer/src/main/java/org/apache/maven/plugins/enforcer/MaxDependencyUpdates.java
+++ b/versions-enforcer/src/main/java/org/apache/maven/plugins/enforcer/MaxDependencyUpdates.java
@@ -137,20 +137,24 @@ public class MaxDependencyUpdates implements EnforcerRule2 {
protected boolean ignoreSubIncrementalUpdates = false;
/**
- * List of dependency inclusion patterns.
- * Only dependencies matching all the patterns will be considered.
+ * List of input dependency inclusion patterns.
+ * Note: even if a version is specified, it will refer to the input dependency version.
+ * To filter output versions, please use {@link #ruleSet}.
+ * >Only dependencies matching all the patterns will be considered.
* The wildcard "*" can be used as the only, first, last or both characters in each token.
- * The version token does support version ranges.
+ * The version token does support version ranges.
dependencyIncludes = singletonList(WILDCARD);
/**
- * List of dependency exclusion patterns.
- * Only dependencies matching none of the patterns will be considered.
+ * List of input dependency exclusion patterns.
+ * Note: even if a version is specified, it will refer to the input dependency version.
+ * To filter output versions, please use {@link #ruleSet}.
+ * Only dependencies matching none of the patterns will be considered.
* The wildcard "*" can be used as the only, first, last or both characters in each token.
- * The version token does support version ranges.
+ * The version token does support version ranges.
*
* @since 2.14.0
*/
diff --git a/versions-maven-plugin/src/main/java/org/codehaus/mojo/versions/DisplayDependencyUpdatesMojo.java b/versions-maven-plugin/src/main/java/org/codehaus/mojo/versions/DisplayDependencyUpdatesMojo.java
index 8b86b19c0..bb0600c73 100644
--- a/versions-maven-plugin/src/main/java/org/codehaus/mojo/versions/DisplayDependencyUpdatesMojo.java
+++ b/versions-maven-plugin/src/main/java/org/codehaus/mojo/versions/DisplayDependencyUpdatesMojo.java
@@ -152,7 +152,9 @@ public class DisplayDependencyUpdatesMojo extends AbstractVersionsDisplayMojo {
private boolean processDependencies;
/**
- * Only take these artifacts into consideration.
+ * Only take the specified input dependencies into account.
+ * Note: even if a version is specified, it will refer to the input dependency version.
+ * To filter output versions, please use {@link #ruleSet} or {@link #ignoredVersions}.
*
* Comma-separated list of extended GAV patterns.
*
@@ -174,7 +176,9 @@ public class DisplayDependencyUpdatesMojo extends AbstractVersionsDisplayMojo {
private List dependencyIncludes;
/**
- * Exclude these artifacts from consideration.
+ * Do not take the specified input dependencies into account.
+ * Note: even if a version is specified, it will refer to the input dependency version.
+ * To filter output versions, please use {@link #ruleSet} or {@link #ignoredVersions}.
*
* Comma-separated list of extended GAV patterns.
*
@@ -182,7 +186,7 @@ public class DisplayDependencyUpdatesMojo extends AbstractVersionsDisplayMojo {
* Extended GAV: groupId:artifactId:version:type:classifier:scope
*
*
- * The wildcard "*" can be used as the only, first, last or both characters in each token.
+ * The wildcaNote:rd "*" can be used as the only, first, last or both characters in each token.
* The version token does support version ranges.
*
*
diff --git a/versions-maven-plugin/src/site/markdown/examples/display-dependency-updates.md b/versions-maven-plugin/src/site/markdown/examples/display-dependency-updates.md
index a8af766c2..21375e9f2 100644
--- a/versions-maven-plugin/src/site/markdown/examples/display-dependency-updates.md
+++ b/versions-maven-plugin/src/site/markdown/examples/display-dependency-updates.md
@@ -55,3 +55,68 @@ Which produces the following output:
[INFO] Final Memory: 10M/167M
[INFO] ------------------------------------------------------------------------
```
+
+# Ignore a specific version suffix in version updates
+
+Let's suppose you wanted `org.apache.maven.doxia:doxia-core:` not to be updated to `2.0.0-M6` or `org.apache.maven:maven-core` to `4.0.0-alpha-5' or anything with a `-M` or `-alpha' in it. Upon first sight of the `dependencyExcludes` option, one might consider to use it to filter out anything with `2.*-M.*` or `*-alpha.*`.
+
+Well, that would be wrong. `dependencyIncludes` and `dependencyExcludes` work only on *input* dependencies, that is, dependency versions that are already being used by your project. This means that it is likely that you will still see the dreaded `2.0.0-M6`-like version in the updates.
+
+You can either use `ruleSet` or `ignoredVersions`. The former allows for a greater control where you can specify ignored version patterns per dependency whereas the latter is intended to be used from command line ans only offers simple version filters.
+
+So, let's say we want to display dependency updates of this very plugin and while doing so, ignore all updates with an `-M` or `-alpha` at the end of the version string, simply use:
+
+```shell
+mvn org.codehaus.mojo:versions-maven-plugin:display-dependency-updates "-Dmaven.version.ignore=.*-M.*,.*-alpha.*"
+```
+
+or:
+
+```xml
+
+ ...
+ .*-M.*,.*-alpha.*
+ ...
+
+```
+
+in your project config. That will result in the following output. Instead of:
+
+```shell
+[INFO] --- versions:2.15.0:display-dependency-updates (default-cli) @ versions-maven-plugin ---
+[INFO] The following dependencies in Dependency Management have newer versions:
+[INFO] dom4j:dom4j ................................. 1.6.1 -> 20040902.021138
+[INFO] org.apache.maven:maven-artifact ............... 3.2.5 -> 4.0.0-alpha-5
+[INFO] org.apache.maven:maven-compat ................. 3.2.5 -> 4.0.0-alpha-5
+[INFO] org.apache.maven:maven-core ................... 3.2.5 -> 4.0.0-alpha-5
+[INFO] org.apache.maven:maven-model .................. 3.2.5 -> 4.0.0-alpha-5
+[INFO] org.apache.maven:maven-plugin-api ............. 3.2.5 -> 4.0.0-alpha-5
+[INFO] org.apache.maven:maven-settings ............... 3.2.5 -> 4.0.0-alpha-5
+[INFO] org.apache.maven.enforcer:enforcer-api ................ 3.2.1 -> 3.3.0
+[INFO] org.apache.maven.plugin-testing:maven-plugin-testing-harness ...
+[INFO] 3.3.0 -> 4.0.0-alpha-1
+[INFO] org.apache.maven.plugin-tools:maven-plugin-annotations ...
+[INFO] 3.8.1 -> 3.8.2
+[INFO] org.mockito:mockito-inline ........................... 4.11.0 -> 5.2.0
+[INFO] org.slf4j:slf4j-simple ............................... 1.7.36 -> 2.0.7
+```
+
+you will only see:
+
+```shell
+[INFO] --- versions:2.15.0:display-dependency-updates (default-cli) @ versions-maven-plugin ---
+[INFO] The following dependencies in Dependency Management have newer versions:
+[INFO] dom4j:dom4j ................................. 1.6.1 -> 20040902.021138
+[INFO] org.apache.maven:maven-artifact ....................... 3.2.5 -> 3.9.2
+[INFO] org.apache.maven:maven-compat ......................... 3.2.5 -> 3.9.2
+[INFO] org.apache.maven:maven-core ........................... 3.2.5 -> 3.9.2
+[INFO] org.apache.maven:maven-model .......................... 3.2.5 -> 3.9.2
+[INFO] org.apache.maven:maven-plugin-api ..................... 3.2.5 -> 3.9.2
+[INFO] org.apache.maven:maven-settings ....................... 3.2.5 -> 3.9.2
+[INFO] org.apache.maven.enforcer:enforcer-api ................ 3.2.1 -> 3.3.0
+[INFO] org.apache.maven.plugin-tools:maven-plugin-annotations ...
+[INFO] 3.8.1 -> 3.8.2
+[INFO] org.mockito:mockito-inline ........................... 4.11.0 -> 5.2.0
+[INFO] org.slf4j:slf4j-simple ............................... 1.7.36 -> 2.0.7
+```
+
diff --git a/versions-maven-plugin/src/site/markdown/faq.md b/versions-maven-plugin/src/site/markdown/faq.md
index 7367e3813..f3c920ba5 100644
--- a/versions-maven-plugin/src/site/markdown/faq.md
+++ b/versions-maven-plugin/src/site/markdown/faq.md
@@ -64,3 +64,33 @@ manager.
In most cases, using a repository manager will solve these issues as the repository managers usually
rebuild the metadata files based on the artifacts that are present.
+
+### Why is a dependency version not excluded by dependencyExcludes
+
+`dependencyIncludes` and `dependencyExcludes` work on *input* dependencies and not on output dependencies. That will mean that even if you include a version string you don't want the given dependency to be updated to, that version might still get chosen as the target dependency version.
+
+The reason for that is that the option filters *input* dependency versions.
+
+Let's suppose you wanted `org.apache.maven.doxia:doxia-core:` not to be updated to `2.0.0-M6` or `org.apache.maven:maven-core` to `4.0.0-alpha-5' or anything with a `-M` or `-alpha' in it. Upon first sight of the `dependencyExcludes` option, one might consider to use it to filter out anything with `2.*-M.*` or `*-alpha.*`.
+
+Well, that would be wrong. `dependencyIncludes` and `dependencyExcludes` work only on *input* dependencies, that is, dependency versions that are already being used by your project. This means that it is likely that you will still see the dreaded `2.0.0-M6`-like version in the updates.
+
+Instead, what you should be looking at is `ruleSet` or `ignoredVersions`. The former allows for a greater control where you can specify ignored version patterns per dependency whereas the latter is intended to be used from command line ans only offers simple version filters.
+
+So, to ignore all updates with an `-M.*` at the end of the version string, simply use:
+
+`-Dmaven.version.ignore=.*-M.*`
+
+or:
+
+```xml
+
+ ...
+ .*-M.*
+ ...
+
+```
+
+in your project config.
+
+See [Issue #258](https://github.com/mojohaus/versions/issues/258) and [the documentation for ignoredVersions](https://www.mojohaus.org/versions/versions-maven-plugin/display-dependency-updates-mojo.html#ignoredVersions)