This is an automated email from the ASF dual-hosted git repository.
olamy pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-dependency-plugin.git
The following commit(s) were added to refs/heads/master by this push:
new 2791f66a Document dependency tree output formats (#535)
2791f66a is described below
commit 2791f66a660ca38ac7736faa3171c98f77d7a90f
Author: Tayebwa Noah <ndacyayin...@gmail.com>
AuthorDate: Fri Jun 6 00:14:50 2025 +0300
Document dependency tree output formats (#535)
* Document dependency tree output formats
* Refactor docs
---
src/site/apt/examples/tree-mojo.apt.vm | 304 +++++++++++++++++++++++++++++++++
src/site/apt/index.apt.vm | 2 +
src/site/site.xml | 1 +
3 files changed, 307 insertions(+)
diff --git a/src/site/apt/examples/tree-mojo.apt.vm
b/src/site/apt/examples/tree-mojo.apt.vm
new file mode 100644
index 00000000..5c5a6ba3
--- /dev/null
+++ b/src/site/apt/examples/tree-mojo.apt.vm
@@ -0,0 +1,304 @@
+~~ 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
++---+
+
+ <<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.
+
+* Output Formats
+
+{JSON (outputType=json)}
+
+ <<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.
+
+ <<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>>:
+
++---+
+{
+ "groupId": "org.apache.maven.extensions",
+ "artifactId": "maven-build-cache-extension",
+ "version": "1.2.1-SNAPSHOT",
+ "type": "jar",
+ "scope": "",
+ "classifier": "",
+ "optional": "false",
+ "children": [
+ {
+ "groupId": "net.openhft",
+ "artifactId": "zero-allocation-hashing",
+ "version": "0.27ea0",
+ "type": "jar",
+ "scope": "compile",
+ "classifier": "",
+ "optional": "false"
+ },
+ {
+ "groupId": "org.apache.maven.wagon",
+ "artifactId": "wagon-webdav-jackrabbit",
+ "version": "3.5.3",
+ "type": "jar",
+ "scope": "compile",
+ "classifier": "",
+ "optional": "false",
+ "children": [
+ {
+ "groupId": "org.apache.jackrabbit",
+ "artifactId": "jackrabbit-webdav",
+ "version": "2.14.4",
+ "type": "jar",
+ "scope": "compile",
+ "classifier": "",
+ "optional": "false",
+ "children": [
+ {
+ "groupId": "commons-codec",
+ "artifactId": "commons-codec",
+ "version": "1.10",
+ "type": "jar",
+ "scope": "compile",
+ "classifier": "",
+ "optional": "false"
+ }
+ ]
+ }
+ ]
+ }
+ ]
+}
++---+
+
+ <<Usage Example>>:
+
++---+
+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)}
+
+ <<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>>>).
+
+ <<Structure>>:
+
+ * <<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.
+
+ <<Example>>:
+
++---+
+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>>:
+
++---+
+mvn dependency:tree -DoutputType=dot -DoutputFile=dependency-tree.dot
++---+
+
+ <<Visualization>>: Convert the DOT file to an image using Graphviz:
+
++---+
+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)}
+
+ <<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.
+
+ <<Structure>>:
+
+ * <<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>>>).
+
+ <<Example>>:
+
++---+
+<?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"/>
+ <key for="edge" id="d1" yfiles.type="edgegraphics"/>
+ <graph id="dependencies" edgedefault="directed">
+ <node id="955994360"><data
key="d0"><y:ShapeNode><y:NodeLabel>org.apache.maven.extensions:maven-build-cache-extension:jar:1.2.1-SNAPSHOT:</y:NodeLabel></y:ShapeNode></data></node>
+ <node id="2058879732"><data
key="d0"><y:ShapeNode><y:NodeLabel>net.openhft:zero-allocation-hashing:jar:0.27ea0:compile</y:NodeLabel></y:ShapeNode></data></node>
+ <edge source="955994360" target="2058879732"><data
key="d1"><y:PolyLineEdge><y:EdgeLabel>compile</y:EdgeLabel></y:PolyLineEdge></data></edge>
+ <node id="1889106580"><data
key="d0"><y:ShapeNode><y:NodeLabel>org.apache.maven.wagon:wagon-webdav-jackrabbit:jar:3.5.3:compile</y:NodeLabel></y:ShapeNode></data></node>
+ <node id="1817415346"><data
key="d0"><y:ShapeNode><y:NodeLabel>org.apache.jackrabbit:jackrabbit-webdav:jar:2.14.4:compile</y:NodeLabel></y:ShapeNode></data></node>
+ <edge source="1889106580" target="1817415346"><data
key="d1"><y:PolyLineEdge><y:EdgeLabel>compile</y:EdgeLabel></y:PolyLineEdge></data></edge>
+ </graph>
+</graphml>
++---+
+
+ <<Usage Example>>:
+
++---+
+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.
+
+{TGF (outputType=tgf)}
+
+ <<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.
+
+ <<Structure>>:
+
+ * <<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>>>).
+
+ <<Example>>:
+
++---+
+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
+1655562261 org.apache.jackrabbit:jackrabbit-webdav:jar:2.14.4:compile
+1894638973 commons-codec:commons-codec:jar:1.10:compile
+#
+1474640235 788877168 compile
+1474640235 1662807313 compile
+1662807313 1655562261 compile
+1655562261 1894638973 compile
++---+
+
+ <<Usage Example>>:
+
++---+
+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
+
+ * <<Plugin Version>>: The <<<json>>>, <<<dot>>>, <<<graphml>>>, and
<<<tgf>>> output formats are
+ available starting with Maven Dependency Plugin version 3.7.0. Always use
the latest version
+ (3.8.1 as of June 2025) for the most stable experience.
+
+ * <<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.
+
+ * <<Contributing>>: If you encounter issues or want to improve this
documentation, contribute to
+ the Maven Dependency Plugin repository at
+
{{{https://github.com/apache/maven-dependency-plugin}https://github.com/apache/maven-dependency-plugin}}.
+ See the
+ {{{https://maven.apache.org/guides/development/guide-helping.html}guide to
helping with Maven}}.
diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm
index 34cf45ed..468888d2 100644
--- a/src/site/apt/index.apt.vm
+++ b/src/site/apt/index.apt.vm
@@ -150,6 +150,8 @@ ${project.name}
* {{{./examples/purging-local-repository.html}Purging the local repository}}
+ * {{{./examples/tree-mojo.html}Tree Mojo}}
+
[]
* Resources
diff --git a/src/site/site.xml b/src/site/site.xml
index 16a0738d..a7f5a4b3 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -42,6 +42,7 @@ under the License.
<item name="Exclude Dependencies from Dependency Analysis"
href="examples/exclude-dependencies-from-dependency-analysis.html"/>
<item name="Filtering the dependency tree"
href="examples/filtering-the-dependency-tree.html"/>
<item name="Purging local repository dependencies"
href="examples/purging-local-repository.html"/>
+ <item name="Dependency tree output formats"
href="examples/tree-mojo.html"/>
</menu>
<menu name="Resources">
<item name="Dependency Mechanism"
href="../../guides/introduction/introduction-to-dependency-mechanism.html"/>
