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 is an experimental project by Amelia 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 which contains a number of other experimental projects.

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, Vue.js, or even PowerShell and interact with these repositories using a visualization powered by D3.js.

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.

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:

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 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:

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 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:

[![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:

What’s Next?

I’m excited for the new directions that GitHub is going and how GitHub Next 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, flat data, and Copilot. 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. I’m preparing for a talk on Visualizing Code 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 appeared first on Kill All Defects.