Skip to content

Commit 2791f66

Browse files
Ndacyayisenga-droidNdacyayisenga-droid
authored
Document dependency tree output formats (#535)
* Document dependency tree output formats * Refactor docs
1 parent 64fa778 commit 2791f66

File tree

3 files changed

+307
-0
lines changed

3 files changed

+307
-0
lines changed

‎src/site/apt/examples/tree-mojo.apt.vm‎

Lines changed: 304 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,304 @@
1+
~~ Licensed to the Apache Software Foundation (ASF) under one
2+
~~ or more contributor license agreements. See the NOTICE file
3+
~~ distributed with this work for additional information
4+
~~ regarding copyright ownership. The ASF licenses this file
5+
~~ to you under the Apache License, Version 2.0 (the
6+
~~ "License"); you may not use this file except in compliance
7+
~~ with the License. You may obtain a copy of the License at
8+
~~
9+
~~ http://www.apache.org/licenses/LICENSE-2.0
10+
~~
11+
~~ Unless required by applicable law or agreed to in writing,
12+
~~ software distributed under the License is distributed on an
13+
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
~~ KIND, either express or implied. See the License for the
15+
~~ specific language governing permissions and limitations
16+
~~ under the License.
17+
18+
------
19+
Dependency Tree Output Formats
20+
------
21+
Tayebwa Noah
22+
------
23+
2025-06-04
24+
------
25+
26+
Dependency Tree Output Formats
27+
28+
The <<<dependency:tree>>> goal of the Maven Dependency Plugin generates a representation
29+
of a project's dependency tree. The <<<outputType>>> parameter allows you to specify
30+
the output format, which can be written to a file using the <<<outputFile>>> parameter
31+
or printed to the console. Supported formats are <<<json>>>, <<<dot>>>, <<<graphml>>>,
32+
and <<<tgf>>>. This section describes each format, its structure, and example usage.
33+
34+
* Usage
35+
36+
To <<generate>> the dependency tree in a specific format, use the following command:
37+
38+
+---+
39+
mvn dependency:tree -DoutputType=<format> -DoutputFile=<filename>
40+
+---+
41+
42+
* <<<format>>>: One of <<<json>>>, <<<dot>>>, <<<graphml>>>, or <<<tgf>>>. If omitted,
43+
the default is a text-based tree printed to the console.
44+
45+
* <<<filename>>>: The file to write the output to (e.g., <<<dependency-tree.json>>>).
46+
If omitted, the output is printed to the console.
47+
48+
Example:
49+
50+
+---+
51+
mvn dependency:tree -DoutputType=json -DoutputFile=dependency-tree.json
52+
+---+
53+
54+
<<Note>>: Ensure you are using Maven Dependency Plugin version 3.7.0 or later
55+
(latest is 3.8.1 as of June 2025) to access these output formats.
56+
57+
* Output Formats
58+
59+
{JSON (outputType=json)}
60+
61+
<<Description>>: The JSON format represents the dependency tree as a hierarchical JSON
62+
object. The root node describes the project's artifact, and its dependencies are listed
63+
in a <<<children>>> array, with nested dependencies recursively included.
64+
65+
<<Structure>>:
66+
67+
* <<Root Node>>:
68+
69+
* <<<groupId>>>: The group ID of the project or dependency (e.g., <<<org.apache.maven.extensions>>>).
70+
71+
* <<<artifactId>>>: The artifact ID (e.g., <<<maven-build-cache-extension>>>).
72+
73+
* <<<version>>>: The version (e.g., <<<1.2.1-SNAPSHOT>>>).
74+
75+
* <<<type>>>: The artifact type (e.g., <<<jar>>>).
76+
77+
* <<<scope>>>: The dependency scope (e.g., <<<compile>>>, <<<test>>>, or empty for the project itself).
78+
79+
* <<<classifier>>>: The classifier, if any (e.g., empty string if none).
80+
81+
* <<<optional>>>: Whether the dependency is optional (<<<true>>> or <<<false>>>).
82+
83+
* <<<children>>>: An array of dependency objects with the same structure, representing transitive dependencies.
84+
85+
* <<Nested Dependencies>>: Each dependency in the <<<children>>> array follows the same
86+
structure, allowing for recursive representation of the dependency tree.
87+
88+
89+
<<Example>>:
90+
91+
+---+
92+
{
93+
"groupId": "org.apache.maven.extensions",
94+
"artifactId": "maven-build-cache-extension",
95+
"version": "1.2.1-SNAPSHOT",
96+
"type": "jar",
97+
"scope": "",
98+
"classifier": "",
99+
"optional": "false",
100+
"children": [
101+
{
102+
"groupId": "net.openhft",
103+
"artifactId": "zero-allocation-hashing",
104+
"version": "0.27ea0",
105+
"type": "jar",
106+
"scope": "compile",
107+
"classifier": "",
108+
"optional": "false"
109+
},
110+
{
111+
"groupId": "org.apache.maven.wagon",
112+
"artifactId": "wagon-webdav-jackrabbit",
113+
"version": "3.5.3",
114+
"type": "jar",
115+
"scope": "compile",
116+
"classifier": "",
117+
"optional": "false",
118+
"children": [
119+
{
120+
"groupId": "org.apache.jackrabbit",
121+
"artifactId": "jackrabbit-webdav",
122+
"version": "2.14.4",
123+
"type": "jar",
124+
"scope": "compile",
125+
"classifier": "",
126+
"optional": "false",
127+
"children": [
128+
{
129+
"groupId": "commons-codec",
130+
"artifactId": "commons-codec",
131+
"version": "1.10",
132+
"type": "jar",
133+
"scope": "compile",
134+
"classifier": "",
135+
"optional": "false"
136+
}
137+
]
138+
}
139+
]
140+
}
141+
]
142+
}
143+
+---+
144+
145+
<<Usage Example>>:
146+
147+
+---+
148+
mvn dependency:tree -DoutputType=json -DoutputFile=dependency-tree.json
149+
+---+
150+
151+
<<Use Case>>: Parse the JSON output programmatically for dependency analysis or integration
152+
with other tools.
153+
154+
{DOT (outputType=dot)}
155+
156+
<<Description>>: The DOT format is a plain-text graph description language used by Graphviz.
157+
It represents the dependency tree as a directed graph (<<<digraph>>>), with nodes for
158+
artifacts and directed edges for dependencies, labeled with their scope (e.g., <<<compile>>>).
159+
160+
<<Structure>>:
161+
162+
* <<Graph Declaration>>: Starts with <<<digraph "<groupId>:<artifactId>:<type>:<version>:">>>.
163+
164+
* <<Nodes>>: Represented implicitly by their identifiers in edge definitions
165+
(e.g., <<<"org.apache.maven.extensions:maven-build-cache-extension:jar:1.2.1-SNAPSHOT:">>>).
166+
167+
* <<Edges>>: Defined as <<<"source" -> "target">>>, where <<<source>>> is the parent artifact
168+
and <<<target>>> is the dependency, optionally labeled with the scope.
169+
170+
<<Example>>:
171+
172+
+---+
173+
digraph "org.apache.maven.extensions:maven-build-cache-extension:jar:1.2.1-SNAPSHOT:" {
174+
"org.apache.maven.extensions:maven-build-cache-extension:jar:1.2.1-SNAPSHOT:" -> "net.openhft:zero-allocation-hashing:jar:0.27ea0:compile";
175+
"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";
176+
"org.apache.maven.wagon:wagon-webdav-jackrabbit:jar:3.5.3:compile" -> "org.apache.jackrabbit:jackrabbit-webdav:jar:2.14.4:compile";
177+
"org.apache.jackrabbit:jackrabbit-webdav:jar:2.14.4:compile" -> "commons-codec:commons-codec:jar:1.10:compile";
178+
}
179+
+---+
180+
181+
<<Usage Example>>:
182+
183+
+---+
184+
mvn dependency:tree -DoutputType=dot -DoutputFile=dependency-tree.dot
185+
+---+
186+
187+
<<Visualization>>: Convert the DOT file to an image using Graphviz:
188+
189+
+---+
190+
dot -Tpng dependency-tree.dot -o dependency-tree.png
191+
+---+
192+
193+
<<Use Case>>: Visualize the dependency graph using tools like Graphviz for presentations
194+
or analysis.
195+
196+
{GraphML (outputType=graphml)}
197+
198+
<<Description>>: GraphML is an XML-based format for representing graphs, compatible with
199+
tools like yEd or Gephi. It represents the dependency tree as a directed graph with nodes
200+
for artifacts and edges for dependencies, including scope information.
201+
202+
<<Structure>>:
203+
204+
* <<GraphML Root>>: Contains namespace declarations and keys for node and edge graphics
205+
(using <<<yworks.com>>> extensions).
206+
207+
* <<Graph>>: Defined with <<<edgedefault="directed">>>.
208+
209+
* <<Nodes>>: Each node has an <<<id>>> (a unique number) and a <<<y:ShapeNode>>> with a
210+
<<<y:NodeLabel>>> containing the artifact coordinates (e.g., <<<groupId:artifactId:type:version:scope>>>).
211+
212+
* <<Edges>>: Defined with <<<source>>> and <<<target>>> node IDs, with a <<<y:PolyLineEdge>>>
213+
containing a <<<y:EdgeLabel>>> for the scope (e.g., <<<compile>>>).
214+
215+
<<Example>>:
216+
217+
+---+
218+
<?xml version="1.0" encoding="UTF-8"?>
219+
<graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:y="http://www.yworks.com/xml/graphml">
220+
<key for="node" id="d0" yfiles.type="nodegraphics"/>
221+
<key for="edge" id="d1" yfiles.type="edgegraphics"/>
222+
<graph id="dependencies" edgedefault="directed">
223+
<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>
224+
<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>
225+
<edge source="955994360" target="2058879732"><data key="d1"><y:PolyLineEdge><y:EdgeLabel>compile</y:EdgeLabel></y:PolyLineEdge></data></edge>
226+
<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>
227+
<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>
228+
<edge source="1889106580" target="1817415346"><data key="d1"><y:PolyLineEdge><y:EdgeLabel>compile</y:EdgeLabel></y:PolyLineEdge></data></edge>
229+
</graph>
230+
</graphml>
231+
+---+
232+
233+
<<Usage Example>>:
234+
235+
+---+
236+
mvn dependency:tree -DoutputType=graphml -DoutputFile=dependency-tree.graphml
237+
+---+
238+
239+
<<Visualization>>: Open the GraphML file in yEd or Gephi to visualize the dependency graph.
240+
241+
<<Use Case>>: Analyze complex dependency structures using graph visualization tools.
242+
243+
{TGF (outputType=tgf)}
244+
245+
<<Description>>: The Trivial Graph Format (TGF) is a simple text-based format for representing
246+
graphs. It lists nodes followed by edges, with each node and edge described on a single line.
247+
248+
<<Structure>>:
249+
250+
* <<Nodes Section>>: Each line contains a unique node ID (a number) followed by the artifact
251+
coordinates (e.g., <<<groupId:artifactId:type:version:scope>>>).
252+
253+
* <<Separator>>: A line containing <<<#>>> separates nodes from edges.
254+
255+
* <<Edges Section>>: Each line contains the source node ID, target node ID, and the scope
256+
(e.g., <<<compile>>>).
257+
258+
<<Example>>:
259+
260+
+---+
261+
1474640235 org.apache.maven.extensions:maven-build-cache-extension:jar:1.2.1-SNAPSHOT:
262+
788877168 net.openhft:zero-allocation-hashing:jar:0.27ea0:compile
263+
1662807313 org.apache.maven.wagon:wagon-webdav-jackrabbit:jar:3.5.3:compile
264+
1655562261 org.apache.jackrabbit:jackrabbit-webdav:jar:2.14.4:compile
265+
1894638973 commons-codec:commons-codec:jar:1.10:compile
266+
#
267+
1474640235 788877168 compile
268+
1474640235 1662807313 compile
269+
1662807313 1655562261 compile
270+
1655562261 1894638973 compile
271+
+---+
272+
273+
<<Usage Example>>:
274+
275+
+---+
276+
mvn dependency:tree -DoutputType=tgf -DoutputFile=dependency-tree.tgf
277+
+---+
278+
279+
<<Visualization>>: Convert TGF to other formats (e.g., DOT) using tools like <<<graphviz>>> or
280+
custom scripts for visualization.
281+
282+
<<Use Case>>: Lightweight format for simple graph processing or conversion to other graph formats.
283+
284+
* Notes
285+
286+
* <<Plugin Version>>: The <<<json>>>, <<<dot>>>, <<<graphml>>>, and <<<tgf>>> output formats are
287+
available starting with Maven Dependency Plugin version 3.7.0. Always use the latest version
288+
(3.8.1 as of June 2025) for the most stable experience.
289+
290+
* <<Visualization Tools>>:
291+
292+
* <<JSON>>: Parse with any JSON-compatible tool (e.g., Python's <<<json>>> module, JavaScript's <<<JSON.parse>>>).
293+
294+
* <<DOT>>: Use Graphviz (<<<dot>>> command) to generate PNG, SVG, or other visual formats.
295+
296+
* <<GraphML>>: Use yEd, Gephi, or other GraphML-compatible tools for visualization.
297+
298+
* <<TGF>>: Use tools supporting TGF or convert to DOT/GraphML for visualization.
299+
300+
* <<Contributing>>: If you encounter issues or want to improve this documentation, contribute to
301+
the Maven Dependency Plugin repository at
302+
{{{https://github.com/apache/maven-dependency-plugin}https://github.com/apache/maven-dependency-plugin}}.
303+
See the
304+
{{{https://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}.

‎src/site/apt/index.apt.vm‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,8 @@ ${project.name}
150150

151151
* {{{./examples/purging-local-repository.html}Purging the local repository}}
152152

153+
* {{{./examples/tree-mojo.html}Tree Mojo}}
154+
153155
[]
154156

155157
* Resources

‎src/site/site.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ under the License.
4242
<item name="Exclude Dependencies from Dependency Analysis" href="examples/exclude-dependencies-from-dependency-analysis.html"/>
4343
<item name="Filtering the dependency tree" href="examples/filtering-the-dependency-tree.html"/>
4444
<item name="Purging local repository dependencies" href="examples/purging-local-repository.html"/>
45+
<item name="Dependency tree output formats" href="examples/tree-mojo.html"/>
4546
</menu>
4647
<menu name="Resources">
4748
<item name="Dependency Mechanism" href="../../guides/introduction/introduction-to-dependency-mechanism.html"/>

0 commit comments

Comments
 (0)