README.md
1# depth
2
3[![GoDoc](https://godoc.org/github.com/KyleBanks/depth?status.svg)](https://godoc.org/github.com/KyleBanks/depth)
4[![Build Status](https://travis-ci.org/KyleBanks/depth.svg?branch=master)](https://travis-ci.org/KyleBanks/depth)
5[![Go Report Card](https://goreportcard.com/badge/github.com/KyleBanks/depth)](https://goreportcard.com/report/github.com/KyleBanks/depth)
6[![Coverage Status](https://coveralls.io/repos/github/KyleBanks/depth/badge.svg?branch=master)](https://coveralls.io/github/KyleBanks/depth?branch=master)
7
8`depth` is tool to retrieve and visualize Go source code dependency trees.
9
10## Install
11
12Download the appropriate binary for your platform from the [Releases](https://github.com/KyleBanks/depth/releases) page, or:
13
14```sh
15go get github.com/KyleBanks/depth/cmd/depth
16```
17
18## Usage
19
20`depth` can be used as a standalone command-line application, or as a package within your own project.
21
22### Command-Line
23
24Simply execute `depth` with one or more package names to visualize. You can use the fully qualified import path of the package, like so:
25
26```sh
27$ depth github.com/KyleBanks/depth/cmd/depth
28github.com/KyleBanks/depth/cmd/depth
29 ├ encoding/json
30 ├ flag
31 ├ fmt
32 ├ io
33 ├ log
34 ├ os
35 ├ strings
36 └ github.com/KyleBanks/depth
37 ├ fmt
38 ├ go/build
39 ├ path
40 ├ sort
41 └ strings
4212 dependencies (11 internal, 1 external, 0 testing).
43```
44
45Or you can use a relative path, for example:
46
47```sh
48$ depth .
49$ depth ./cmd/depth
50$ depth ../
51```
52
53You can also use `depth` on the Go standard library:
54
55```sh
56$ depth strings
57strings
58 ├ errors
59 ├ io
60 ├ unicode
61 └ unicode/utf8
625 dependencies (5 internal, 0 external, 0 testing).
63```
64
65Visualizing multiple packages at a time is supported by simply naming the packages you'd like to visualize:
66
67```sh
68$ depth strings github.com/KyleBanks/depth
69strings
70 ├ errors
71 ├ io
72 ├ unicode
73 └ unicode/utf8
745 dependencies (5 internal, 0 external, 0 testing).
75github.com/KyleBanks/depth
76 ├ fmt
77 ├ go/build
78 ├ path
79 ├ sort
80 └ strings
817 dependencies (7 internal, 0 external, 0 testing).
82```
83
84#### `-internal`
85
86By default, `depth` only resolves the top level of dependencies for standard library packages, however you can use the `-internal` flag to visualize all internal dependencies:
87
88```sh
89$ depth -internal strings
90strings
91 ├ errors
92 ├ io
93 ├ errors
94 └ sync
95 ├ internal/race
96 └ unsafe
97 ├ runtime
98 ├ runtime/internal/atomic
99 └ unsafe
100 ├ runtime/internal/sys
101 └ unsafe
102 ├ sync/atomic
103 └ unsafe
104 └ unsafe
105 ├ unicode
106 └ unicode/utf8
10712 dependencies (12 internal, 0 external, 0 testing).
108```
109
110#### `-max`
111
112The `-max` flag limits the dependency tree to the maximum depth provided. For example, if you supply `-max 1` on the `depth` package, your output would look like so:
113
114```
115$ depth -max 1 github.com/KyleBanks/depth/cmd/depth
116github.com/KyleBanks/depth/cmd/depth
117 ├ encoding/json
118 ├ flag
119 ├ fmt
120 ├ io
121 ├ log
122 ├ os
123 ├ strings
124 └ github.com/KyleBanks/depth
1257 dependencies (6 internal, 1 external, 0 testing).
126```
127
128The `-max` flag is particularly useful in conjunction with the `-internal` flag which can lead to very deep dependency trees.
129
130#### `-test`
131
132By default, `depth` ignores dependencies that are only required for testing. However, you can view test dependencies using the `-test` flag:
133
134```sh
135$ depth -test strings
136strings
137 ├ bytes
138 ├ errors
139 ├ fmt
140 ├ io
141 ├ io/ioutil
142 ├ math/rand
143 ├ reflect
144 ├ sync
145 ├ testing
146 ├ unicode
147 ├ unicode/utf8
148 └ unsafe
14913 dependencies (13 internal, 0 external, 8 testing).
150```
151
152#### `-explain target-package`
153
154The `-explain` flag instructs `depth` to print import chains in which the
155`target-package` is found:
156
157```sh
158$ depth -explain strings github.com/KyleBanks/depth/cmd/depth
159github.com/KyleBanks/depth/cmd/depth -> strings
160github.com/KyleBanks/depth/cmd/depth -> github.com/KyleBanks/depth -> strings
161```
162
163#### `-json`
164
165The `-json` flag instructs `depth` to output dependencies in JSON format:
166
167```sh
168$ depth -json github.com/KyleBanks/depth/cmd/depth
169{
170 "name": "github.com/KyleBanks/depth/cmd/depth",
171 "deps": [
172 {
173 "name": "encoding/json",
174 "internal": true,
175 "deps": null
176 },
177 ...
178 {
179 "name": "github.com/KyleBanks/depth",
180 "internal": false,
181 "deps": [
182 {
183 "name": "go/build",
184 "internal": true,
185 "deps": null
186 },
187 ...
188 ]
189 }
190 ]
191}
192```
193
194### Integrating With Your Project
195
196The `depth` package can easily be used to retrieve the dependency tree for a particular package in your own project. For example, here's how you would retrieve the dependency tree for the `strings` package:
197
198```go
199import "github.com/KyleBanks/depth"
200
201var t depth.Tree
202err := t.Resolve("strings")
203if err != nil {
204 log.Fatal(err)
205}
206
207// Output: "'strings' has 4 dependencies."
208log.Printf("'%v' has %v dependencies.", t.Root.Name, len(t.Root.Deps))
209```
210
211For additional customization, simply set the appropriate flags on the `Tree` before resolving:
212
213```go
214import "github.com/KyleBanks/depth"
215
216t := depth.Tree {
217 ResolveInternal: true,
218 ResolveTest: true,
219 MaxDepth: 10,
220}
221
222
223err := t.Resolve("strings")
224```
225
226## Author
227
228`depth` was developed by [Kyle Banks](https://twitter.com/kylewbanks).
229
230## License
231
232`depth` is available under the [MIT](./LICENSE) license.
233