Visualize the codebase of your GitHub repo
Try GitHub Next's repo-vizualizer action for generating a diagram of your codebase
Beginning of the month, Amelia Wattenberger of GitHub Next has published a project to create a SVG visualization of a GitHub repository’s codebase.
On the project page Visualizing a codebase, she talks about the advantages of code vizualization in terms of a better overview and comparability of code … and I loved it at first sight, because I’m an absolute visual person.
But her attempt was not only to show us what’s possible (static SVG files and even interactive apps for code browsing, filtering and comparing), but give us the possibility to create our own codebase diagrams as SVG automatically, whenever we commit our code, by running a GitHub Action, she and her team has developed … the Repo Vizualizer
Actually, her instructions are quite simple to implement, but the devil is in the details and I would like to show you what you may need for this. The goal is to prepare every project hosted on GitHub with instructions to run the Repo Visualizer after every commit to create or update a SVG file in the project, we can use in the README or via hotlinking in every other web page.
Let’s start with my setup:
- Windows 10
- Visual Studio Code
- a bunch of tiny projects hosted on GitHub
Project Integration
GitHub actions are configured via YAML files in the folder .github\workflows
. Therefore, just take Amelias demo file diagram.yaml
and copy it to this folder.
1 | name: Create Vizualizing Codebase Diagram |
You don’t have to change anything in this file, except the name if you want to. It is clear to run correctly.
Prepare Windows
In case you get the following error message on pushing the new file in your project to GitHub …
1 | refusing to allow an OAuth App to create or update workflow .github/workflows/diagram.yml without workflow scope |
… you have a problem with your OAuth Token the Git Credential Manager created for you, while installing Git for Windows. This token doesn’t include the permission to update GitHub action workflows.
A workaround is, to create a Personal Access Token on Github WITH this permission …
… and replace the existing token in the Windows Credential Manager (in German the wonderful word “Anmeldeinformationsverwaltung”):
Parameters
There are a few interesting parameters to place within the with
section, that allow you to customize the output of the graph to your needs:
output_file
- The name and relative path to the SVG file to generate. Default is ./diagram.svgroot_path
- The root path of the code to be vizualizedexcluded_paths
- Folders to exclude from visualizing (as in the demo YAML)excluded_globs
- Files to exclude from visualizing in micromatch syntaxcommit_message
- After the action has created the diagram, it will be commited with this custom message
After pushing your changes, you can watch the action run in the ACTIONS tab in GitHub:
The README
As the SVG is part of yor project, you can use it easily in your repos README:
1 | ## Codebase Vizualization |
This SVG is not interactive as Amelias Repo Visualization React app is, but it is a good overview of a repos codebase und it looks really good.
You can interact with this article (applause, criticism, whatever) by mention it in one of your posts or by replying to its syndication on Twitter, which will also be shown here as a Webmention ... or you leave a good old comment with your GitHub account.
Webmentions
No Webmentions yet...
In case your blog software can't send Webmentions, you can use this form to submit me a mention of this article...
Comments