7 tools for visualizing a codebase

Need to write a README file, but not sure what to say? If this is a frustration that bothers you frequently, you might consider beefing your document up with a diagram. After all, a picture is worth a thousand words, as the cliche goes.

Photo by Hanna Morris on Unsplash

This article collects tools that generates graphs for a code repository.

Visualize files by size and type

Let’s start with the most generic tool, repo-visualizer. It plots files as bubbles, indicating their extension names and sizes with colors and sizes, respectively. It's brought to you by GitHub Next, a lab at GitHub the company, and (naturally) it's packaged as a GitHub Action.

Visualize Docker Compose files

The next tool specifically caters to Docker users, but it’s still language-agnostic. To visualize docker-compose.yml, you can use docker-compose-viz:

docker run \--rm \-it \--name dcv \-v $(pwd):/input pmsipilot/docker-compose-viz render \-m image docker-compose.yml

Here’s how it would look:

I like how it’s also plotting extra information like open ports and mounted volumes.

Visualize call graphs

Code2flow supports a couple of dynamic languages, including Python, JavaScript, Ruby, and PHP.

Here’s the example provided in its README:

code2flow code2flow/engine.py code2flow/python.py --target-function=code2flow --downstream-depth=3

Call graph of a student project by Pamela Fox. Slides.

If Python is the only language you care about, you might have heard of pycallgraph , but -- alas, the bane of open source software projects -- the original author had to abandon the project due to personal time constraints. The most sensible alternative I can find is pyan.

pyan *.py --uses --no-defines --colored --grouped --annotated --svg >myuses.svg

Visualize dependencies

A fundamental functionality of build systems and package managers is dependency resolution. As you’d expect, many visualization tools tap into dependency graphs generated by these software to plot diagrams for a repository.

Under the hood, most of these tools use graphviz for the actual plotting work. Therefore, don't be surprised to discover that the diagrams share a similar style.

Bazel is a language-agnostic build system. The developers behind Bazel know its users so well that they put up an official guide for visualizing dependencies defined with Bazel:

bazel query 'deps(//:main)' --output graph > dependencies.in
dot -Tpng < dependencies.in > dependencies.svg

It gives something like this:

For Python packages in an environment, use pipdeptree:

pipdeptree --graph-output svg > dependencies.svg

For Java projects built with Maven, depgraph-maven-plugin is the way to go:

mvn com.github.ferstl:depgraph-maven-plugin:graph

I want more interactivity!

Maybe you’re not here to fill up your README; rather, you just want to learn about a repo as quickly and intuitively as possible. If that’s the case, there are some nice tools you can play with:

• Gource: A locally-run software.
• CodeSee: A cloud service that offers paid plans.

I’m not endorsing either of them, and they are beyond the scope of this post. Nevertheless, this serves as a good point to wrap up this post. Writing an ending is painful, and I’m sure you’re aware of that — Otherwise, you would not have landed on this very article that helps you evade the chore of composing words, would you?