GitHub is great for exploring repositories, but it’s not always the best option for your project. If you want to keep it private, access it without the internet, or configure what you see, you’ll need to use command-line magic or a GUI client.
pgit offers an alternative: a static site that renders your repository as a browsable set of pages, much like GitHub’s code view.
What is pgit?
pgit is a static site generator for git. In other words, it produces a browsable git repo that you can serve from any static host, including your own local web server.
The service is analogous to GitHub’s “Code” tab. It shows individual files and commits, with details of the code that changed between them. This makes it easy to learn about the project structure and its history. Code files are syntax-highlighted, and you can configure the theme from a large selection of presets.
pgit just generates the static HTML files; it’s up to you to then host them on a remote server or view them locally.
How to install and use pgit
pgit is a simple tool, but it’s one that you’ll need to build yourself. Don’t let that put you off, though; the build process couldn’t be much easier:
git clone git@github.com:picosh/pgit.git
cd pgit
make build
This will produce a binary in the pgit directory; feel free to run it from there or move it to a more convenient location, like one in your PATH. So, to run pgit against its own repository, just run:
./pgit
You’ll see a new directory named public, containing all the generated static HTML files. You can either browse this directory locally, via a web server, or upload it to a static host and view the code there.
The time it takes pgit to run will depend on the size of your repository and the number of commits and revisions you include.
Additional features and configuration
The default behavior of pgit produces a simple browsable repository site, but if you want to take it a bit further, there are a few things you can tweak to your liking.
Multiple repos
By default, pgit generates a single-repository site, with relative links. This means you’ll want to run a web server behind it, set up to serve the pgit output directory as its document root. You can do this with a static site host, like pico.sh or locally, using virtual hosts, for example.
Hosting locally, you might have a pgit-generated directory like /home/project/public, which you can then serve as an Apache virtual host using configuration like this:
Listen 8000
DocumentRoot “/home/project/public”
Require all granted
This will work fine for a single project that you can access using URLs like http://localhost:8000/tree/b7fcf0e/index.html, but it won’t allow more than one project to coexist.
To support multiple repositories, you can change how pgit generates links, telling it to use a subdirectory for each project, rather than the root:
pgit –out /home/project/public/first –root-relative “/first/”
pgit –out /home/project/public/second –root-relative “/second/”
Using this approach, one project will be browsable at http://localhost:8000/first/ and the other at http://localhost:8000/second/.
Commits, branches, and revisions
pgit can struggle with projects containing a huge number of commits. To cater for this, you can limit the number of commits it will process using the –max-commits option, for example:
pgit –max-commits 1000
By default, pgit will generate a site for the HEAD revision of your repo. You can change this to any combination of revisions (branches, tags, commit hashes) using the –rev option, like this:
pgit –revs dev,v1,c49e89f
README summary
Just like GitHub, pgit will look for a README file in your repo and embed it in the index page of your generated site. Unlike GitHub, it will be the Markdown source rather than an HTML-formatted version, but Markdown is easy to read, so that shouldn’t really be an issue.
Template files
You can use pgit’s –theme option to change the syntax highlighting color scheme. If you want to alter pgit’s output beyond that, you’ll have to edit either the generated HTML files or the templates used to produce them. The latter is by far the better option, but it comes with a small caveat: you’ll need to rebuild pgit each time you make a template change.
Template files live in the html subdirectory.
Currently, the tool serves a small, technical audience, so this isn’t too problematic. However, if you’re uncomfortable with this kind of approach, you may want to avoid pgit altogether.
Why you should use pgit or an alternative
It might seem like a lot of work, so why should you go to all this effort when you can use GitHub instead?
Well, for a start, it’s not actually that much work. You can get great results from just a single ./pgit, with a pretty basic one-off step to set up your web server.
The pgit approach lets you avoid GitHub subscription costs. Your repository can stay private, and you won’t have to pay anything for the privilege. You’ll also gain full control over the output and how to present it.
If you’re not sold on pgit, there are alternatives. cgit is an old-school approach using CGI, so it requires much more effort to set up. Stagit is another static site generator that inspired pgit. It’s another low-level tool, but the project is slightly more mature than pgit.
Finally, for a much more featureful experience, you can run a personal GitLab server, although that also involves more effort to set up.
