Skip to content

Commit 0dba4e5

Browse files
andrzejj0andrzejj0
committed
Resolves #921: Added extended documentation on dependencyIncludes/dependencyExcludes with a faq section and an example
1 parent 765e23f commit 0dba4e5

File tree

4 files changed

+112
-9
lines changed

4 files changed

+112
-9
lines changed

‎versions-enforcer/src/main/java/org/apache/maven/plugins/enforcer/MaxDependencyUpdates.java

+10-6
Original file line numberDiff line numberDiff line change
@@ -137,20 +137,24 @@ public class MaxDependencyUpdates implements EnforcerRule2 {
137137
protected boolean ignoreSubIncrementalUpdates = false;
138138

139139
/**
140-
* List of dependency inclusion patterns.
141-
* Only dependencies matching all the patterns will be considered.
140+
* <p>List of <u>input</u> dependency inclusion patterns.</p>
141+
* <p><b><u>Note</u>: even if a version is specified, it will refer to the input dependency version.</b>
142+
* To filter <u>output</u> versions, please use {@link #ruleSet}.</p>
143+
* <p>>Only dependencies matching all the patterns will be considered.
142144
* The wildcard "*" can be used as the only, first, last or both characters in each token.
143-
* The version token does support version ranges.
145+
* The version token does support version ranges.</p>
144146
*
145147
* @since 2.14.0
146148
*/
147149
protected List<String> dependencyIncludes = singletonList(WILDCARD);
148150

149151
/**
150-
* List of dependency exclusion patterns.
151-
* Only dependencies matching none of the patterns will be considered.
152+
* <p>List of <u>input</u> dependency exclusion patterns.</p>
153+
* <p><b><u>Note</u>: even if a version is specified, it will refer to the input dependency version.</b>
154+
* To filter <u>output</u> versions, please use {@link #ruleSet}.</p>
155+
* <p>Only dependencies matching none of the patterns will be considered.
152156
* The wildcard "*" can be used as the only, first, last or both characters in each token.
153-
* The version token does support version ranges.
157+
* The version token does support version ranges.</p>
154158
*
155159
* @since 2.14.0
156160
*/

‎versions-maven-plugin/src/main/java/org/codehaus/mojo/versions/DisplayDependencyUpdatesMojo.java

+7-3
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,9 @@ public class DisplayDependencyUpdatesMojo extends AbstractVersionsDisplayMojo {
152152
private boolean processDependencies;
153153

154154
/**
155-
* Only take these artifacts into consideration.
155+
* <p>Only take the specified <u>input</u> dependencies into account.</p>
156+
* <p><b><u>Note</u>: even if a version is specified, it will refer to the input dependency version.</b>
157+
* To filter <u>output</u> versions, please use {@link #ruleSet} or {@link #ignoredVersions}.</p>
156158
* <p>
157159
* Comma-separated list of extended GAV patterns.
158160
*
@@ -174,15 +176,17 @@ public class DisplayDependencyUpdatesMojo extends AbstractVersionsDisplayMojo {
174176
private List<String> dependencyIncludes;
175177

176178
/**
177-
* Exclude these artifacts from consideration.
179+
* <p>Do not take the specified <u>input</u> dependencies into account.</p>
180+
* <p><b><u>Note</u>: even if a version is specified, it will refer to the input dependency version.</b>
181+
* To filter <u>output</u> versions, please use {@link #ruleSet} or {@link #ignoredVersions}.</p>
178182
* <p>
179183
* Comma-separated list of extended GAV patterns.
180184
*
181185
* <p>
182186
* Extended GAV: groupId:artifactId:version:type:classifier:scope
183187
* </p>
184188
* <p>
185-
* The wildcard "*" can be used as the only, first, last or both characters in each token.
189+
* The wildca<u>Note:</u>rd "*" can be used as the only, first, last or both characters in each token.
186190
* The version token does support version ranges.
187191
* </p>
188192
*

‎versions-maven-plugin/src/site/markdown/examples/display-dependency-updates.md

+65
Original file line numberDiff line numberDiff line change
@@ -55,3 +55,68 @@ Which produces the following output:
5555
[INFO] Final Memory: 10M/167M
5656
[INFO] ------------------------------------------------------------------------
5757
```
58+
59+
# Ignore a specific version suffix in version updates
60+
61+
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.*`.
62+
63+
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.
64+
65+
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.
66+
67+
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:
68+
69+
```shell
70+
mvn org.codehaus.mojo:versions-maven-plugin:display-dependency-updates "-Dmaven.version.ignore=.*-M.*,.*-alpha.*"
71+
```
72+
73+
or:
74+
75+
```xml
76+
<configuration>
77+
...
78+
<ignoredVersions>.*-M.*,.*-alpha.*</ignoredVersions>
79+
...
80+
</configuration>
81+
```
82+
83+
in your project config. That will result in the following output. Instead of:
84+
85+
```shell
86+
[INFO] --- versions:2.15.0:display-dependency-updates (default-cli) @ versions-maven-plugin ---
87+
[INFO] The following dependencies in Dependency Management have newer versions:
88+
[INFO] dom4j:dom4j ................................. 1.6.1 -> 20040902.021138
89+
[INFO] org.apache.maven:maven-artifact ............... 3.2.5 -> 4.0.0-alpha-5
90+
[INFO] org.apache.maven:maven-compat ................. 3.2.5 -> 4.0.0-alpha-5
91+
[INFO] org.apache.maven:maven-core ................... 3.2.5 -> 4.0.0-alpha-5
92+
[INFO] org.apache.maven:maven-model .................. 3.2.5 -> 4.0.0-alpha-5
93+
[INFO] org.apache.maven:maven-plugin-api ............. 3.2.5 -> 4.0.0-alpha-5
94+
[INFO] org.apache.maven:maven-settings ............... 3.2.5 -> 4.0.0-alpha-5
95+
[INFO] org.apache.maven.enforcer:enforcer-api ................ 3.2.1 -> 3.3.0
96+
[INFO] org.apache.maven.plugin-testing:maven-plugin-testing-harness ...
97+
[INFO] 3.3.0 -> 4.0.0-alpha-1
98+
[INFO] org.apache.maven.plugin-tools:maven-plugin-annotations ...
99+
[INFO] 3.8.1 -> 3.8.2
100+
[INFO] org.mockito:mockito-inline ........................... 4.11.0 -> 5.2.0
101+
[INFO] org.slf4j:slf4j-simple ............................... 1.7.36 -> 2.0.7
102+
```
103+
104+
you will only see:
105+
106+
```shell
107+
[INFO] --- versions:2.15.0:display-dependency-updates (default-cli) @ versions-maven-plugin ---
108+
[INFO] The following dependencies in Dependency Management have newer versions:
109+
[INFO] dom4j:dom4j ................................. 1.6.1 -> 20040902.021138
110+
[INFO] org.apache.maven:maven-artifact ....................... 3.2.5 -> 3.9.2
111+
[INFO] org.apache.maven:maven-compat ......................... 3.2.5 -> 3.9.2
112+
[INFO] org.apache.maven:maven-core ........................... 3.2.5 -> 3.9.2
113+
[INFO] org.apache.maven:maven-model .......................... 3.2.5 -> 3.9.2
114+
[INFO] org.apache.maven:maven-plugin-api ..................... 3.2.5 -> 3.9.2
115+
[INFO] org.apache.maven:maven-settings ....................... 3.2.5 -> 3.9.2
116+
[INFO] org.apache.maven.enforcer:enforcer-api ................ 3.2.1 -> 3.3.0
117+
[INFO] org.apache.maven.plugin-tools:maven-plugin-annotations ...
118+
[INFO] 3.8.1 -> 3.8.2
119+
[INFO] org.mockito:mockito-inline ........................... 4.11.0 -> 5.2.0
120+
[INFO] org.slf4j:slf4j-simple ............................... 1.7.36 -> 2.0.7
121+
```
122+

‎versions-maven-plugin/src/site/markdown/faq.md

+30
Original file line numberDiff line numberDiff line change
@@ -64,3 +64,33 @@ manager.
6464

6565
In most cases, using a repository manager will solve these issues as the repository managers usually
6666
rebuild the metadata files based on the artifacts that are present.
67+
68+
### Why is a dependency version not excluded by dependencyExcludes
69+
70+
`dependencyIncludes` and `dependencyExcludes` work on *input* dependencies and not on <u>output</u> 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.
71+
72+
The reason for that is that the option filters *input* dependency versions.
73+
74+
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.*`.
75+
76+
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.
77+
78+
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.
79+
80+
So, to ignore all updates with an `-M.*` at the end of the version string, simply use:
81+
82+
`-Dmaven.version.ignore=.*-M.*`
83+
84+
or:
85+
86+
```xml
87+
<configuration>
88+
...
89+
<ignoredVersions>.*-M.*</ignoredVersions>
90+
...
91+
</configuration>
92+
```
93+
94+
in your project config.
95+
96+
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)

0 commit comments

Comments
 (0)