[MDEP-933] Document dependency tree output formats

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}}.

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

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"/>