Repository Visualization with GitHub Next
Tags: github, visualization, git, analytics
Published: 2021-10-09 04:19:05

---
title: Repository Visualization with GitHub Next
published: true
date: 2021-10-09 03:54:48 UTC
tags: GitHub,Visualization,git,analytics
canonical_url: https://killalldefects.com/2021/10/08/github-next-repo-visualization/
---

[![A banner image featuring a GitHub Repo Visualization](https://i0.wp.com/killalldefects.com/wp-content/uploads/2021/10/RepoVisualizerBanner.png?fit=768%2C449&ssl=1)](https://killalldefects.com/2021/10/08/github-next-repo-visualization/ "Repository Visualization with GitHub Next")

In this short tutorial I’ll introduce you to GitHub Next’s Repo Visualization Project and show you how you can use it to visualize your repositories and even generate images of your git repository every time you push new code to GitHub.

## What is the Repo Visualization project and what can it do?

[GitHub’s repo-visualization project](https://next.github.com/projects/repo-visualization) is an experimental project by [Amelia Wattenberger](https://twitter.com/Wattenberger) aiming to build advanced repository visualization tools that one day may join the main GitHub product. The repo-visualization project is currently part of [GitHub Next](https://next.github.com/) which contains a number of other experimental projects.

![A visualization of GitHub's documentation repository](https://i0.wp.com/killalldefects.com/wp-content/uploads/2021/10/RepoVisualizer1.png?resize=710%2C825&ssl=1)

You can currently use the repository visualization project to view any public repository on GitHub regardless of whether that repository is yours. For example, you can use it to visualize [Microsoft’s Cloud Adoption Framework](https://octo-repo-visualization.vercel.app/?repo=MicrosoftDocs%2Fcloud-adoption-framework), [Vue.js](https://octo-repo-visualization.vercel.app/?repo=vuejs%2Fvue), or even [PowerShell](https://octo-repo-visualization.vercel.app/?repo=PowerShell%2FPowerShell) and interact with these repositories using a visualization powered by [D3.js](https://d3js.org/).

While the interactive visualization struggles to render graphs of larger repositories, once it does render it will let you view the structure of a project at a glance highlighting file size, type, and folder structures. You can also hover over files of particular interest to you.

![An Interactive Visualization of the paperjs/paper.js Repository](https://i1.wp.com/killalldefects.com/wp-content/uploads/2021/10/RepoVisualizerHoverHighlight.png?resize=554%2C541&ssl=1)

In addition to this live visualization technique, the repo visualization project also offers a build action to automatically generate a SVG image file of an architecture diagram whenever code is checked in on a branch that the action is configured to watch. The action will then add a new commit that adds or updates the SVG file in your repository, ensuring the diagram stays up to date without you needing to generate it or wait for it to finish rendering.

The SVG file generated by the build action is a vector image that does not need to be generated in the browser every time the page is visited, which helps performance on larger repositories, though it doesn’t offer the same level of minimalism the interactive version offers since all labels cannot be dynamically shown or hidden in an image.

## Automating Diagram Creation with a Build Action

Generating a GitHub Octo Diagram is fairly straightforward. You’ll need to create a `.yml` file inside of your repository with some basic configuration steps.

First, make sure your project has a `.github` directory in its root directory (the `.` is important here). Inside of that directory you’ll need to create a `workflows` directory if one doesn’t exist already.

Once the `.github/workflows` directory exists, add a `create-diagram.yml` file to your repository and set its contents to the following:

```yml
name: Create diagram
on:
  workflow_dispatch: {}
  push:
    branches:
      - main
jobs:
  get_data:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@master
      - name: Update diagram
        uses: githubocto/repo-visualizer@main
        with:
          excluded_paths: "ignore,.github,.idea"

```

This file is a [YAML file](https://en.wikipedia.org/wiki/YAML) containing information about the action to take, its dependencies, and any optional parameters. The above snippet’s `on: / push: / branches:` configuration assumes that the action watches the `main` branch, but you can modify that as needed to match your repository or watch additional branches.

You may also want to tweak the `excluded_paths` value if you want certain directories to be excluded from the generated diagram.

Once you add, commit, and push this change to GitHub an action should trigger to generate a `diagram.svg` file in your repository’s root. It will look something like this, depending on the contents of your repository:

![A Visualization of the IntegerMan/VisualizingCode Repository](https://i0.wp.com/killalldefects.com/wp-content/uploads/2021/10/RepoVisualizer3.png?resize=770%2C730&ssl=1)

Any subsequent commits on watched branches will cause the image to be updated.

If you’re curious about more details, the full source code for the [repo-visualizer](https://github.com/githubocto/repo-visualizer) is available on GitHub and its readme lists all available configuration options. Configuration options typically get added underneath the `with:` step.

## Adding the Diagram to your Readme

If you want to showcase your repository image on your project’s GitHub page, you can do so by adding a few image and link tags to your `readme.md` file or any other markdown file.

Here’s a sample from the `README.md` file in my [Visualizing Code talk’s repository](https://github.com/IntegerMan/VisualizingCode):

```md
[![Visualization of the codebase](./diagram.svg)](https://octo-repo-visualization.vercel.app/?repo=integerman%2FVisualizingCode)
[View interactive Diagram](https://octo-repo-visualization.vercel.app/?repo=integerman%2FVisualizingCode)

```

The first line contains the path to the image and will be the same on your repository unless you configure the action differently. The URL present on both lines goes to the interactive repository visualization tool which uses a query-string parameter to set the repository being explored in that interactive visualization.

When viewed on GitHub, a `README.md` file like this will generate something like the following image:

![A GitHub Readme page featuring a diagram](https://i2.wp.com/killalldefects.com/wp-content/uploads/2021/10/RepoVisualizer2.png?resize=770%2C652&ssl=1)

## What’s Next?

I’m excited for the new directions that GitHub is going and how [GitHub Next](https://next.github.com/) is starting to give us early signs at how GitHub is expanding our capabilities as open source software developers through projects like the [repo visualizer](https://next.github.com/projects/repo-visualization), [flat data](https://copilot.github.com/), and [Copilot](https://next.github.com/projects/flat-data). It feels like only a matter of time before more and more of these features make it into the regular suite of GitHub features, and I can’t wait.

If you’re interested in more things related to code visualization, give me a follow here or on [Twitter](https://twitter.com/IntegerMan). I’m preparing for a talk on [Visualizing Code](https://sessionize.com/s/matt-eland/visualizing_code/43084) and will be exploring many related topics on this topic as well as on data science matters in the coming months and years.

---

The post [Repository Visualization with GitHub Next](https://killalldefects.com/2021/10/08/github-next-repo-visualization/) appeared first on [Kill All Defects](https://killalldefects.com).