You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sl...@apache.org on 2026/08/06 17:23:26 UTC
(maven-dependency-plugin) 02/02: Port the site documentation from APT to Markdown
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-dependency-plugin.git
commit 5c174eb123437182c6dd69a0bfe5cb997ccf6362
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Thu Aug 6 13:53:04 2026 +0200
Port the site documentation from APT to Markdown
15 page(s) converted with doxia-converter and then cleaned up by hand:
- <<<code>>> becomes backticks, <<bold>> becomes **bold**, {{{url}text}}
becomes [text](url)
- the ASF license header becomes a single block HTML comment
- a page whose only Velocity reference was ${project.name} is now a plain
.md with the title spelled out
- a page that keeps a reference stays a .vm. Velocity reads ## as a line
comment and would silently swallow every ATX heading below level one, so
subsections use setext underlines and anything deeper is wrapped in
#[[ ... ]]#
- a reference APT rendered literally is escaped with ${esc.d}, which always
yields a literal dollar; a backslash only works when the reference itself
resolves
Verified by building the site before and after and comparing every generated
page: the visible text and the link targets are unchanged apart from
<b>/<i> becoming <strong>/<em> and quotes and ellipses in prose picking up
the Markdown module's typographic substitution.
---
src/site/markdown/examples/copying-artifacts.md.vm | 140 ++---
.../examples/copying-project-dependencies.md.vm | 85 ++-
...ude-dependencies-from-dependency-analysis.md.vm | 78 +--
...the-build-on-dependency-analysis-warnings.md.vm | 66 +--
.../examples/filtering-the-dependency-tree.md | 117 ++--
.../markdown/examples/managing-dependencies.md.vm | 260 ++++-----
.../examples/purging-local-repository.md.vm | 149 ++---
.../markdown/examples/render-dependencies.md.vm | 58 +-
src/site/markdown/examples/tree-mojo.md | 258 ++++-----
.../markdown/examples/unpacking-artifacts.md.vm | 77 ++-
.../markdown/examples/unpacking-filemapper.md.vm | 79 ++-
.../examples/unpacking-project-dependencies.md.vm | 57 +-
.../examples/using-dependencies-sources.md.vm | 59 +-
src/site/markdown/index.md | 263 +++------
src/site/markdown/usage.md.vm | 608 +++++++++------------
15 files changed, 945 insertions(+), 1409 deletions(-)
diff --git a/src/site/markdown/examples/copying-artifacts.md.vm b/src/site/markdown/examples/copying-artifacts.md.vm
index 4fe75867..aba17101 100644
--- a/src/site/markdown/examples/copying-artifacts.md.vm
+++ b/src/site/markdown/examples/copying-artifacts.md.vm
@@ -1,37 +1,27 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
- ------
- Copying specific artifacts
- ------
- Allan Ramirez
- Brian Fox
- Stephen Connolly
- ------
- 2011-07-01
- ------
-
-Copying specific artifacts
-
- In copying specific artifacts, you need to bind the <<<dependency:copy>>>
- mojo to a lifecycle, configure the plugin and specify the artifacts you
- want to copy. See the following example:
-
-+---+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Copying specific artifacts
+
+In copying specific artifacts, you need to bind the `dependency:copy` mojo to a lifecycle, configure the plugin and specify the artifacts you want to copy. See the following example:
+
+```xml
<project>
[...]
<build>
@@ -57,11 +47,11 @@ Copying specific artifacts
<version>3.8.1</version>
<type>jar</type>
<overWrite>false</overWrite>
- <outputDirectory>\${project.build.directory}/alternateLocation</outputDirectory>
+ <outputDirectory>${esc.d}{project.build.directory}/alternateLocation</outputDirectory>
<destFileName>optional-new-name.jar</destFileName>
</artifactItem>
</artifactItems>
- <outputDirectory>\${project.build.directory}/wars</outputDirectory>
+ <outputDirectory>${esc.d}{project.build.directory}/wars</outputDirectory>
<overWriteReleases>false</overWriteReleases>
<overWriteSnapshots>true</overWriteSnapshots>
</configuration>
@@ -70,27 +60,21 @@ Copying specific artifacts
</build>
[...]
</project>
-+---+
-
- Then after executing <<<mvn package>>>, the artifact (junit) is copied to the
- given alternate location.
-
- Artifacts are resolved from the following sources in order:
-
- * the current reactor,
+```
- * the local repository,
+Then after executing `mvn package`, the artifact (junit) is copied to the given alternate location.
- * the configured remote repositories.
+Artifacts are resolved from the following sources in order:
- []
+- the current reactor,
+- the local repository,
+- the configured remote repositories.
- If the artifact cannot be resolved from the above sources then the build will fail.
+If the artifact cannot be resolved from the above sources then the build will fail.
- If the artifact is also listed as a dependency, the <<<version>>> of the <<<artifactItem>>> will default to
- the version from the <<<dependencies>>> or <<<dependencyManagement>>>, e.g.
+If the artifact is also listed as a dependency, the `version` of the `artifactItem` will default to the version from the `dependencies` or `dependencyManagement`, e.g.
-+---+
+```xml
<project>
[...]
<dependencies>
@@ -121,11 +105,11 @@ Copying specific artifacts
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<overWrite>false</overWrite>
- <outputDirectory>\${project.build.directory}/alternateLocation</outputDirectory>
+ <outputDirectory>${esc.d}{project.build.directory}/alternateLocation</outputDirectory>
<destFileName>optional-new-name.jar</destFileName>
</artifactItem>
</artifactItems>
- <outputDirectory>\${project.build.directory}/wars</outputDirectory>
+ <outputDirectory>${esc.d}{project.build.directory}/wars</outputDirectory>
<overWriteReleases>false</overWriteReleases>
<overWriteSnapshots>true</overWriteSnapshots>
</configuration>
@@ -136,15 +120,11 @@ Copying specific artifacts
</build>
[...]
</project>
-+---+
+```
- The <<<dependency:copy>>> goal can also be used to copy the just built
- artifact to a custom location if desired. <<It must be bound
- to any phase after the package phase>> so that the artifact exists in the
- repository. The following configuration shows how (binding to the
- install phase in this case):
+The `dependency:copy` goal can also be used to copy the just built artifact to a custom location if desired. **It must be bound to any phase after the package phase** so that the artifact exists in the repository. The following configuration shows how (binding to the install phase in this case):
-+---+
+```xml
<project>
[...]
<build>
@@ -163,10 +143,10 @@ Copying specific artifacts
<configuration>
<artifactItems>
<artifactItem>
- <groupId>\${project.groupId}</groupId>
- <artifactId>\${project.artifactId}</artifactId>
- <version>\${project.version}</version>
- <type>\${project.packaging}</type>
+ <groupId>${esc.d}{project.groupId}</groupId>
+ <artifactId>${esc.d}{project.artifactId}</artifactId>
+ <version>${esc.d}{project.version}</version>
+ <type>${esc.d}{project.packaging}</type>
</artifactItem>
</artifactItems>
<outputDirectory>some-other-place</outputDirectory>
@@ -178,19 +158,15 @@ Copying specific artifacts
</build>
[...]
</project>
-+---+
+```
-{Using an alternate local repository}
+# <a id="Using_an_alternate_local_repository"></a>Using an alternate local repository
- <<dependency:copy>> always downloads artifacts to default local repository first, and then
- copy the artifacts to the desired locations. For large size unique snapshot artifacts, the downloads can quickly
- fill up default local repository, and therefore local disk, after many executions.
- To clean up the downloaded artifacts as part the build, set <localRepositoryDirectory>'s value
- to a location in your project's target directory.
+**dependency:copy** always downloads artifacts to default local repository first, and then copy the artifacts to the desired locations. For large size unique snapshot artifacts, the downloads can quickly fill up default local repository, and therefore local disk, after many executions. To clean up the downloaded artifacts as part the build, set _localRepositoryDirectory_'s value to a location in your project's target directory.
- This use case also applies to <<dependency:unpack>> goal.
+This use case also applies to **dependency:unpack** goal.
-+---+
+```xml
<project>
[...]
<build>
@@ -213,7 +189,7 @@ Copying specific artifacts
</artifactItem>
[...]
</artifactItems>
- <localRepositoryDirectory>\${project.build.directory}/localrepo</localRepositoryDirectory>
+ <localRepositoryDirectory>${esc.d}{project.build.directory}/localrepo</localRepositoryDirectory>
</configuration>
</execution>
</executions>
@@ -222,19 +198,19 @@ Copying specific artifacts
</build>
[...]
</project>
-+---+
+```
-{Copying from the command line}
+# <a id="Copying_from_the_command_line"></a>Copying from the command line
- If you intend to configure this mojo for execution on the command line using:
+If you intend to configure this mojo for execution on the command line using:
-+---+
+```shell
mvn dependency:copy
-+---+
+```
- you must not put the configuration inside the <executions> tag. Your configuration should look like this:
+you must not put the configuration inside the _executions_ tag. Your configuration should look like this:
-+---+
+```xml
<project>
[...]
<build>
@@ -262,4 +238,4 @@ mvn dependency:copy
</build>
[...]
</project>
-+---+
+```
diff --git a/src/site/markdown/examples/copying-project-dependencies.md.vm b/src/site/markdown/examples/copying-project-dependencies.md.vm
index f904e80d..3b65aa16 100644
--- a/src/site/markdown/examples/copying-project-dependencies.md.vm
+++ b/src/site/markdown/examples/copying-project-dependencies.md.vm
@@ -1,36 +1,27 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
- ------
- Copying project dependencies
- ------
- Allan Ramirez
- Brian Fox
- ------
- 2006-11-01
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
-Copying project dependencies
+http://www.apache.org/licenses/LICENSE-2.0
- Project dependencies are the dependencies declared in your pom. To copy them with their transitive dependencies, use the
- <<<dependency:copy-dependencies>>> mojo and configure the plugin like
- the sample below:
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
-+---+
+# Copying project dependencies
+
+Project dependencies are the dependencies declared in your pom. To copy them with their transitive dependencies, use the `dependency:copy-dependencies` mojo and configure the plugin like the sample below:
+
+```xml
<project>
[...]
<build>
@@ -47,7 +38,7 @@ Copying project dependencies
<goal>copy-dependencies</goal>
</goals>
<configuration>
- <outputDirectory>\${project.build.directory}/alternateLocation</outputDirectory>
+ <outputDirectory>${esc.d}{project.build.directory}/alternateLocation</outputDirectory>
<overWriteReleases>false</overWriteReleases>
<overWriteSnapshots>false</overWriteSnapshots>
<overWriteIfNewer>true</overWriteIfNewer>
@@ -59,15 +50,14 @@ Copying project dependencies
</build>
[...]
</project>
-+---+
+```
-* Excluding transitive dependencies
+Excluding transitive dependencies
+---------------------------------
- As mentioned, {{{https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html}transitive dependencies}} are copied by default. However, they
- can also be excluded by setting the <<<excludeTransitive>>> property to
- <<true>>.
+As mentioned, [transitive dependencies](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html) are copied by default. However, they can also be excluded by setting the `excludeTransitive` property to **true**.
-+---+
+```xml
<project>
[...]
<build>
@@ -84,7 +74,7 @@ Copying project dependencies
<goal>copy-dependencies</goal>
</goals>
<configuration>
- <outputDirectory>\${project.build.directory}/alternateLocation</outputDirectory>
+ <outputDirectory>${esc.d}{project.build.directory}/alternateLocation</outputDirectory>
<overWriteReleases>false</overWriteReleases>
<overWriteSnapshots>true</overWriteSnapshots>
<excludeTransitive>true</excludeTransitive>
@@ -96,14 +86,14 @@ Copying project dependencies
</build>
[...]
</project>
-+---+
+```
-* Subtrees
+Subtrees
+--------
- By default, the pom is considered the root of the dependency tree, but it can be useful to get the jars of one dependency and all its transitive dependencies.
- This can be done by specifying one or more <<graphRoots>>.
+By default, the pom is considered the root of the dependency tree, but it can be useful to get the jars of one dependency and all its transitive dependencies. This can be done by specifying one or more **graphRoots**.
-+---+
+```xml
<project>
[...]
<build>
@@ -122,12 +112,12 @@ Copying project dependencies
<configuration>
<graphRoots>
<graphRoot>
- <groupId>org.apache.maven.resolver</groupId>
- <artifactId>maven-resolver-supplier-mvn4</artifactId>
+ <groupId>org.apache.maven.resolver</groupId>
+ <artifactId>maven-resolver-supplier-mvn4</artifactId>
</graphRoot>
</graphRoots>
<!-- move to separate directory, so it can get its own classloader -->
- <outputDirectory>\${project.build.directory}/lib-ext/maven-resolver-supplier-mvn4</outputDirectory>
+ <outputDirectory>${esc.d}{project.build.directory}/lib-ext/maven-resolver-supplier-mvn4</outputDirectory>
</configuration>
</execution>
</executions>
@@ -143,5 +133,4 @@ Copying project dependencies
</dependency>
</dependencies>
</project>
-+---+
-
\ No newline at end of file
+```
diff --git a/src/site/markdown/examples/exclude-dependencies-from-dependency-analysis.md.vm b/src/site/markdown/examples/exclude-dependencies-from-dependency-analysis.md.vm
index 4514937d..36c98ec9 100644
--- a/src/site/markdown/examples/exclude-dependencies-from-dependency-analysis.md.vm
+++ b/src/site/markdown/examples/exclude-dependencies-from-dependency-analysis.md.vm
@@ -1,48 +1,33 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
- ------
- Exclude dependencies from dependency analysis
- ------
- Henning Schmiedehausen
- ------
- 2015-01-01
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
-Exclude dependencies from dependency analysis
+http://www.apache.org/licenses/LICENSE-2.0
- A project's dependencies can be analyzed as part of the build process by binding the <<<dependency:analyze-only>>>
- goal to the lifecycle. By default, the analysis will be performed during the <<<verify>>> lifecycle phase.
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
- It is possible to have necessary dependencies on the classpath that
- cause either "Declared but unused" or "Undeclared but used" warnings.
- One common cause of byte code analysis being unable to
- determine whether a jar is required are annotations with
- source retention. Another common cause is
- a class that is loaded by reflection at runtime.
+# Exclude dependencies from dependency analysis
- The dependency plugin does not warn about a few common dependencies
- where its analysis is known to be unreliable, most notably SLF4J.
+A project's dependencies can be analyzed as part of the build process by binding the `dependency:analyze-only` goal to the lifecycle. By default, the analysis will be performed during the `verify` lifecycle phase.
- If you encounter other false positives, you can configure the plugin to ignore particular
- dependencies that are "declared but unused", "undeclared but used", and "non-test scoped".
- See the following POM configuration for an example:
+It is possible to have necessary dependencies on the classpath that cause either "Declared but unused" or "Undeclared but used" warnings. One common cause of byte code analysis being unable to determine whether a jar is required are annotations with source retention. Another common cause is a class that is loaded by reflection at runtime.
-+---+
+The dependency plugin does not warn about a few common dependencies where its analysis is known to be unreliable, most notably SLF4J.
+
+If you encounter other false positives, you can configure the plugin to ignore particular dependencies that are "declared but unused", "undeclared but used", and "non-test scoped". See the following POM configuration for an example:
+
+```xml
<project>
...
<build>
@@ -87,15 +72,12 @@ Exclude dependencies from dependency analysis
</build>
...
</project>
-+---+
+```
+
+Note that the `dependency:analyze-only` goal is used in preference to `dependency:analyze` since it doesn't force a further compilation of the project, but uses the compiled classes produced from the earlier `test-compile` phase in the lifecycle.
- Note that the <<<dependency:analyze-only>>> goal is used in preference to <<<dependency:analyze>>> since it doesn't
- force a further compilation of the project, but uses the compiled classes produced from the earlier
- <<<test-compile>>> phase in the lifecycle.
+The project's dependencies will then be automatically analyzed during the `verify` lifecycle phase, which can be executed explicitly as follows:
- The project's dependencies will then be automatically analyzed during the <<<verify>>> lifecycle phase, which can be
- executed explicitly as follows:
-
-+---+
+```shell
mvn verify
-+---+
+```
diff --git a/src/site/markdown/examples/failing-the-build-on-dependency-analysis-warnings.md.vm b/src/site/markdown/examples/failing-the-build-on-dependency-analysis-warnings.md.vm
index f3ef73cb..19a1bae8 100644
--- a/src/site/markdown/examples/failing-the-build-on-dependency-analysis-warnings.md.vm
+++ b/src/site/markdown/examples/failing-the-build-on-dependency-analysis-warnings.md.vm
@@ -1,36 +1,27 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
- ------
- Failing the build on dependency analysis warnings
- ------
- Mark Hobson
- ------
- 2007-09-01
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
-Failing the build on dependency analysis warnings
+http://www.apache.org/licenses/LICENSE-2.0
- A project's dependencies can be analyzed as part of the build process by binding the <<<dependency:analyze-only>>>
- goal to the lifecycle. By default, the analysis will be performed during the <<<verify>>> lifecycle phase. The
- plugin can then be configured to fail the build if any dependency analysis warnings are encountered by setting the
- <<<failOnWarning>>> parameter. See the following POM configuration for an example:
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
-+---+
+# Failing the build on dependency analysis warnings
+
+A project's dependencies can be analyzed as part of the build process by binding the `dependency:analyze-only` goal to the lifecycle. By default, the analysis will be performed during the `verify` lifecycle phase. The plugin can then be configured to fail the build if any dependency analysis warnings are encountered by setting the `failOnWarning` parameter. See the following POM configuration for an example:
+
+```xml
<project>
...
<build>
@@ -55,15 +46,12 @@ Failing the build on dependency analysis warnings
</build>
...
</project>
-+---+
+```
+
+Note that the `dependency:analyze-only` goal is used in preference to `dependency:analyze` since it doesn't force a further compilation of the project, but uses the compiled classes produced from the earlier `test-compile` phase in the lifecycle.
- Note that the <<<dependency:analyze-only>>> goal is used in preference to <<<dependency:analyze>>> since it doesn't
- force a further compilation of the project, but uses the compiled classes produced from the earlier
- <<<test-compile>>> phase in the lifecycle.
+The project's dependencies will then be automatically analyzed during the `verify` lifecycle phase, which can be executed explicitly as follows:
- The project's dependencies will then be automatically analyzed during the <<<verify>>> lifecycle phase, which can be
- executed explicitly as follows:
-
-+---+
+```shell
mvn verify
-+---+
+```
diff --git a/src/site/markdown/examples/filtering-the-dependency-tree.md b/src/site/markdown/examples/filtering-the-dependency-tree.md
index ee138763..26f3fa54 100644
--- a/src/site/markdown/examples/filtering-the-dependency-tree.md
+++ b/src/site/markdown/examples/filtering-the-dependency-tree.md
@@ -1,87 +1,74 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
- ------
- Filtering the dependency tree
- ------
- Mark Hobson
- ------
- 2007-09-01
- ------
-
-Filtering the dependency tree
-
- A project's dependency tree can be filtered to locate specific dependencies. For example, to find out why Velocity
- is being used by the Maven Dependency Plugin, we can execute the following in the project's directory:
-
-+---+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Filtering the dependency tree
+
+A project's dependency tree can be filtered to locate specific dependencies. For example, to find out why Velocity is being used by the Maven Dependency Plugin, we can execute the following in the project's directory:
+
+```shell
mvn dependency:tree -Dincludes=velocity:velocity
-+---+
+```
- Which outputs:
+Which outputs:
-+---+
+```unknown
[INFO] [dependency:tree]
[INFO] org.apache.maven.plugins:maven-dependency-plugin:maven-plugin:2.0-alpha-5-SNAPSHOT
[INFO] \- org.apache.maven.doxia:doxia-site-renderer:jar:1.0-alpha-8:compile
[INFO] \- org.codehaus.plexus:plexus-velocity:jar:1.1.3:compile
[INFO] \- velocity:velocity:jar:1.4:compile
-+---+
+```
- Thus we can see that Velocity is being brought in by Plexus Velocity, which in turn is being brought in by a direct
- dependency on Doxia Site Renderer.
+Thus we can see that Velocity is being brought in by Plexus Velocity, which in turn is being brought in by a direct dependency on Doxia Site Renderer.
-* Filter pattern syntax
+## Filter pattern syntax
- The syntax for filter patterns is as follows:
-
-+---+
+The syntax for filter patterns is as follows:
+
+```unknown
[groupId]:[artifactId]:[type]:[version]
-+---+
+```
+
+Where each pattern segment is optional and supports full and partial `*` wildcards. An empty pattern segment is treated as an implicit wildcard.
+
+For example, `org.apache.*` would match all artifacts whose group id started with `org.apache.`, and `:::*-SNAPSHOT` would match all snapshot artifacts.
- Where each pattern segment is optional and supports full and partial <<<*>>> wildcards. An empty pattern segment is
- treated as an implicit wildcard.
-
- For example, <<<org.apache.*>>> would match all artifacts whose group id started with <<<org.apache.>>>, and
- <<<:::*-SNAPSHOT>>> would match all snapshot artifacts.
+## Excluding dependencies from the tree
-* Excluding dependencies from the tree
+The dependency tree can also be filtered to remove specific dependencies. For example, to exclude Plexus dependencies from the tree, we can execute the following:
- The dependency tree can also be filtered to remove specific dependencies. For example, to exclude Plexus
- dependencies from the tree, we can execute the following:
-
-+---+
+```shell
mvn dependency:tree -Dexcludes=org.codehaus.plexus
-+---+
+```
-* Specifying multiple patterns
+## Specifying multiple patterns
- Multiple patterns can be specified when filtering the dependency tree by separating the patterns with commas. For
- example, to exclude Maven and Plexus dependencies from the tree, we can execute the following:
-
-+---+
+Multiple patterns can be specified when filtering the dependency tree by separating the patterns with commas. For example, to exclude Maven and Plexus dependencies from the tree, we can execute the following:
+
+```shell
mvn dependency:tree -Dexcludes=org.apache.maven*,org.codehaus.plexus
-+---+
+```
+
+## Including and excluding dependencies from the tree
-* Including and excluding dependencies from the tree
+Both include and exclude patterns and be specified together to filter the dependency tree. For example, to locate all non-snapshot Plexus dependencies in the tree, we can execute the following:
- Both include and exclude patterns and be specified together to filter the dependency tree. For example, to locate
- all non-snapshot Plexus dependencies in the tree, we can execute the following:
-
-+---+
+```shell
mvn dependency:tree -Dincludes=org.codehaus.plexus -Dexcludes=:::*-SNAPSHOT
-+---+
+```
diff --git a/src/site/markdown/examples/managing-dependencies.md.vm b/src/site/markdown/examples/managing-dependencies.md.vm
index 8f384e9c..79ee9b4f 100644
--- a/src/site/markdown/examples/managing-dependencies.md.vm
+++ b/src/site/markdown/examples/managing-dependencies.md.vm
@@ -1,231 +1,201 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
- ------
- Managing Dependencies
- ------
- Bruno Borges
- ------
- 2025-06-01
- ------
-
-Managing Dependencies
-
- Starting with version 3.11.0, the Maven Dependency Plugin provides two goals
- for managing dependencies directly from the command line: <<<dependency:add>>>
- and <<<dependency:remove>>>.
-
-%{toc|fromDepth=2}
-
-* Adding Dependencies
-
- The <<<dependency:add>>> goal adds a dependency to your project's <<<pom.xml>>>.
-
-** Basic Usage
-
- You can add a dependency by specifying its coordinates with the <<<gav>>> parameter:
-
-+---+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Managing Dependencies
+
+Starting with version 3.11.0, the Maven Dependency Plugin provides two goals for managing dependencies directly from the command line: `dependency:add` and `dependency:remove`.
+
+<!-- MACRO{toc|fromDepth=2} -->
+
+Adding Dependencies
+-------------------
+
+The `dependency:add` goal adds a dependency to your project's `pom.xml`.
+
+#[[### Basic Usage]]#
+
+You can add a dependency by specifying its coordinates with the `gav` parameter:
+
+```shell
mvn dependency:add -Dgav=org.apache.commons:commons-lang3:3.17.0
-+---+
+```
- The <<<gav>>> parameter accepts the format <<<groupId:artifactId[:extension[:classifier]]:version>>>.
- Scope must be specified separately with <<<-Dscope>>>:
+The `gav` parameter accepts the format `groupId:artifactId[:extension[:classifier]]:version`. Scope must be specified separately with `-Dscope`:
-+---+
+```shell
mvn dependency:add -Dgav=org.apache.commons:commons-lang3:3.17.0 -Dscope=test
-+---+
+```
-** Adding to dependencyManagement
+#[[### Adding to dependencyManagement]]#
- Use the <<<-Dmanaged>>> flag to add a dependency to the <<<\<dependencyManagement\>>>> section
- instead of <<<\<dependencies\>>>>:
+Use the `-Dmanaged` flag to add a dependency to the `<dependencyManagement>` section instead of `<dependencies>`:
-+---+
+```shell
mvn dependency:add -Dgav=org.apache.commons:commons-lang3:3.17.0 -Dmanaged
-+---+
+```
-** Adding a BOM Import
+#[[### Adding a BOM Import]]#
- To import a BOM (Bill of Materials) into <<<\<dependencyManagement\>>>>, specify the type and scope explicitly:
+To import a BOM (Bill of Materials) into `<dependencyManagement>`, specify the type and scope explicitly:
-+---+
+```shell
mvn dependency:add -Dgav=org.springframework.boot:spring-boot-dependencies:pom:3.2.0 -Dscope=import -Dmanaged
-+---+
+```
- This inserts a dependency with <<<type=pom>>> and <<<scope=import>>> into <<<\<dependencyManagement\>>>>.
+This inserts a dependency with `type=pom` and `scope=import` into `<dependencyManagement>`.
-** Version Inference
+#[[### Version Inference]]#
- When adding to <<<\<dependencies\>>>> and the version is already managed by a parent POM's
- <<<\<dependencyManagement\>>>>, you can omit the version:
+When adding to `<dependencies>` and the version is already managed by a parent POM's `<dependencyManagement>`, you can omit the version:
-+---+
+```shell
mvn dependency:add -Dgav=org.apache.commons:commons-lang3
-+---+
+```
- The goal will detect the managed version and omit the <<<\<version\>>>> element from the inserted
- dependency, following Maven convention. If no managed version is found, the goal fails with
- a descriptive error.
+The goal will detect the managed version and omit the `<version>` element from the inserted dependency, following Maven convention. If no managed version is found, the goal fails with a descriptive error.
-** Additional Parameters
+#[[### Additional Parameters]]#
- You can also specify <<<type>>> and <<<classifier>>> explicitly. These override any values
- provided in the <<<gav>>> shorthand:
+You can also specify `type` and `classifier` explicitly. These override any values provided in the `gav` shorthand:
-+---+
+```shell
mvn dependency:add -Dgav=com.example:lib:1.0 -Dtype=test-jar
mvn dependency:add -Dgav=com.example:lib:1.0 -Dclassifier=sources
-+---+
+```
-** Duplicate Detection
+#[[### Duplicate Detection]]#
- If the dependency already exists in the POM (matching on <<<groupId>>>, <<<artifactId>>>,
- <<<type>>>, and <<<classifier>>>), the goal fails with a descriptive error directing you to
- remove the existing dependency first:
+If the dependency already exists in the POM (matching on `groupId`, `artifactId`, `type`, and `classifier`), the goal fails with a descriptive error directing you to remove the existing dependency first:
-+---+
+```shell
mvn dependency:remove -Dgav=org.apache.commons:commons-lang3
mvn dependency:add -Dgav=org.apache.commons:commons-lang3:3.17.0 -Dscope=test
-+---+
+```
-** Optional Dependencies
+#[[### Optional Dependencies]]#
- Mark a dependency as optional using the <<<optional>>> parameter:
+Mark a dependency as optional using the `optional` parameter:
-+---+
+```shell
mvn dependency:add -Dgav=org.apache.commons:commons-lang3:3.17.0 -Doptional=true
-+---+
+```
-** Scope Validation
+#[[### Scope Validation]]#
- The <<<scope>>> parameter is validated against Maven's known scope values:
- <<<compile>>>, <<<provided>>>, <<<runtime>>>, <<<test>>>, <<<system>>>, and <<<import>>>.
- Invalid scope values are rejected with an error.
+The `scope` parameter is validated against Maven's known scope values: `compile`, `provided`, `runtime`, `test`, `system`, and `import`. Invalid scope values are rejected with an error.
-** Dependencies Using Property References
+#[[### Dependencies Using Property References]]#
- Some POMs declare dependencies using Maven property references for the <<<groupId>>> or
- <<<artifactId>>>, for example:
+Some POMs declare dependencies using Maven property references for the `groupId` or `artifactId`, for example:
-+---+
+```xml
<dependency>
<groupId>${my.group}</groupId>
<artifactId>lib</artifactId>
</dependency>
-+---+
+```
- When <<<dependency:add>>> detects that a dependency with the same coordinates already exists
- in the resolved (effective) model but cannot be found in the raw XML, it means the dependency
- is declared using property interpolation. In this case, the goal <<fails>> with an error message
- explaining that the dependency cannot be safely added or updated automatically:
+When `dependency:add` detects that a dependency with the same coordinates already exists in the resolved (effective) model but cannot be found in the raw XML, it means the dependency is declared using property interpolation. In this case, the goal **fails** with an error message explaining that the dependency cannot be safely added or updated automatically:
-+---+
+```unknown
[ERROR] Dependency com.example:lib already exists in the POM (using property references).
Cannot safely add or update automatically. Please edit the POM manually.
-+---+
+```
- This safety check prevents <<<dependency:add>>> from inserting a duplicate entry that would
- conflict with the property-based declaration. The same check applies to <<<dependency:remove>>>.
+This safety check prevents `dependency:add` from inserting a duplicate entry that would conflict with the property-based declaration. The same check applies to `dependency:remove`.
-** Multi-Module Projects
+#[[### Multi-Module Projects]]#
- To add a dependency to a specific child module from the root of a multi-module project,
- use Maven's built-in <<<-pl>>> (project list) flag:
+To add a dependency to a specific child module from the root of a multi-module project, use Maven's built-in `-pl` (project list) flag:
-+---+
+```shell
mvn dependency:add -Dgav=org.apache.commons:commons-lang3:3.17.0 -pl my-service
-+---+
+```
-** Adding to a Profile
+#[[### Adding to a Profile]]#
- To add a dependency to a specific Maven profile, use the <<<-Dprofile>>> parameter.
- The profile must already exist in the POM:
+To add a dependency to a specific Maven profile, use the `-Dprofile` parameter. The profile must already exist in the POM:
-+---+
+```shell
mvn dependency:add -Dgav=org.apache.commons:commons-lang3:3.17.0 -Dprofile=dev
-+---+
+```
-* Removing Dependencies
+Removing Dependencies
+---------------------
- The <<<dependency:remove>>> goal removes a dependency from your project's <<<pom.xml>>>.
+The `dependency:remove` goal removes a dependency from your project's `pom.xml`.
-** Basic Usage
+#[[### Basic Usage]]#
- Remove a dependency using the <<<gav>>> parameter:
+Remove a dependency using the `gav` parameter:
-+---+
+```shell
mvn dependency:remove -Dgav=org.apache.commons:commons-lang3
-+---+
+```
- Only <<<groupId>>> and <<<artifactId>>> are required to identify the dependency to remove.
+Only `groupId` and `artifactId` are required to identify the dependency to remove.
-** Type and Classifier Matching
+#[[### Type and Classifier Matching]]#
- Maven allows the same <<<groupId:artifactId>>> to appear multiple times in a POM
- with different types or classifiers (e.g., both the main jar and a test-jar). These
- are distinct dependencies.
+Maven allows the same `groupId:artifactId` to appear multiple times in a POM with different types or classifiers (e.g., both the main jar and a test-jar). These are distinct dependencies.
- When no <<<-Dtype>>> or <<<-Dclassifier>>> is specified, <<<dependency:remove>>> targets
- the default variant (<<<type=jar>>>, no classifier). To remove a specific variant, use
- <<<-Dtype>>> and/or <<<-Dclassifier>>>:
+When no `-Dtype` or `-Dclassifier` is specified, `dependency:remove` targets the default variant (`type=jar`, no classifier). To remove a specific variant, use `-Dtype` and/or `-Dclassifier`:
-+---+
+```shell
mvn dependency:remove -Dgav=com.example:lib -Dtype=test-jar
mvn dependency:remove -Dgav=com.example:lib -Dclassifier=sources
-+---+
+```
- Explicit <<<-Dtype>>> and <<<-Dclassifier>>> override any values from the <<<-Dgav>>> parameter.
+Explicit `-Dtype` and `-Dclassifier` override any values from the `-Dgav` parameter.
- Similarly, <<<dependency:add>>> uses <<<groupId:artifactId:type:classifier>>> matching for
- duplicate detection. Adding <<<com.example:lib:test-jar:1.0>>> will succeed even if
- <<<com.example:lib:jar:1.0>>> already exists, since they are distinct dependencies.
+Similarly, `dependency:add` uses `groupId:artifactId:type:classifier` matching for duplicate detection. Adding `com.example:lib:test-jar:1.0` will succeed even if `com.example:lib:jar:1.0` already exists, since they are distinct dependencies.
-** Removing a BOM Import
+#[[### Removing a BOM Import]]#
- To remove a BOM import from <<<\<dependencyManagement\>>>>, specify the type and use <<<-Dmanaged>>>:
+To remove a BOM import from `<dependencyManagement>`, specify the type and use `-Dmanaged`:
-+---+
+```shell
mvn dependency:remove -Dgav=org.springframework.boot:spring-boot-dependencies -Dtype=pom -Dmanaged
-+---+
+```
-** Removing from dependencyManagement
+#[[### Removing from dependencyManagement]]#
- To remove a dependency from <<<\<dependencyManagement\>>>> instead of <<<\<dependencies\>>>>:
+To remove a dependency from `<dependencyManagement>` instead of `<dependencies>`:
-+---+
+```shell
mvn dependency:remove -Dgav=org.apache.commons:commons-lang3 -Dmanaged
-+---+
+```
-** Removing from a Specific Module
+#[[### Removing from a Specific Module]]#
- In a multi-module project, use Maven's <<<-pl>>> flag to target a specific child module:
+In a multi-module project, use Maven's `-pl` flag to target a specific child module:
-+---+
+```shell
mvn dependency:remove -Dgav=org.apache.commons:commons-lang3 -pl my-service
-+---+
+```
- If the dependency is not found, the goal fails with a descriptive error message.
+If the dependency is not found, the goal fails with a descriptive error message.
-** Removing from a Profile
+#[[### Removing from a Profile]]#
- To remove a dependency from a specific Maven profile:
+To remove a dependency from a specific Maven profile:
-+---+
+```shell
mvn dependency:remove -Dgav=org.apache.commons:commons-lang3 -Dprofile=dev
-+---+
-
+```
diff --git a/src/site/markdown/examples/purging-local-repository.md.vm b/src/site/markdown/examples/purging-local-repository.md.vm
index e7029fde..e9ad813e 100644
--- a/src/site/markdown/examples/purging-local-repository.md.vm
+++ b/src/site/markdown/examples/purging-local-repository.md.vm
@@ -1,68 +1,52 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
- ------
- Purging project dependencies
- ------
- Nicolas Cazottes
- Paul Gier
- ------
- 2012-10-01
- ------
-
-Purging local repository dependencies
-
- The purpose of the <<<dependency:purge-local-repository>>> goal is to purge
- (delete and optionally re-resolve) artifacts from the local maven repository.
- This page describes some of the configuration options available to the plugin.
-
-* Basic usage
-
- The default behaviour of the plugin is to first resolve the entire dependency
- tree, then delete the contents from the local repository, and then re-resolve
- the dependencies from the remote repository.
-
-+---+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Purging local repository dependencies
+
+The purpose of the `dependency:purge-local-repository` goal is to purge (delete and optionally re-resolve) artifacts from the local maven repository. This page describes some of the configuration options available to the plugin.
+
+Basic usage
+-----------
+
+The default behaviour of the plugin is to first resolve the entire dependency tree, then delete the contents from the local repository, and then re-resolve the dependencies from the remote repository.
+
+```shell
mvn dependency:purge-local-repository
-+---+
+```
-* Transitive dependency resolution
+Transitive dependency resolution
+--------------------------------
- By default, the plugin operates on all transitive dependencies. This means that
- the plugin may download certain missing dependencies to gather the full
- dependency tree information before beginning the purge process.
+By default, the plugin operates on all transitive dependencies. This means that the plugin may download certain missing dependencies to gather the full dependency tree information before beginning the purge process.
- To avoid this pre-download step, the plugin can be configured to operate only
- on the direct dependencies of the project using the "actTransitively" parameter.
+To avoid this pre-download step, the plugin can be configured to operate only on the direct dependencies of the project using the "actTransitively" parameter.
-+---+
+```shell
mvn dependency:purge-local-repository -DactTransitively=false
-+---+
+```
-* Dependency includes/excludes
+Dependency includes/excludes
+----------------------------
- Specific dependencies from the current project dependency tree
- can be included or excluded from the purging and re-resolution
- process using the "includes" or "excludes" parameters. By default,
- all project dependencies are purged. The "includes" option changes
- this behaviour to only purge the included artifacts. The "excludes"
- option can be used to prevent purging/refreshing of certain dependencies.
+Specific dependencies from the current project dependency tree can be included or excluded from the purging and re-resolution process using the "includes" or "excludes" parameters. By default, all project dependencies are purged. The "includes" option changes this behaviour to only purge the included artifacts. The "excludes" option can be used to prevent purging/refreshing of certain dependencies.
-+---+
+```xml
<project>
[...]
<build>
@@ -91,49 +75,34 @@ mvn dependency:purge-local-repository -DactTransitively=false
</build>
[...]
</project>
-+---+
+```
- The includes/excludes configuration can also be passed from the CLI using the "include"
- or "exclude" parameter.
-
-+---+
+The includes/excludes configuration can also be passed from the CLI using the "include" or "exclude" parameter.
+
+```shell
mvn dependency:purge-local-repository -Dinclude=org.slf4j:slf4j-api,org.slf4j:log4j-over-slf4j
-+---+
+```
-+---+
+```shell
mvn dependency:purge-local-repository -Dinclude=org.slf4j -DresolutionFuzziness=groupId -Dverbose=true
-+---+
+```
+Manual purge
+------------
-* Manual purge
+Specific dependencies which are not part of the current project dependency tree can also be purged by using the [purge-local-repository](../purge-local-repository-mojo.html) goal and setting the "manualIncludes" or "manualInclude" parameters. Any manually included purge artifacts will be removed from the local repository and will not be re-resolved until they are needed. This can be useful for example to refresh the parent pom, an imported pom, or a Maven plugin.
- Specific dependencies which are not part of the current project dependency tree
- can also be purged by using the
- {{{../purge-local-repository-mojo.html}purge-local-repository}}
- goal and setting the "manualIncludes" or "manualInclude" parameters. Any manually
- included purge artifacts will be removed from the local repository and will
- not be re-resolved until they are needed. This can be useful for
- example to refresh the parent pom, an imported pom, or a Maven plugin.
-
- Warning, using this goal during the normal build process can be risky
- if dependencies are removed from the local repo, but are needed later in
- the build. This goal is normally safe at the end of the build, or as
- part of the build clean process.
+Warning, using this goal during the normal build process can be risky if dependencies are removed from the local repo, but are needed later in the build. This goal is normally safe at the end of the build, or as part of the build clean process.
-+---+
+```shell
mvn dependency:purge-local-repository -DmanualInclude=org.apache:apache
-+---+
+```
+
+Other purge configuration
+-------------------------
+To purge all the dependencies of a given groupId, use the `resolutionFuzziness` configuration parameter.
-* Other purge configuration
-
- To purge all the dependencies of a given groupId, use the <<<resolutionFuzziness>>>
- configuration parameter.
+If neither `includes` nor `excludes` are specified, all the dependencies of the current project are purged.
- If neither <<<includes>>> nor <<<excludes>>> are specified, all the dependencies
- of the current project are purged.
-
- You can see the complete mojo documentation in
- {{{../purge-local-repository-mojo.html}dependency:purge-local-repository}}.
-
-
+You can see the complete mojo documentation in [dependency:purge-local-repository](../purge-local-repository-mojo.html).
diff --git a/src/site/markdown/examples/render-dependencies.md.vm b/src/site/markdown/examples/render-dependencies.md.vm
index 9e2aaae6..4b5b7df8 100644
--- a/src/site/markdown/examples/render-dependencies.md.vm
+++ b/src/site/markdown/examples/render-dependencies.md.vm
@@ -1,36 +1,27 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
- ------
- Render a Velocity template
- ------
- Allan Ramirez
- Brian Fox
- Stephen Connolly
- ------
- 2025-09-17
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
-Render a Velocity template
+http://www.apache.org/licenses/LICENSE-2.0
- You can use <<<dependency:render-depedencies>>> mojo to a render a velocity template,
- with the <<artifacts>> (dependencies) as context:
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
-+---+
+# Render a Velocity template
+
+You can use `dependency:render-depedencies` mojo to a render a velocity template, with the **artifacts** (dependencies) as context:
+
+```xml
<project>
[...]
<build>
@@ -69,9 +60,8 @@ deps:
</build>
[...]
</project>
-+---+
+```
- Then after executing <<<mvn process-resources>>>, the template will be rendered.
- By default it is printed in the console but you can set <<outputFile>> to store it somewhere.
+Then after executing `mvn process-resources`, the template will be rendered. By default it is printed in the console but you can set **outputFile** to store it somewhere.
- The resolution uses exactly the same mechanism than for <<dependency:build-classpath>> mojo.
+The resolution uses exactly the same mechanism than for **dependency:build-classpath** mojo.
diff --git a/src/site/markdown/examples/tree-mojo.md b/src/site/markdown/examples/tree-mojo.md
index 2e3f847f..1b66a379 100644
--- a/src/site/markdown/examples/tree-mojo.md
+++ b/src/site/markdown/examples/tree-mojo.md
@@ -1,94 +1,67 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
- ------
- Dependency Tree Output Formats
- ------
- Tayebwa Noah
- ------
- 2025-06-04
- ------
-
-Dependency Tree Output Formats
-
- The <<<dependency:tree>>> goal of the Maven Dependency Plugin generates a representation
- of a project's dependency tree. The <<<outputType>>> parameter allows you to specify
- the output format, which can be written to a file using the <<<outputFile>>> parameter
- or printed to the console. Supported formats are <<<json>>>, <<<dot>>>, <<<graphml>>>,
- and <<<tgf>>>. This section describes each format, its structure, and example usage.
-
-* Usage
-
- To <<generate>> the dependency tree in a specific format, use the following command:
-
-+---+
-mvn dependency:tree -DoutputType=<format> -DoutputFile=<filename>
-+---+
-
- * <<<format>>>: One of <<<json>>>, <<<dot>>>, <<<graphml>>>, or <<<tgf>>>. If omitted,
- the default is a text-based tree printed to the console.
-
- * <<<filename>>>: The file to write the output to (e.g., <<<dependency-tree.json>>>).
- If omitted, the output is printed to the console.
-
- Example:
-
-+---+
-mvn dependency:tree -DoutputType=json -DoutputFile=dependency-tree.json
-+---+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- <<Note>>: Ensure you are using Maven Dependency Plugin version 3.7.0 or later
- (latest is 3.8.1 as of June 2025) to access these output formats.
+http://www.apache.org/licenses/LICENSE-2.0
-* Output Formats
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
-{JSON (outputType=json)}
+# Dependency Tree Output Formats
- <<Description>>: The JSON format represents the dependency tree as a hierarchical JSON
- object. The root node describes the project's artifact, and its dependencies are listed
- in a <<<children>>> array, with nested dependencies recursively included.
+The `dependency:tree` goal of the Maven Dependency Plugin generates a representation of a project's dependency tree. The `outputType` parameter allows you to specify the output format, which can be written to a file using the `outputFile` parameter or printed to the console. Supported formats are `json`, `dot`, `graphml`, and `tgf`. This section describes each format, its structure, and example usage.
- <<Structure>>:
+## Usage
- * <<Root Node>>:
+To **generate** the dependency tree in a specific format, use the following command:
- * <<<groupId>>>: The group ID of the project or dependency (e.g., <<<org.apache.maven.extensions>>>).
+```shell
+mvn dependency:tree -DoutputType=<format> -DoutputFile=<filename>
+```
- * <<<artifactId>>>: The artifact ID (e.g., <<<maven-build-cache-extension>>>).
+- `format`: One of `json`, `dot`, `graphml`, or `tgf`. If omitted, the default is a text-based tree printed to the console.
+- `filename`: The file to write the output to (e.g., `dependency-tree.json`). If omitted, the output is printed to the console.
- * <<<version>>>: The version (e.g., <<<1.2.1-SNAPSHOT>>>).
+ Example:
- * <<<type>>>: The artifact type (e.g., <<<jar>>>).
+ ```shell
+ mvn dependency:tree -DoutputType=json -DoutputFile=dependency-tree.json
+ ```
- * <<<scope>>>: The dependency scope (e.g., <<<compile>>>, <<<test>>>, or empty for the project itself).
+ **Note**: Ensure you are using Maven Dependency Plugin version 3.7.0 or later (latest is 3.8.1 as of June 2025) to access these output formats.
- * <<<classifier>>>: The classifier, if any (e.g., empty string if none).
+## Output Formats
- * <<<optional>>>: Whether the dependency is optional (<<<true>>> or <<<false>>>).
+# <a id="JSON_.28outputType.3Djson.29"></a>JSON (outputType\=json)
- * <<<children>>>: An array of dependency objects with the same structure, representing transitive dependencies.
+**Description**: The JSON format represents the dependency tree as a hierarchical JSON object. The root node describes the project's artifact, and its dependencies are listed in a `children` array, with nested dependencies recursively included.
- * <<Nested Dependencies>>: Each dependency in the <<<children>>> array follows the same
- structure, allowing for recursive representation of the dependency tree.
+**Structure**:
+- **Root Node**:
+ - `groupId`: The group ID of the project or dependency (e.g., `org.apache.maven.extensions`).
+ - `artifactId`: The artifact ID (e.g., `maven-build-cache-extension`).
+ - `version`: The version (e.g., `1.2.1-SNAPSHOT`).
+ - `type`: The artifact type (e.g., `jar`).
+ - `scope`: The dependency scope (e.g., `compile`, `test`, or empty for the project itself).
+ - `classifier`: The classifier, if any (e.g., empty string if none).
+ - `optional`: Whether the dependency is optional (`true` or `false`).
+ - `children`: An array of dependency objects with the same structure, representing transitive dependencies.
+- **Nested Dependencies**: Each dependency in the `children` array follows the same structure, allowing for recursive representation of the dependency tree.
- <<Example>>:
+**Example**:
-+---+
+```unknown
{
"groupId": "org.apache.maven.extensions",
"artifactId": "maven-build-cache-extension",
@@ -140,81 +113,65 @@ mvn dependency:tree -DoutputType=json -DoutputFile=dependency-tree.json
}
]
}
-+---+
+```
- <<Usage Example>>:
+**Usage Example**:
-+---+
+```shell
mvn dependency:tree -DoutputType=json -DoutputFile=dependency-tree.json
-+---+
-
- <<Use Case>>: Parse the JSON output programmatically for dependency analysis or integration
- with other tools.
+```
-{DOT (outputType=dot)}
+**Use Case**: Parse the JSON output programmatically for dependency analysis or integration with other tools.
- <<Description>>: The DOT format is a plain-text graph description language used by Graphviz.
- It represents the dependency tree as a directed graph (<<<digraph>>>), with nodes for
- artifacts and directed edges for dependencies, labeled with their scope (e.g., <<<compile>>>).
+# <a id="DOT_.28outputType.3Ddot.29"></a>DOT (outputType\=dot)
- <<Structure>>:
+**Description**: The DOT format is a plain-text graph description language used by Graphviz. It represents the dependency tree as a directed graph (`digraph`), with nodes for artifacts and directed edges for dependencies, labeled with their scope (e.g., `compile`).
- * <<Graph Declaration>>: Starts with <<<digraph "<groupId>:<artifactId>:<type>:<version>:">>>.
+**Structure**:
- * <<Nodes>>: Represented implicitly by their identifiers in edge definitions
- (e.g., <<<"org.apache.maven.extensions:maven-build-cache-extension:jar:1.2.1-SNAPSHOT:">>>).
+- **Graph Declaration**: Starts with `digraph "<groupId>:<artifactId>:<type>:<version>:"`.
+- **Nodes**: Represented implicitly by their identifiers in edge definitions (e.g., `"org.apache.maven.extensions:maven-build-cache-extension:jar:1.2.1-SNAPSHOT:"`).
+- **Edges**: Defined as `"source" -> "target"`, where `source` is the parent artifact and `target` is the dependency, optionally labeled with the scope.
- * <<Edges>>: Defined as <<<"source" -> "target">>>, where <<<source>>> is the parent artifact
- and <<<target>>> is the dependency, optionally labeled with the scope.
+**Example**:
- <<Example>>:
-
-+---+
+```unknown
digraph "org.apache.maven.extensions:maven-build-cache-extension:jar:1.2.1-SNAPSHOT:" {
"org.apache.maven.extensions:maven-build-cache-extension:jar:1.2.1-SNAPSHOT:" -> "net.openhft:zero-allocation-hashing:jar:0.27ea0:compile";
"org.apache.maven.extensions:maven-build-cache-extension:jar:1.2.1-SNAPSHOT:" -> "org.apache.maven.wagon:wagon-webdav-jackrabbit:jar:3.5.3:compile";
"org.apache.maven.wagon:wagon-webdav-jackrabbit:jar:3.5.3:compile" -> "org.apache.jackrabbit:jackrabbit-webdav:jar:2.14.4:compile";
"org.apache.jackrabbit:jackrabbit-webdav:jar:2.14.4:compile" -> "commons-codec:commons-codec:jar:1.10:compile";
}
-+---+
+```
- <<Usage Example>>:
+**Usage Example**:
-+---+
+```shell
mvn dependency:tree -DoutputType=dot -DoutputFile=dependency-tree.dot
-+---+
+```
- <<Visualization>>: Convert the DOT file to an image using Graphviz:
+**Visualization**: Convert the DOT file to an image using Graphviz:
-+---+
+```unknown
dot -Tpng dependency-tree.dot -o dependency-tree.png
-+---+
-
- <<Use Case>>: Visualize the dependency graph using tools like Graphviz for presentations
- or analysis.
+```
-{GraphML (outputType=graphml)}
+**Use Case**: Visualize the dependency graph using tools like Graphviz for presentations or analysis.
- <<Description>>: GraphML is an XML-based format for representing graphs, compatible with
- tools like yEd or Gephi. It represents the dependency tree as a directed graph with nodes
- for artifacts and edges for dependencies, including scope information.
+# <a id="GraphML_.28outputType.3Dgraphml.29"></a>GraphML (outputType\=graphml)
- <<Structure>>:
+**Description**: GraphML is an XML-based format for representing graphs, compatible with tools like yEd or Gephi. It represents the dependency tree as a directed graph with nodes for artifacts and edges for dependencies, including scope information.
- * <<GraphML Root>>: Contains namespace declarations and keys for node and edge graphics
- (using <<<yworks.com>>> extensions).
+**Structure**:
- * <<Graph>>: Defined with <<<edgedefault="directed">>>.
+- **GraphML Root**: Contains namespace declarations and keys for node and edge graphics (using `yworks.com` extensions).
+- **Graph**: Defined with `edgedefault="directed"`.
+- **Nodes**: Each node has an `id` (a unique number) and a `y:ShapeNode` with a `y:NodeLabel` containing the artifact coordinates (e.g., `groupId:artifactId:type:version:scope`).
+- **Edges**: Defined with `source` and `target` node IDs, with a `y:PolyLineEdge` containing a `y:EdgeLabel` for the scope (e.g., `compile`).
- * <<Nodes>>: Each node has an <<<id>>> (a unique number) and a <<<y:ShapeNode>>> with a
- <<<y:NodeLabel>>> containing the artifact coordinates (e.g., <<<groupId:artifactId:type:version:scope>>>).
+**Example**:
- * <<Edges>>: Defined with <<<source>>> and <<<target>>> node IDs, with a <<<y:PolyLineEdge>>>
- containing a <<<y:EdgeLabel>>> for the scope (e.g., <<<compile>>>).
-
- <<Example>>:
-
-+---+
+```xml
<?xml version="1.0" encoding="UTF-8"?>
<graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:y="http://www.yworks.com/xml/graphml">
<key for="node" id="d0" yfiles.type="nodegraphics"/>
@@ -228,36 +185,31 @@ dot -Tpng dependency-tree.dot -o dependency-tree.png
<edge source="1889106580" target="1817415346"><data key="d1"><y:PolyLineEdge><y:EdgeLabel>compile</y:EdgeLabel></y:PolyLineEdge></data></edge>
</graph>
</graphml>
-+---+
+```
- <<Usage Example>>:
+**Usage Example**:
-+---+
+```shell
mvn dependency:tree -DoutputType=graphml -DoutputFile=dependency-tree.graphml
-+---+
-
- <<Visualization>>: Open the GraphML file in yEd or Gephi to visualize the dependency graph.
+```
- <<Use Case>>: Analyze complex dependency structures using graph visualization tools.
+**Visualization**: Open the GraphML file in yEd or Gephi to visualize the dependency graph.
-{TGF (outputType=tgf)}
+**Use Case**: Analyze complex dependency structures using graph visualization tools.
- <<Description>>: The Trivial Graph Format (TGF) is a simple text-based format for representing
- graphs. It lists nodes followed by edges, with each node and edge described on a single line.
+# <a id="TGF_.28outputType.3Dtgf.29"></a>TGF (outputType\=tgf)
- <<Structure>>:
+**Description**: The Trivial Graph Format (TGF) is a simple text-based format for representing graphs. It lists nodes followed by edges, with each node and edge described on a single line.
- * <<Nodes Section>>: Each line contains a unique node ID (a number) followed by the artifact
- coordinates (e.g., <<<groupId:artifactId:type:version:scope>>>).
+**Structure**:
- * <<Separator>>: A line containing <<<#>>> separates nodes from edges.
+- **Nodes Section**: Each line contains a unique node ID (a number) followed by the artifact coordinates (e.g., `groupId:artifactId:type:version:scope`).
+- **Separator**: A line containing `#` separates nodes from edges.
+- **Edges Section**: Each line contains the source node ID, target node ID, and the scope (e.g., `compile`).
- * <<Edges Section>>: Each line contains the source node ID, target node ID, and the scope
- (e.g., <<<compile>>>).
+**Example**:
- <<Example>>:
-
-+---+
+```unknown
1474640235 org.apache.maven.extensions:maven-build-cache-extension:jar:1.2.1-SNAPSHOT:
788877168 net.openhft:zero-allocation-hashing:jar:0.27ea0:compile
1662807313 org.apache.maven.wagon:wagon-webdav-jackrabbit:jar:3.5.3:compile
@@ -268,28 +220,22 @@ mvn dependency:tree -DoutputType=graphml -DoutputFile=dependency-tree.graphml
1474640235 1662807313 compile
1662807313 1655562261 compile
1655562261 1894638973 compile
-+---+
+```
- <<Usage Example>>:
+**Usage Example**:
-+---+
+```shell
mvn dependency:tree -DoutputType=tgf -DoutputFile=dependency-tree.tgf
-+---+
-
- <<Visualization>>: Convert TGF to other formats (e.g., DOT) using tools like <<<graphviz>>> or
- custom scripts for visualization.
-
- <<Use Case>>: Lightweight format for simple graph processing or conversion to other graph formats.
-
-* Notes
-
- * <<Visualization Tools>>:
-
- * <<JSON>>: Parse with any JSON-compatible tool (e.g., Python's <<<json>>> module, JavaScript's <<<JSON.parse>>>).
+```
- * <<DOT>>: Use Graphviz (<<<dot>>> command) to generate PNG, SVG, or other visual formats.
+**Visualization**: Convert TGF to other formats (e.g., DOT) using tools like `graphviz` or custom scripts for visualization.
- * <<GraphML>>: Use yEd, Gephi, or other GraphML-compatible tools for visualization.
+**Use Case**: Lightweight format for simple graph processing or conversion to other graph formats.
- * <<TGF>>: Use tools supporting TGF or convert to DOT/GraphML for visualization.
+## Notes
+- **Visualization Tools**:
+ - **JSON**: Parse with any JSON-compatible tool (e.g., Python's `json` module, JavaScript's `JSON.parse`).
+ - **DOT**: Use Graphviz (`dot` command) to generate PNG, SVG, or other visual formats.
+ - **GraphML**: Use yEd, Gephi, or other GraphML-compatible tools for visualization.
+ - **TGF**: Use tools supporting TGF or convert to DOT/GraphML for visualization.
diff --git a/src/site/markdown/examples/unpacking-artifacts.md.vm b/src/site/markdown/examples/unpacking-artifacts.md.vm
index 9973ca6a..a54142eb 100644
--- a/src/site/markdown/examples/unpacking-artifacts.md.vm
+++ b/src/site/markdown/examples/unpacking-artifacts.md.vm
@@ -1,37 +1,27 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
- ------
- Unpacking specific artifacts
- ------
- Allan Ramirez
- Brian Fox
- ------
- 2006-11-01
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
-Unpacking specific artifacts
+http://www.apache.org/licenses/LICENSE-2.0
- This is pretty similar to the {{{./copying-artifacts.html}Copying Specific Artifacts}}
- example. The difference is that instead of copying the artifacts, they are unpacked.
- To unpack the copied artifacts, use the <<<dependency:unpack>>> mojo and
- configure the plugin into something like the sample below:
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
-+---+
+# Unpacking specific artifacts
+
+This is pretty similar to the [Copying Specific Artifacts](./copying-artifacts.html) example. The difference is that instead of copying the artifacts, they are unpacked. To unpack the copied artifacts, use the `dependency:unpack` mojo and configure the plugin into something like the sample below:
+
+```xml
<project>
[...]
<build>
@@ -55,7 +45,7 @@ Unpacking specific artifacts
<version>3.8.1</version>
<type>jar</type>
<overWrite>false</overWrite>
- <outputDirectory>\${project.build.directory}/alternateLocation</outputDirectory>
+ <outputDirectory>${esc.d}{project.build.directory}/alternateLocation</outputDirectory>
<destFileName>optional-new-name.jar</destFileName>
<includes>**/*.class,**/*.xml</includes>
<excludes>**/*test.class</excludes>
@@ -63,7 +53,7 @@ Unpacking specific artifacts
</artifactItems>
<includes>**/*.java</includes>
<excludes>**/*.properties</excludes>
- <outputDirectory>\${project.build.directory}/wars</outputDirectory>
+ <outputDirectory>${esc.d}{project.build.directory}/wars</outputDirectory>
<overWriteReleases>false</overWriteReleases>
<overWriteSnapshots>true</overWriteSnapshots>
</configuration>
@@ -74,22 +64,21 @@ Unpacking specific artifacts
</build>
[...]
</project>
-+---+
+```
- And after invoking <<<mvn package>>>, the artifacts are unpacked. Because checking the existence of an unpacked archive
- is difficult to do reliably, marker files are used instead. The location of the marker files is controlled by the {{{../unpack-dependencies-mojo.html#markersDirectory}markersDirectory}} parameter.
+And after invoking `mvn package`, the artifacts are unpacked. Because checking the existence of an unpacked archive is difficult to do reliably, marker files are used instead. The location of the marker files is controlled by the [markersDirectory](../unpack-dependencies-mojo.html#markersDirectory) parameter.
-{Unpacking from the command line}:
+# <a id="Unpacking_from_the_command_line"></a>Unpacking from the command line:
- If you intend to configure this mojo for execution on the command line using:
+If you intend to configure this mojo for execution on the command line using:
-+---+
+```shell
mvn dependency:unpack
-+---+
+```
+
+you must not put the configuration inside the _executions_ tag. Your configuration should look like this:
- you must not put the configuration inside the <executions> tag. Your configuration should look like this:
-
-+---+
+```xml
<project>
[...]
<build>
@@ -120,4 +109,4 @@ mvn dependency:unpack
</build>
[...]
</project>
-+---+
+```
diff --git a/src/site/markdown/examples/unpacking-filemapper.md.vm b/src/site/markdown/examples/unpacking-filemapper.md.vm
index 4af65714..5a2b4688 100644
--- a/src/site/markdown/examples/unpacking-filemapper.md.vm
+++ b/src/site/markdown/examples/unpacking-filemapper.md.vm
@@ -1,34 +1,27 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ------
- Rewriting target path and file name
- ------
- Markus KARG
- ------
- 2018-09-24
- ------
+http://www.apache.org/licenses/LICENSE-2.0
-Rewriting target path and file name
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
- When unpacking files, it is possible to rewrite each unpacked file's target path and file name within the target folder.
- This is useful e. g. to add or remove prefixes (like cutting away top level folders etc.):
+# Rewriting target path and file name
-+---+
+When unpacking files, it is possible to rewrite each unpacked file's target path and file name within the target folder. This is useful e. g. to add or remove prefixes (like cutting away top level folders etc.):
+
+```xml
<project>
[...]
<build>
@@ -67,45 +60,39 @@ Rewriting target path and file name
</build>
[...]
</project>
-+---+
+```
- The above example effectively cuts away the prefix <<<x.y/z/>>> of each unpacked file's path, using a regular
- expression and a replacement expression. Two tricks need to be used here: First, the regular expression uses <<<\Q>>>
- and <<<\E>>> to demarcate pattern quoting, as the dot (<<<.>>>) is special character in a reqular expression. Second,
- due to a restriction of Maven's POM syntax, the replacement cannot be empty (this would skip the file). Instead a
- dot-slash (<<<./>>>) replacement is used, which is effectively a no-op for paths segments.
+The above example effectively cuts away the prefix `x.y/z/` of each unpacked file's path, using a regular expression and a replacement expression. Two tricks need to be used here: First, the regular expression uses `\Q` and `\E` to demarcate pattern quoting, as the dot (`.`) is special character in a reqular expression. Second, due to a restriction of Maven's POM syntax, the replacement cannot be empty (this would skip the file). Instead a dot-slash (`./`) replacement is used, which is e [...]
- Any Plexus File Mapper (i. e. implementation of the interface
- <<<org.codehaus.plexus.components.io.filemappers.FileMapper>>>) can be used, but there are three particularly useful.
+Any Plexus File Mapper (i. e. implementation of the interface `org.codehaus.plexus.components.io.filemappers.FileMapper`) can be used, but there are three particularly useful.
- The Regular Expression Mapper is useful to modify or cut away prefixes or suffixes, or to rewrite file extensions:
+The Regular Expression Mapper is useful to modify or cut away prefixes or suffixes, or to rewrite file extensions:
-+---+
+```unknown
[...]
<org.codehaus.plexus.components.io.filemappers.RegExpFileMapper>
<pattern>[...]</pattern>
<replacement>[...]</replacement>
</org.codehaus.plexus.components.io.filemappers.RegExpFileMapper>
[...]
-+---+
+```
- The Prefix File Mapper is useful to add prefixes:
+The Prefix File Mapper is useful to add prefixes:
-+---+
+```unknown
[...]
<org.codehaus.plexus.components.io.filemappers.PrefixFileMapper>
<prefix>[...]</prefix>
</org.codehaus.plexus.components.io.filemappers.PrefixFileMapper>
[...]
-+---+
+```
- The Flatten File Mapper removes the path completey, effectively putting all files in the same folder:
+The Flatten File Mapper removes the path completey, effectively putting all files in the same folder:
-+---+
+```unknown
[...]
<org.codehaus.plexus.components.io.filemappers.FlattenFileMapper/>
[...]
-+---+
+```
- When multiple file mappers are given, the list gets executed from top to bottom. This might improve readability of
- the overal rewriting action compared to using a singular (typically complex) regular expression.
+When multiple file mappers are given, the list gets executed from top to bottom. This might improve readability of the overal rewriting action compared to using a singular (typically complex) regular expression.
diff --git a/src/site/markdown/examples/unpacking-project-dependencies.md.vm b/src/site/markdown/examples/unpacking-project-dependencies.md.vm
index 1035520b..a3f5f2f6 100644
--- a/src/site/markdown/examples/unpacking-project-dependencies.md.vm
+++ b/src/site/markdown/examples/unpacking-project-dependencies.md.vm
@@ -1,38 +1,27 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
- ------
- Unpacking project dependencies
- ------
- Allan Ramirez
- Brian Fox
- ------
- 2006-11-01
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
-Unpacking project dependencies
+http://www.apache.org/licenses/LICENSE-2.0
- This is pretty similar to the {{{./copying-project-dependencies.html}Copying direct dependencies}}
- example. The difference is that the direct dependencies are unpacked,
- including the transitive dependencies. To unpack the artifacts, use the
- <<<dependency:unpack-dependencies>>> mojo and configure the dependency plugin
- to something like the sample below:
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
-+---+
+# Unpacking project dependencies
+
+This is pretty similar to the [Copying direct dependencies](./copying-project-dependencies.html) example. The difference is that the direct dependencies are unpacked, including the transitive dependencies. To unpack the artifacts, use the `dependency:unpack-dependencies` mojo and configure the dependency plugin to something like the sample below:
+
+```xml
<project>
[...]
<build>
@@ -51,7 +40,7 @@ Unpacking project dependencies
<configuration>
<includes>**/*.class</includes>
<excludes>**/*.properties</excludes>
- <outputDirectory>\${project.build.directory}/alternateLocation</outputDirectory>
+ <outputDirectory>${esc.d}{project.build.directory}/alternateLocation</outputDirectory>
<overWriteReleases>false</overWriteReleases>
<overWriteSnapshots>true</overWriteSnapshots>
</configuration>
@@ -62,4 +51,4 @@ Unpacking project dependencies
</build>
[...]
</project>
-+---+
+```
diff --git a/src/site/markdown/examples/using-dependencies-sources.md.vm b/src/site/markdown/examples/using-dependencies-sources.md.vm
index 97226e46..9e15b5f0 100644
--- a/src/site/markdown/examples/using-dependencies-sources.md.vm
+++ b/src/site/markdown/examples/using-dependencies-sources.md.vm
@@ -1,40 +1,29 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
- ------
- Unpacking project dependencies
- ------
- Carlos Sanchez
- ------
- 2007-10-01
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
-Using project dependencies' sources
+http://www.apache.org/licenses/LICENSE-2.0
- This is pretty similar to the {{{./copying-project-dependencies.html}Copying project dependencies}}
- or {{{./unpacking-project-dependencies.html}Unpacking project dependencies}}
- examples.
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
- Instead of using the project dependencies it uses their sources. Use the goal
- <<<copy-dependencies>>> to just copy the sources jars to a directory or
- <<<unpack-dependencies>>> to extract them.
- See the sample below:
+# Using project dependencies' sources
-+---+
+This is pretty similar to the [Copying project dependencies](./copying-project-dependencies.html) or [Unpacking project dependencies](./unpacking-project-dependencies.html) examples.
+
+Instead of using the project dependencies it uses their sources. Use the goal `copy-dependencies` to just copy the sources jars to a directory or `unpack-dependencies` to extract them. See the sample below:
+
+```xml
<project>
[...]
<build>
@@ -54,7 +43,7 @@ Using project dependencies' sources
<configuration>
<classifier>sources</classifier>
<failOnMissingClassifierArtifact>false</failOnMissingClassifierArtifact>
- <outputDirectory>\${project.build.directory}/sources</outputDirectory>
+ <outputDirectory>${esc.d}{project.build.directory}/sources</outputDirectory>
</configuration>
</execution>
</executions>
@@ -63,4 +52,4 @@ Using project dependencies' sources
</build>
[...]
</project>
-+---+
+```
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 9a5db684..6fe07950 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -1,179 +1,84 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
- ------
- Introduction
- ------
- Allan Ramirez
- Brian Fox
- ------
- 2014-08-07
- ------
-
-${project.name}
-
- The dependency plugin provides the capability to manipulate artifacts. It
- can copy and/or unpack artifacts from local or remote repositories to a
- specified location.
-
-* Goals Overview
-
- The Dependency plugin has several goals:
-
- *{{{./add-mojo.html}dependency:add}} adds a dependency to the project's <<<pom.xml>>> from the command line.
- Supports GAV shorthand, version inference from <<<\<dependencyManagement\>>>>, BOM imports, profile targeting, and more.
- See {{{./examples/managing-dependencies.html}Managing Dependencies}}.
-
- *{{{./analyze-mojo.html}dependency:analyze}} analyzes the dependencies of this project and determines which are: used
- and declared; used and undeclared; unused and declared.
-
- *{{{./analyze-dep-mgt-mojo.html}dependency:analyze-dep-mgt}} analyzes the project's dependencies and lists mismatches
- between resolved dependencies and those listed in your dependencyManagement section.
-
- *{{{./analyze-exclusions-mojo.html}dependency:analyze-exclusions}} analyzes the exclusions on dependencies and checks if the artifact actually brings in the given dependency.
-
- *{{{./analyze-only-mojo.html}dependency:analyze-only}} is the same as analyze, but is meant to be bound in a pom. It
- does not fork the build and execute test-compile.
-
- *{{{./analyze-report-mojo.html}dependency:analyze-report}} analyzes the dependencies of this project and produces a report
- that summarises which are: used and declared; used and undeclared; unused and declared.
-
- *{{{./analyze-duplicate-mojo.html}dependency:analyze-duplicate}} analyzes the <<<\<dependencies/\>>>> and <<<\<dependencyManagement/\>>>>
- tags in the pom.xml and determines the duplicate declared dependencies.
-
- *{{{./build-classpath-mojo.html}dependency:build-classpath}} tells
- Maven to output the path of the dependencies from the local repository in a classpath format to be used in java -cp.
- The classpath file may also be attached and installed/deployed along with the main artifact.
-
- *{{{./collect-mojo.html}dependency:collect}} collects the project dependencies from the repository.
- It lists the groupId:artifactId:version information by downloading the pom files without downloading the actual
- artifacts such as jar files.
-
- *{{{./copy-mojo.html}dependency:copy}} takes a list of artifacts defined in the plugin configuration section and
- copies them to a specified location, renaming them or stripping the version if desired. This goal can resolve
- the artifacts from remote repositories if they don't exist in either the local repository or the reactor.
-
- *{{{./copy-dependencies-mojo.html}dependency:copy-dependencies}} takes the list of project direct dependencies and
- optionally transitive dependencies and copies them to a specified location, stripping the version if desired.
- This goal can also be run from the command line.
-
- *{{{./display-ancestors-mojo.html}dependency:display-ancestors}} displays all ancestor POMs of the project.
- This may be useful in a continuous integration system where you want to know all parent poms of the project.
- This goal can also be run from the command line.
-
- *{{{./get-mojo.html}dependency:get}} resolves a single artifact, eventually transitively, from a specified remote repository.
-
- *{{{./go-offline-mojo.html}dependency:go-offline}} tells Maven to resolve everything this project is dependent on
- (dependencies, plugins, reports) in preparation for going offline.
-
- *{{{./list-mojo.html}dependency:list}} alias for resolve that lists the dependencies for this project.
-
- *{{{./list-classes-mojo.html}dependency:list-classes}} displays the fully package-qualified names of all classes found in a specified artifact.
-
- *{{{./list-repositories-mojo.html}dependency:list-repositories}} collects all project dependencies and then lists the repositories
- used by the build and by the transitive dependencies.
-
- *{{{./properties-mojo.html}dependency:properties}} sets a property for each project dependency containing the
- artifact on the file system.
-
- *{{{./purge-local-repository-mojo.html}dependency:purge-local-repository}} tells Maven to clear dependency artifact
- files out of the local repository, and optionally re-resolve them.
-
- *{{{./remove-mojo.html}dependency:remove}} removes a dependency from the project's <<<pom.xml>>> from the command line.
- Supports <<<\<dependencyManagement\>>>>, BOM imports, profile targeting, and child module safety checks.
- See {{{./examples/managing-dependencies.html}Managing Dependencies}}.
-
- *{{{./resolve-mojo.html}dependency:resolve}} tells Maven to resolve all dependencies and displays the version. <<JAVA 9 NOTE:>> <will display the
- module name when running with Java 9.>
-
- *{{{./resolve-plugins-mojo.html}dependency:resolve-plugins}} tells Maven to resolve plugins and their dependencies.
-
- *{{{./resolve-sources-mojo.html}dependency:resolve-sources}} tells Maven to resolve all dependencies and their source attachments,
- and displays the version.
-
- *{{{./sources-mojo.html}dependency:sources}} has been deprecated for removal in favor of {{{./resolve-sources-mojo.html}dependency:resolve-sources}}.
-
- *{{{./tree-mojo.html}dependency:tree}} displays the dependency tree for this project.
-
- *{{{./unpack-mojo.html}dependency:unpack}} like copy but unpacks.
-
- *{{{./unpack-dependencies-mojo.html}dependency:unpack-dependencies}} like
- copy-dependencies but unpacks.
-
- *{{{./render-dependencies-mojo.html}dependency:render-dependencies}} like
- build-classpath but with a custom Velocity template.
-
- []
-
-* Usage
-
- General instructions on how to use the Dependency Plugin can be found on the {{{./usage.html}usage page}}. Some more
- specific use cases are described in the following examples.
-
- If you have questions regarding the plugin's usage, please have a look at the {{{./faq.html}FAQ}} and feel
- free to contact the {{{./mailing-lists.html}user mailing list}}. The posts to the mailing list are archived and could
- already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching
- the {{{./mailing-lists.html}mail archive}}.
-
- If you think the plugin is missing a feature or has a defect, you can file a feature request or bug report in the
- {{{./issue-management.html}issue tracker}}. When creating a new issue, please provide a comprehensive description of your
- concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason,
- entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated.
- Of course, patches are welcome, too. Contributors can check out the project from our
- {{{./scm.html}source repository}} and will find supplementary information in the
- {{{https://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}.
-
-* Examples
-
- The following examples show how to use the dependency plugin in more advanced use-cases:
-
- * {{{./examples/copying-artifacts.html}Copying Specific Artifacts}}
-
- * {{{./examples/copying-project-dependencies.html}Copying Project Dependencies}}
-
- * {{{./examples/unpacking-artifacts.html}Unpacking Specific Artifacts}}
-
- * {{{./examples/unpacking-project-dependencies.html}Unpacking the Project Dependencies}}
-
- * {{{./examples/unpacking-filemapper.html}Rewriting target path and file name}}
-
- * {{{./examples/using-dependencies-sources.html}Using Project Dependencies' Sources}}
-
- * {{{./examples/failing-the-build-on-dependency-analysis-warnings.html}Failing the Build on Dependency Analysis Warnings}}
-
- * {{{./examples/exclude-dependencies-from-dependency-analysis.html}Exclude Dependencies from Dependency Analysis}}
-
- * {{{./examples/filtering-the-dependency-tree.html}Filtering the Dependency Tree}}
-
- * {{{./examples/managing-dependencies.html}Managing Dependencies}}
-
- * {{{./examples/purging-local-repository.html}Purging the local repository}}
-
- * {{{./examples/tree-mojo.html}Tree Mojo}}
-
- * {{{./examples/render-dependencies.html}Render Dependencies}}
-
- []
-
-* Resources
-
- Here is a link that provides more reference regarding dependencies
- (i.e. dependency management, transitive dependencies).
-
- * {{{https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html}Dependency Mechanism}}
-
- []
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Apache Maven Dependency Plugin
+The dependency plugin provides the capability to manipulate artifacts. It can copy and/or unpack artifacts from local or remote repositories to a specified location.
+
+## Goals Overview
+
+The Dependency plugin has several goals:
+
+- [dependency:add](./add-mojo.html) adds a dependency to the project's `pom.xml` from the command line. Supports GAV shorthand, version inference from `<dependencyManagement>`, BOM imports, profile targeting, and more. See [Managing Dependencies](./examples/managing-dependencies.html).
+- [dependency:analyze](./analyze-mojo.html) analyzes the dependencies of this project and determines which are: used and declared; used and undeclared; unused and declared.
+- [dependency:analyze-dep-mgt](./analyze-dep-mgt-mojo.html) analyzes the project's dependencies and lists mismatches between resolved dependencies and those listed in your dependencyManagement section.
+- [dependency:analyze-exclusions](./analyze-exclusions-mojo.html) analyzes the exclusions on dependencies and checks if the artifact actually brings in the given dependency.
+- [dependency:analyze-only](./analyze-only-mojo.html) is the same as analyze, but is meant to be bound in a pom. It does not fork the build and execute test-compile.
+- [dependency:analyze-report](./analyze-report-mojo.html) analyzes the dependencies of this project and produces a report that summarises which are: used and declared; used and undeclared; unused and declared.
+- [dependency:analyze-duplicate](./analyze-duplicate-mojo.html) analyzes the `<dependencies/>` and `<dependencyManagement/>` tags in the pom.xml and determines the duplicate declared dependencies.
+- [dependency:build-classpath](./build-classpath-mojo.html) tells Maven to output the path of the dependencies from the local repository in a classpath format to be used in java -cp. The classpath file may also be attached and installed/deployed along with the main artifact.
+- [dependency:collect](./collect-mojo.html) collects the project dependencies from the repository. It lists the groupId:artifactId:version information by downloading the pom files without downloading the actual artifacts such as jar files.
+- [dependency:copy](./copy-mojo.html) takes a list of artifacts defined in the plugin configuration section and copies them to a specified location, renaming them or stripping the version if desired. This goal can resolve the artifacts from remote repositories if they don't exist in either the local repository or the reactor.
+- [dependency:copy-dependencies](./copy-dependencies-mojo.html) takes the list of project direct dependencies and optionally transitive dependencies and copies them to a specified location, stripping the version if desired. This goal can also be run from the command line.
+- [dependency:display-ancestors](./display-ancestors-mojo.html) displays all ancestor POMs of the project. This may be useful in a continuous integration system where you want to know all parent poms of the project. This goal can also be run from the command line.
+- [dependency:get](./get-mojo.html) resolves a single artifact, eventually transitively, from a specified remote repository.
+- [dependency:go-offline](./go-offline-mojo.html) tells Maven to resolve everything this project is dependent on (dependencies, plugins, reports) in preparation for going offline.
+- [dependency:list](./list-mojo.html) alias for resolve that lists the dependencies for this project.
+- [dependency:list-classes](./list-classes-mojo.html) displays the fully package-qualified names of all classes found in a specified artifact.
+- [dependency:list-repositories](./list-repositories-mojo.html) collects all project dependencies and then lists the repositories used by the build and by the transitive dependencies.
+- [dependency:properties](./properties-mojo.html) sets a property for each project dependency containing the artifact on the file system.
+- [dependency:purge-local-repository](./purge-local-repository-mojo.html) tells Maven to clear dependency artifact files out of the local repository, and optionally re-resolve them.
+- [dependency:remove](./remove-mojo.html) removes a dependency from the project's `pom.xml` from the command line. Supports `<dependencyManagement>`, BOM imports, profile targeting, and child module safety checks. See [Managing Dependencies](./examples/managing-dependencies.html).
+- [dependency:resolve](./resolve-mojo.html) tells Maven to resolve all dependencies and displays the version. **JAVA 9 NOTE:** _will display the module name when running with Java 9._
+- [dependency:resolve-plugins](./resolve-plugins-mojo.html) tells Maven to resolve plugins and their dependencies.
+- [dependency:resolve-sources](./resolve-sources-mojo.html) tells Maven to resolve all dependencies and their source attachments, and displays the version.
+- [dependency:sources](./sources-mojo.html) has been deprecated for removal in favor of [dependency:resolve-sources](./resolve-sources-mojo.html).
+- [dependency:tree](./tree-mojo.html) displays the dependency tree for this project.
+- [dependency:unpack](./unpack-mojo.html) like copy but unpacks.
+- [dependency:unpack-dependencies](./unpack-dependencies-mojo.html) like copy-dependencies but unpacks.
+- [dependency:render-dependencies](./render-dependencies-mojo.html) like build-classpath but with a custom Velocity template.
+## Usage
+
+General instructions on how to use the Dependency Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the following examples.
+
+If you have questions regarding the plugin's usage, please have a look at the [FAQ](./faq.html) and feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html).
+
+If you think the plugin is missing a feature or has a defect, you can file a feature request or bug report in the [issue tracker](./issue-management.html). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcome [...]
+
+## Examples
+
+The following examples show how to use the dependency plugin in more advanced use-cases:
+
+- [Copying Specific Artifacts](./examples/copying-artifacts.html)
+- [Copying Project Dependencies](./examples/copying-project-dependencies.html)
+- [Unpacking Specific Artifacts](./examples/unpacking-artifacts.html)
+- [Unpacking the Project Dependencies](./examples/unpacking-project-dependencies.html)
+- [Rewriting target path and file name](./examples/unpacking-filemapper.html)
+- [Using Project Dependencies' Sources](./examples/using-dependencies-sources.html)
+- [Failing the Build on Dependency Analysis Warnings](./examples/failing-the-build-on-dependency-analysis-warnings.html)
+- [Exclude Dependencies from Dependency Analysis](./examples/exclude-dependencies-from-dependency-analysis.html)
+- [Filtering the Dependency Tree](./examples/filtering-the-dependency-tree.html)
+- [Managing Dependencies](./examples/managing-dependencies.html)
+- [Purging the local repository](./examples/purging-local-repository.html)
+- [Tree Mojo](./examples/tree-mojo.html)
+- [Render Dependencies](./examples/render-dependencies.html)
+## Resources
+
+Here is a link that provides more reference regarding dependencies (i.e. dependency management, transitive dependencies).
+
+- [Dependency Mechanism](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html)
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index 7c1ef0aa..a2fd5763 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -1,54 +1,40 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
- ------
- Usage
- ------
- Allan Ramirez
- Brian Fox
- ------
- 2010-05-01
- ------
-
-Usage
-
- Brief examples of how to use the dependency goals:
-
-%{toc|fromDepth=2}
-
-* <<<dependency:copy>>>
-
- This goal is meant to be bound to a lifecycle phase and configured in your
- <<<pom.xml>>>. It will resolve the artifact from the repository and place a copy
- in the specified location. Multiple artifacts can be defined in a single
- execution. A default output directory is specified but can be overridden for
- each ArtifactItem by setting the optional outputDirectory field. An
- optional new name can be set to rename or the version stripped while copying.
-
- The artifact version is optional. If not set, the plugin will attempt to resolve it from the
- project dependencies and then the dependencyManagement section.
-
- See the {{{#Overwrite_Rules}Overwrite Rules}} section for rules about how overwriting is handled.
-
- []
-
- Configure the plugin something like this if you intend to bind it to execute along with your build:
-
-+---+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Usage
+
+Brief examples of how to use the dependency goals:
+
+<!-- MACRO{toc|fromDepth=2} -->
+
+`dependency:copy`
+-----------------
+
+This goal is meant to be bound to a lifecycle phase and configured in your `pom.xml`. It will resolve the artifact from the repository and place a copy in the specified location. Multiple artifacts can be defined in a single execution. A default output directory is specified but can be overridden for each ArtifactItem by setting the optional outputDirectory field. An optional new name can be set to rename or the version stripped while copying.
+
+The artifact version is optional. If not set, the plugin will attempt to resolve it from the project dependencies and then the dependencyManagement section.
+
+See the [Overwrite Rules](#Overwrite_Rules) section for rules about how overwriting is handled.
+
+Configure the plugin something like this if you intend to bind it to execute along with your build:
+
+```xml
<project>
[...]
<build>
@@ -86,17 +72,17 @@ Usage
</build>
[...]
</project>
-+---+
+```
- If you intend to configure this goal for execution on the command line using:
+If you intend to configure this goal for execution on the command line using:
----
+```
mvn dependency:copy
----
+```
- you must not put the configuration inside the <executions> tag. Your configuration should look like this:
+you must not put the configuration inside the _executions_ tag. Your configuration should look like this:
-+---+
+```xml
<project>
[...]
<build>
@@ -125,63 +111,41 @@ mvn dependency:copy
</build>
[...]
</project>
-+---+
+```
- <Notes:>
+_Notes:_
- * By default, artifacts are copied into <outputDirectory> using the
- Maven artifact file name convention (that is, <artifactId-version-classifier.type>).
- Use the following rules to override the default convention:
+- By default, artifacts are copied into _outputDirectory_ using the Maven artifact file name convention (that is, _artifactId-version-classifier.type_). Use the following rules to override the default convention:
+ - Use _artifactItem.destFileName_ to override the default file name.
+ - Use _stripVersion_ to remove _version_ from default file name. This field is ignored when _artifactId.destFileName_ is set.
+ - Use _artifactItem.outputDirectory_ to override the plugin's _outputDirectory_ configuration per _artifactItem_.
- * Use <artifactItem.destFileName> to override the default file name.
+`dependency:copy-dependencies`
+------------------------------
- * Use <stripVersion> to remove <version> from default file name.
- This field is ignored when <artifactId.destFileName> is set.
+This goal can be bound to a lifecycle phase and configured in your `pom.xml`. It will resolve the dependencies (including transitive dependencies) from the repository and place a copy in the specified location.
- * Use <artifactItem.outputDirectory> to override the plugin's <outputDirectory> configuration
- per <artifactItem>.
+The artifacts can be placed in subfolders based on type. For example:
- []
+/outputDirectory
- []
+/outputDirectory/jars
-* <<<dependency:copy-dependencies>>>
+/outputDirectory/wars
- This goal can be bound to a lifecycle phase and configured in your <<<pom.xml>>>.
- It will resolve the dependencies (including transitive dependencies) from
- the repository and place a copy in the specified location.
+The artifacts can be placed in a subfolder per artifact. For example: /outputDirectory/junit-junit-3.8.1/ This feature also works with the subfolders per type. For example: /outputDirectory/jars/junit-junit-3.8.1/
- The artifacts can be placed in subfolders based on type. For example:
+Artifacts can also be resolved by specifying the classifier and optionally type. Type is only used with the classifier and defaults to java-sources. When the classifier is set, the list of dependencies is used as the base to resolve artifacts with the classifier and type. For example: `mvn dependency:copy-dependencies -Dclassifier=sources` will try to find the sources for all dependencies and copy them.
- /outputDirectory
+Also included is the ability to include or exclude by type (war, jar, etc.), scope (runtime, test, etc.), classifier (jdk14, sources, etc.), groupId, artifactId, or a combination of them.
- /outputDirectory/jars
+**Note:** You may mix includes and excludes of the same category (e.g. scope). Includes are processed before excludes.
- /outputDirectory/wars
+See the [Overwrite Rules](#Overwrite_Rules) section for rules about how overwriting is handled.
- The artifacts can be placed in a subfolder per artifact. For example:
- /outputDirectory/junit-junit-3.8.1/
- This feature also works with the subfolders per type. For example:
- /outputDirectory/jars/junit-junit-3.8.1/
+The goal can also be launched from the command line like: `mvn dependency:copy-dependencies [optional params]`
- Artifacts can also be resolved by specifying the classifier and optionally
- type. Type is only used with the classifier and defaults to java-sources.
- When the classifier is set, the list of dependencies is used as the base to
- resolve artifacts with the classifier and type. For example:
- <<<mvn dependency:copy-dependencies -Dclassifier=sources>>> will try to find
- the sources for all dependencies and copy them.
-
- Also included is the ability to include or exclude by type (war, jar, etc.), scope (runtime, test, etc.), classifier (jdk14, sources, etc.), groupId, artifactId, or a combination of them.
-
- <<Note:>> You may mix includes and excludes of the same category (e.g. scope). Includes are processed before excludes.
-
- See the {{{#Overwrite_Rules}Overwrite Rules}} section for rules about how overwriting is handled.
-
-
- The goal can also be launched from the command line like:
- <<<mvn dependency:copy-dependencies [optional params]>>>
-
-+---+
+```xml
<project>
[...]
<build>
@@ -207,28 +171,22 @@ mvn dependency:copy
</build>
[...]
</project>
-+---+
-
+```
-* <<<dependency:unpack>>>
+`dependency:unpack`
+-------------------
- This goal is meant to be bound to a lifecycle and configured in your <<<pom.xml>>>.
- It will resolve the artifact from the repository and place a copy in the
- specified location. Multiple artifacts can be defined in a single execution.
- A default outputDirectory is specified but can be overridden for each
- ArtifactItem by setting the optional outputDirectory field.
+This goal is meant to be bound to a lifecycle and configured in your `pom.xml`. It will resolve the artifact from the repository and place a copy in the specified location. Multiple artifacts can be defined in a single execution. A default outputDirectory is specified but can be overridden for each ArtifactItem by setting the optional outputDirectory field.
- A single artifact can be unpacked multiple times if different include/exclude parameters
- are defined for each artifact item.
+A single artifact can be unpacked multiple times if different include/exclude parameters are defined for each artifact item.
- See the {{{#Overwrite_Rules}Overwrite Rules}} section for rules about how overwriting is handled.
+See the [Overwrite Rules](#Overwrite_Rules) section for rules about how overwriting is handled.
- The artifact version is optional. If not set, the plugin will attempt to resolve it from the
- project dependencies and then the dependencyManagement section.
+The artifact version is optional. If not set, the plugin will attempt to resolve it from the project dependencies and then the dependencyManagement section.
- Configure the plugin something like this if you intend to bind it to execute along with your build:
+Configure the plugin something like this if you intend to bind it to execute along with your build:
-+---+
+```xml
<project>
[...]
<build>
@@ -254,17 +212,17 @@ mvn dependency:copy
</build>
[...]
</project>
-+---+
+```
- If you intend to configure this goal for execution on the command line using:
+If you intend to configure this goal for execution on the command line using:
----
+```
mvn dependency:unpack
----
+```
- you must not put the configuration inside the <executions> tag. Your configuration should look like this:
+you must not put the configuration inside the _executions_ tag. Your configuration should look like this:
-+---+
+```xml
<project>
[...]
<build>
@@ -294,53 +252,40 @@ mvn dependency:unpack
</build>
[...]
</project>
-+---+
-
+```
-* <<<dependency:unpack-dependencies>>>
+`dependency:unpack-dependencies`
+--------------------------------
- This goal can be bound to a lifecycle and configured in your <<<pom.xml>>>.
- It will resolve the dependencies (including transitive dependencies) from
- the repository and unpack them to the specified location.
+This goal can be bound to a lifecycle and configured in your `pom.xml`. It will resolve the dependencies (including transitive dependencies) from the repository and unpack them to the specified location.
- Unpack-dependencies includes transitive dependencies by default. To include
- only direct dependencies, set the excludeTransitive parameter to true.
+Unpack-dependencies includes transitive dependencies by default. To include only direct dependencies, set the excludeTransitive parameter to true.
- Dependencies can be included or excluded by a list of types. See
- {{{./unpack-dependencies-mojo.html}unpack-dependencies}} for details.
+Dependencies can be included or excluded by a list of types. See [unpack-dependencies](./unpack-dependencies-mojo.html) for details.
- The artifacts can be unpacked in subfolders based on type. For example:
+The artifacts can be unpacked in subfolders based on type. For example:
- /outputDirectory
+/outputDirectory
- /outputDirectory/jars
+/outputDirectory/jars
- /outputDirectory/wars
+/outputDirectory/wars
- The artifacts can be placed in a subfolder per artifact. For example:
- /outputDirectory/junit-junit-3.8.1/
- This feature also works with the subfolders per type. For example:
- /outputDirectory/jars/junit-junit-3.8.1/
+The artifacts can be placed in a subfolder per artifact. For example: /outputDirectory/junit-junit-3.8.1/ This feature also works with the subfolders per type. For example: /outputDirectory/jars/junit-junit-3.8.1/
- Artifacts can also be resolved by specifying the classifier and optionally
- type. Type is only used with the classifier and defaults to java-sources.
- When the classifier is set, the list of dependencies is used as the base to
- resolve artifacts with the classifier and type. For example:
- <<<mvn dependency:unpack-dependencies -Dclassifier=sources>>> will try to find
- the sources for all dependencies and unpack them.
+Artifacts can also be resolved by specifying the classifier and optionally type. Type is only used with the classifier and defaults to java-sources. When the classifier is set, the list of dependencies is used as the base to resolve artifacts with the classifier and type. For example: `mvn dependency:unpack-dependencies -Dclassifier=sources` will try to find the sources for all dependencies and unpack them.
- Filters can be applied to include or exclude files or filesets as necessary
+Filters can be applied to include or exclude files or filesets as necessary
- Also included is the ability to include or exclude by type (war, jar, etc.), scope (runtime, test, etc.), classifier (jdk14, sources, etc.), groupId, artifactId, or a combination of them.
+Also included is the ability to include or exclude by type (war, jar, etc.), scope (runtime, test, etc.), classifier (jdk14, sources, etc.), groupId, artifactId, or a combination of them.
- <<Note:>> You can mix includes and excludes of the same category (e.g. scope). Includes are processed before excludes.
+**Note:** You can mix includes and excludes of the same category (e.g. scope). Includes are processed before excludes.
- See the {{{#Overwrite_Rules}Overwrite Rules}} section for rules about how overwriting is handled.
+See the [Overwrite Rules](#Overwrite_Rules) section for rules about how overwriting is handled.
- The goal can also be launched from the command line like:
- <<<mvn dependency:unpack-dependencies [optional params]>>>
+The goal can also be launched from the command line like: `mvn dependency:unpack-dependencies [optional params]`
-+---+
+```xml
<project>
[...]
<build>
@@ -366,187 +311,137 @@ mvn dependency:unpack
</build>
[...]
</project>
-+---+
-
-** Overwrite Rules
-
- Artifacts are copied or unpacked using the following rules:
+```
- * If the artifact doesn't exist in the destination, then copy/unpack it.
+#[[### Overwrite Rules]]#
- Otherwise:
+Artifacts are copied or unpacked using the following rules:
- * For copy/unpack goal only: if <<<artifactItem / overWrite>>> or <<<overWrite>>> is true, then it will force an overwrite.
+- If the artifact doesn't exist in the destination, then copy/unpack it.
- * Releases check the <<<overWriteReleases>>> value (default = false). If true, then it will force an overwrite.
+ Otherwise:
- * Snapshots check the <<<overWriteSnapshots>>> value (default = false). If true, then it will force an overwrite.
+- For copy/unpack goal only: if `artifactItem / overWrite` or `overWrite` is true, then it will force an overwrite.
+- Releases check the `overWriteReleases` value (default = false). If true, then it will force an overwrite.
+- Snapshots check the `overWriteSnapshots` value (default = false). If true, then it will force an overwrite.
+- If none of the above is set to true, then it defaults to the `overWriteIfNewer` value (default = true). This value, if true, causes the plugin to only copy if the source is newer than the destination (or it doesn't exist in the destination). (for unpack, this checks the existence of the marker file, created in the `markersDirectory` path. To avoid unexpected behavior after `mvn clean`, this path should normally be contained within the `/target` hierarchy.)
- * If none of the above is set to true, then it defaults to the <<<overWriteIfNewer>>> value (default = true). This value, if true, causes
- the plugin to only copy if the source is newer than the destination (or it doesn't exist in the destination). (for unpack, this checks the existence of the marker file, created in the <<<markersDirectory>>> path.
- To avoid unexpected behavior after <<<mvn clean>>>, this path should normally be contained within the <<</target>>> hierarchy.)
+Examples:
- Examples:
+- Using the default settings (`overWriteReleases` = false, `overWriteSnapshots` = false, `overWriteIfNewer` = true), then a release or snapshot artifact will only over write the destination if the source is newer than the destination (or marker file if unpacking).
+- If `overWriteReleases` = true, then a release artifact (e.g. `foo-1.0.jar`) will always overwrite.
+- If `overWriteSnapshots` = true, then a snapshot artifact (e.g. `foo-1.0-SNAPSHOT.jar`) will always overwrite.
+- If all of the values are false, then a copy/unpack will only occur if the artifact doesn't exist in the destination (or `markersDirectory` if unpacking).
- * Using the default settings (<<<overWriteReleases>>> = false, <<<overWriteSnapshots>>> = false, <<<overWriteIfNewer>>> = true), then a release or snapshot artifact will
- only over write the destination if the source is newer than the destination (or marker file if unpacking).
+`dependency:resolve`
+--------------------
- * If <<<overWriteReleases>>> = true, then a release artifact (e.g. <<<foo-1.0.jar>>>) will always overwrite.
+Resolve is intended to be used from the command line like: `mvn dependency:resolve -Dsilent=true`
- * If <<<overWriteSnapshots>>> = true, then a snapshot artifact (e.g. <<<foo-1.0-SNAPSHOT.jar>>>) will always overwrite.
+This goal resolves all test and compile scoped dependencies and then displays the resolved versions. This ensures all dependencies are downloaded to the local repository. This is useful when troubleshooting or during intermittent remote repository failures when repeatedly building multiproject modules is undesirable and the build is failing on dependency resolution. It can also be used to quickly determine how versions are being resolved.
- * If all of the values are false, then a copy/unpack will only occur if the artifact doesn't exist in the destination (or <<<markersDirectory>>> if unpacking).
+Artifacts can also be resolved by specifying the classifier and optionally type. Type is only used with the classifier and defaults to java-sources. When the classifier is set, the list of dependencies is used as the base to resolve artifacts with the classifier and type. For example: `mvn dependency:resolve -Dclassifier=test-jar` will try to find the test-jar for all dependencies resolve them to the local repository.
+`dependency:resolve-sources`
+----------------------------
+Resolve-sources is intended to be used from the command line like: `mvn dependency:resolve-sources -Dsilent=true`
-* <<<dependency:resolve>>>
+This is the same as the resolve goal except it includes the source attachments if they exist. This is useful when you want to download source attachments to your local repository.
- Resolve is intended to be used from the command line like:
- <<<mvn dependency:resolve -Dsilent=true>>>
+You can also define the `markersDirectory` either in the `pom.xml` or settings to be a common location for all projects. This allows the system to resolve sources faster for dependencies that don't have the sources published. The plugin will store a marker file to describe if the sources were resolved or not. By placing them in a common location, multiple attempts to resolve non-existent sources will be avoided.
- This goal resolves all test and compile scoped
- dependencies and then displays the resolved versions. This
- ensures all dependencies are downloaded to the local repository. This is
- useful when troubleshooting or during intermittent remote repository
- failures when repeatedly building multiproject modules is undesirable and
- the build is failing on dependency resolution. It can also be used to quickly
- determine how versions are being resolved.
+`dependency:resolve-plugins`
+----------------------------
- Artifacts can also be resolved by specifying the classifier and optionally
- type. Type is only used with the classifier and defaults to java-sources.
- When the classifier is set, the list of dependencies is used as the base to
- resolve artifacts with the classifier and type. For example:
- <<<mvn dependency:resolve -Dclassifier=test-jar>>> will try to find the
- test-jar for all dependencies resolve them to the local repository.
+Resolve-plugins is intended to be used from the command line like: `mvn dependency:resolve-plugins -Dsilent=true -DexcludeTransitive=true`
-* <<<dependency:resolve-sources>>>
+This is the same as the resolve goal except it resolves plugins and optionally their dependencies.
- Resolve-sources is intended to be used from the command line like:
- <<<mvn dependency:resolve-sources -Dsilent=true>>>
+`dependency:go-offline`
+-----------------------
- This is the same as the resolve goal except it includes the source
- attachments if they exist. This is useful when you want to download source
- attachments to your local repository.
+This goal is exactly the same as calling `mvn dependency:resolve dependency:resolve-plugins`.
- You can also define the <<<markersDirectory>>> either in the <<<pom.xml>>> or settings
- to be a common location for all projects. This allows the system to resolve sources faster for dependencies that don't
- have the sources published. The plugin will store a marker file to describe if the sources were resolved or not. By placing
- them in a common location, multiple attempts to resolve non-existent sources will be avoided.
+`dependency:purge-local-repository`
+-----------------------------------
-* <<<dependency:resolve-plugins>>>
+This goal is meant to delete all of the dependencies for the current project (or projects, in the case of a multimodule build) from the local repository. Purges can be run with a variety of limiting parameters, including artifact exclusions, limiting to direct dependencies only, and different levels of depth for deletion. By default, deleted artifacts can be re-resolved afterwards; you can disable this by specifying `-DreResolve=false`.
- Resolve-plugins is intended to be used from the command line like:
- <<<mvn dependency:resolve-plugins -Dsilent=true -DexcludeTransitive=true>>>
+In its simplest form, the goal can be called like this:
- This is the same as the resolve goal except it resolves plugins and
- optionally their dependencies.
-
-* <<<dependency:go-offline>>>
-
- This goal is exactly the same as calling
- <<<mvn dependency:resolve dependency:resolve-plugins>>>.
-
-* <<<dependency:purge-local-repository>>>
-
- This goal is meant to delete all of the dependencies for the current project
- (or projects, in the case of a multimodule build) from the local repository.
- Purges can be run with a variety of limiting parameters, including artifact
- exclusions, limiting to direct dependencies only, and different levels of
- depth for deletion. By default, deleted artifacts can be re-resolved
- afterwards; you can disable this by specifying <<<-DreResolve=false>>>.
-
- In its simplest form, the goal can be called like this:
-
----
+```
mvn dependency:purge-local-repository
----
+```
- To add the restriction that the <<<org.apache.maven:maven-plugin-api>>>
- artifact not be deleted, we can modify the command to this:
+To add the restriction that the `org.apache.maven:maven-plugin-api` artifact not be deleted, we can modify the command to this:
----
+```
mvn dependency:purge-local-repository -Dexclude=org.apache.maven:maven-plugin-api
----
+```
- <<Note:>> The <<<exclude>>> parameter is a comma-delimited list of
- groupId:artifactId pairs. It has a corresponding List-based parameter -
- <<<excludes>>> - for convenient use inside the <<<pom.xml>>>.
+**Note:** The `exclude` parameter is a comma-delimited list of groupId:artifactId pairs. It has a corresponding List-based parameter - `excludes` - for convenient use inside the `pom.xml`.
- Another handy aspect of this goal is the ability to wipe out artifacts at
- varying depths. These depths are:
+Another handy aspect of this goal is the ability to wipe out artifacts at varying depths. These depths are:
- * <<file>> - Delete just the artifact's file.
+- **file** - Delete just the artifact's file.
+- **version** - Delete the version directory containing this artifact. Amounts to `file.getParentFile()`.
+- **artifactId** - Delete the artifactId directory containing this artifact. Amounts to `file.getParentFile().getParentFile()`.
+- **groupId** - Delete the groupId directory structure containing this artifact.
- * <<version>> - Delete the version directory containing this artifact. Amounts to
- <<<file.getParentFile()>>>.
+ At a minimum, this amounts to `file.getParentFile().getParentFile().getParentFile()`. However, if the groupId contains multiple parts, the goal will prune all groupId-part directories that contain only the files associated with this artifact. Again, note that the exception to this pruning algorithm is the lowest groupId part, which will always be pruned.
- * <<artifactId>> - Delete the artifactId directory containing this artifact.
- Amounts to <<<file.getParentFile().getParentFile()>>>.
+To prune dependency artifacts back to their associated artifactId directories (in order to verify proper artifact resolution, for example), simply use this command:
- * <<groupId>> - Delete the groupId directory structure containing this artifact.
-
- At a minimum, this amounts to <<<file.getParentFile().getParentFile().getParentFile()>>>.
- However, if the groupId contains multiple parts, the goal will prune all groupId-part
- directories that contain only the files associated with this artifact. Again, note that
- the exception to this pruning algorithm is the lowest groupId part, which will always
- be pruned.
-
- []
-
- To prune dependency artifacts back to their associated artifactId directories
- (in order to verify proper artifact resolution, for example), simply use this
- command:
-
----
+```
mvn dependency:purge-local-repository -DresolutionFuzziness=artifactId
----
-
- Finally, it's possible to bind this goal to the build lifecycle. One reason for this
- might be to clean out all dependencies when the build is initialized, to verify
- correct resolution.
+```
+Finally, it's possible to bind this goal to the build lifecycle. One reason for this might be to clean out all dependencies when the build is initialized, to verify correct resolution.
-* <<<dependency:analyze>>>
+`dependency:analyze`
+--------------------
- This goal performs byte code analysis to determine missing or unused dependencies. This goal is meant to be launched from the command line. It will fork the build and execute test-compile so there are class files to analyze.
- If you want to bind analyze in your <<<pom.xml>>>, use the <<<dependency:analyze-only>>> instead.
+This goal performs byte code analysis to determine missing or unused dependencies. This goal is meant to be launched from the command line. It will fork the build and execute test-compile so there are class files to analyze. If you want to bind analyze in your `pom.xml`, use the `dependency:analyze-only` instead.
- This goal can be executed from the command line:
+This goal can be executed from the command line:
----
+```
mvn dependency:analyze
----
+```
- Sample output:
+Sample output:
-+---+
+```unknown
[INFO] [dependency:analyze]
[WARNING] Used undeclared dependencies found:
[WARNING] classworlds:classworlds:jar:1.1-alpha-2:compile
[WARNING] org.apache.maven.shared:maven-invoker:jar:2.0.7-SNAPSHOT:test
-+---+
+```
-* <<<dependency:analyze-only>>>
+`dependency:analyze-only`
+-------------------------
- This goal performs bytecode analysis to determine missing or unused dependencies, similar to <<<dependency:analyze>>>.
+This goal performs bytecode analysis to determine missing or unused dependencies, similar to `dependency:analyze`.
- It will not fork the build with test compilation, so it should be used when you want to bind the analyze goal in your <<<pom.xml>>>.
+It will not fork the build with test compilation, so it should be used when you want to bind the analyze goal in your `pom.xml`.
-* <<<dependency:analyze-dep-mgt>>>
+`dependency:analyze-dep-mgt`
+----------------------------
- This goal looks at the dependencies after final resolution and looks for mismatches in your dependencyManagement section.
+This goal looks at the dependencies after final resolution and looks for mismatches in your dependencyManagement section.
- This goal is useful for detecting projects that override the dependencyManagement directly. Set ignoreDirect to false to detect these otherwise normal conditions.
+This goal is useful for detecting projects that override the dependencyManagement directly. Set ignoreDirect to false to detect these otherwise normal conditions.
- This goal can be executed from the command line:
+This goal can be executed from the command line:
----
+```
mvn dependency:analyze-dep-mgt
----
+```
- Sample output:
+Sample output:
-+---+
+```unknown
[INFO] Found Resolved Dependency / DependencyManagement mismatches:
[INFO] Dependency: commons-lang:commons-lang:jar
[INFO] DepMgt : 1.0
@@ -558,14 +453,14 @@ mvn dependency:analyze-dep-mgt
[INFO] DepMgt : 2.3
[INFO] Resolved: 2.4
[WARNING] Potential problems found in Dependency Management
-+---+
+```
+`dependency:analyze-report`
+---------------------------
-* <<<dependency:analyze-report>>>
+This goal is used to include a report of the dependencies in the output of the `maven-site-plugin`.
- This goal is used to include a report of the dependencies in the output of the <<<maven-site-plugin>>>.
-
-+-------+
+```xml
<reporting>
<plugins>
...
@@ -583,73 +478,66 @@ mvn dependency:analyze-dep-mgt
</plugin>
</plugins>
</reporting>
-+-------+
-
+```
-* <<<dependency:tree>>>
+`dependency:tree`
+-----------------
- This goal is used to view the dependency hierarchy of the project currently being built.
- It will output the resolved tree of dependencies that the Maven build process actually uses.
+This goal is used to view the dependency hierarchy of the project currently being built. It will output the resolved tree of dependencies that the Maven build process actually uses.
- This goal can be executed from the command line:
+This goal can be executed from the command line:
----
+```
mvn dependency:tree
----
+```
- Optionally, the <<<output>>> parameter can be specified to divert the output to a file:
+Optionally, the `output` parameter can be specified to divert the output to a file:
----
+```
mvn dependency:tree -DoutputFile=/path/to/file
----
-
- Also, the <<<outputType>>> parameter can be used to generate different formats of output. The
- following formats are currently supported:
-
- * text
-
- * {{{https://en.wikipedia.org/wiki/DOT_language}dot}}
+```
- * {{{https://en.wikipedia.org/wiki/GraphML}graphml}}
+Also, the `outputType` parameter can be used to generate different formats of output. The following formats are currently supported:
- * {{{https://en.wikipedia.org/wiki/Trivial_Graph_Format}tgf}}
+- text
+- [dot](https://en.wikipedia.org/wiki/DOT_language)
+- [graphml](https://en.wikipedia.org/wiki/GraphML)
+- [tgf](https://en.wikipedia.org/wiki/Trivial_Graph_Format)
- []
-
----
+```
mvn dependency:tree -DoutputFile=/path/to/file.graphml -DoutputType=graphml
----
-
+```
-* <<<dependency:build-classpath>>>
+`dependency:build-classpath`
+----------------------------
- This goal will output a classpath string of dependencies from the local repository to a file or log and optionally attach and deploy the file. For instance, the file would contain a classpath string like this:
+This goal will output a classpath string of dependencies from the local repository to a file or log and optionally attach and deploy the file. For instance, the file would contain a classpath string like this:
----
+```
/home/foo/.m2/repository/org/java/utils/util/util-1.0.jar:/home/foo/.m2/ ....
----
+```
- The resulting file could then be used like this:
+The resulting file could then be used like this:
----
+```
java -cp `cat resultFile` MyClass
----
+```
- In its simplest form, to output the classpath to the log, the goal can be called like this:
+In its simplest form, to output the classpath to the log, the goal can be called like this:
----
+```
mvn dependency:build-classpath
----
+```
- or to write the classpath to cp.txt:
+or to write the classpath to cp.txt:
----
+```
mvn dependency:build-classpath -Dmdep.outputFile=cp.txt
----
+```
- The goal can also be bound to a lifecycle phase with the following configuration:
+The goal can also be bound to a lifecycle phase with the following configuration:
-+---+
+```xml
<project>
[...]
<build>
@@ -675,85 +563,77 @@ mvn dependency:build-classpath -Dmdep.outputFile=cp.txt
</build>
[...]
</project>
-+---+
-
+```
-* <<<dependency:list-repositories>>>
+`dependency:list-repositories`
+------------------------------
- This goal lists all the repositories that this build depends upon. It shows repositories defined in your settings,
- poms, and declared in transitive dependency poms.
+This goal lists all the repositories that this build depends upon. It shows repositories defined in your settings, poms, and declared in transitive dependency poms.
+`dependency:get`
+----------------
-* <<<dependency:get>>>
+This goal resolves an artifact and (optionally) its dependencies from remote repositories using its Maven coordinates. The Maven Central repository are always consider during resolving.
- This goal resolves an artifact and (optionally) its dependencies from remote repositories using its Maven coordinates.
- The Maven Central repository are always consider during resolving.
-
----
+```
mvn dependency:get -DgroupId=org.apache.maven -DartifactId=maven-core -Dversion=2.2.1 -Dpackaging=jar -Dclassifier=sources
mvn dependency:get -DgroupId=org.apache.maven -DartifactId=maven-core -Dversion=2.2.1 -Dpackaging=jar -Dclassifier=sources -DremoteRepositories=https://myrepo.com/maven2
----
-
+```
-* <<<dependency:analyze-exclusions>>>
+`dependency:analyze-exclusions`
+-------------------------------
- This goal checks exclusions on dependencies and checks if the artifact actually brings in the given dependency.
- For instance, given dependency a:b:1.0 transitively includes x:y:1.0 which you do not want for some reason and exclude it.
- Later a:b:2.0 has removed the unwanted dependency and you upgrade. This goal will inform you that the exclusion is no
- longer required.
+This goal checks exclusions on dependencies and checks if the artifact actually brings in the given dependency. For instance, given dependency a:b:1.0 transitively includes x:y:1.0 which you do not want for some reason and exclude it. Later a:b:2.0 has removed the unwanted dependency and you upgrade. This goal will inform you that the exclusion is no longer required.
----
+```
mvn dependency:analyze-exclusions
----
+```
- Sample output:
+Sample output:
-+---+
+```unknown
[WARNING] The following dependencies defines unnecessary excludes
[WARNING] org.apache.maven:maven-artifact:
[WARNING] - javax.annotation:javax.annotation-api
[WARNING] - javax.activation:javax.activation-api
-+---+
+```
-* <<<dependency:add>>>
+`dependency:add`
+----------------
- This goal adds a dependency to the project's <<<pom.xml>>> directly from the command line.
- If the dependency already exists, the goal fails with a descriptive error directing you to
- remove it first. For detailed examples, see
- {{{./examples/managing-dependencies.html}Managing Dependencies}}.
+This goal adds a dependency to the project's `pom.xml` directly from the command line. If the dependency already exists, the goal fails with a descriptive error directing you to remove it first. For detailed examples, see [Managing Dependencies](./examples/managing-dependencies.html).
----
+```
mvn dependency:add -Dgav=org.apache.commons:commons-lang3:3.17.0
mvn dependency:add -Dgav=org.apache.commons:commons-lang3:3.17.0 -Dscope=test
----
+```
- Add to <<<\<dependencyManagement\>>>>:
+Add to `<dependencyManagement>`:
----
+```
mvn dependency:add -Dgav=org.apache.commons:commons-lang3:3.17.0 -Dmanaged
----
+```
- Add a BOM import:
+Add a BOM import:
----
+```
mvn dependency:add -Dgav=org.springframework.boot:spring-boot-dependencies:pom:3.2.0 -Dscope=import -Dmanaged
----
+```
- In multi-module projects, use Maven's <<<-pl>>> flag to target a specific module:
+In multi-module projects, use Maven's `-pl` flag to target a specific module:
----
+```
mvn dependency:add -Dgav=org.apache.commons:commons-lang3:3.17.0 -pl my-service
----
+```
-* <<<dependency:remove>>>
+`dependency:remove`
+-------------------
- This goal removes a dependency from the project's <<<pom.xml>>> directly from the command line.
- For detailed examples, see {{{./examples/managing-dependencies.html}Managing Dependencies}}.
+This goal removes a dependency from the project's `pom.xml` directly from the command line. For detailed examples, see [Managing Dependencies](./examples/managing-dependencies.html).
----
+```
mvn dependency:remove -Dgav=org.apache.commons:commons-lang3
mvn dependency:remove -Dgav=org.apache.commons:commons-lang3 -Dmanaged
----
+```
- When removing a managed dependency from a parent POM, the goal warns if child modules still
- reference that dependency without an explicit version.
+When removing a managed dependency from a parent POM, the goal warns if child modules still reference that dependency without an explicit version.