My git viewer

Why I did this

So, the premise behind this project was a few different things:

• I wanted a git viewer stack that, while modular, remained light.
• I liked the idea of having reusable “templates” rather than generating the HTML dynamically in the code. This is much closer to how things like Hugo operate.
• It needs to be easy to extend (modularity!). A core is responsible for loading a git repo’s context and other request state, but all “real” functionality is implemented via modules. I could add/remove things without needing to worry (too much…) about breaking unrelated things.
• I wanted something that was modern, but didn’t require javascript to operate. All features on this site work without javascript, though your experience is improved with it.
• I wanted to have a way to view private git repositories using systems I already have.
  • I don’t want to/have the capability to SSH clone my repos to show something off.
  • Could I have done this in cgit? Perhaps, but it wasn’t built for it.
• And, probably most visibly, this was a trial in “vibe coding”. While the idea around the design of this software was mine, I wrote very little of the code. Especially the UI, and this is for the better. I am not a graphics designer and whatever slop the LLM pumps out (with my input here and there) will be leagues better than whatever I do; for better or worse.

The name “gsg” doesn’t mean much (I don’t name things). It’re pretty much “git static generator”. It was the placeholder when I was thinking of a system that was “kind of a combination of cgit’s lightness and hugo’s composability and templating”.

The design

First and foremost, the AI writeup is in ./llm_readme.md. Read that if you want all of the verbose details.

Also, as alluded to above, no javascript is strictly required. The few places it is used it is just used to make the experience nicer, and a fallback always exists. For example, the JSON/YAML codepath has a JS module that allows you to search for values/keys, perform folding, etc. This is a core design tenant: JS always hydrates what exists already.

(Not) Broadly speaking, as stated above, this project is split up into:

• The core
  • gitx - the module that actually interfaces with git. This transforms a context into a re-usable struct (should I ever want to use a real implementation)
  • access - Consolidated checks for whether someone can see/not see a repo
  • session - Owns all privileged access logic. It generates/verifies tokens that are used across the site. Everything is stateless once authenticated.
  • authn - Route owner that defines login/logout flows. Uses session internally
  • httpx - Shared helpers used when generating responses/evaling a req
  • notices - Logic for me to post notices to the site or repos
  • share - Logic for authenticated users to mint links to private repos they are allowed to. Uses same auth logic as users under the hood.
  • api - Exposes repo details as a JSON endpoint, will be used by my main site later on
  • core/site - All the main things needed to make this tick. Build req context, define routes and where they live, define module registration structs.
• The modules
  • blob - Responsible for returning files (raw or templated)
  • commit - Render a commit
  • compare - Render a diff between two commits/refs
  • graph - Render commit log graph
  • image - Image preview, defines compatible file types and max size
  • markdown - Render markdown
  • readme - Inherits markdown to render a readme (what you see here!)
  • notices - Handles cache invalidation for repos that need one rendered
  • log - View the git log
  • repos - Aggregates the repos you may view based on session
  • structured - Whether a file is a YAML or JSON. If so, it prepares data for JS in the frontend to perform folding and suchA
  • tree - the directory-structure viewer

As time goes on, I am sure I will find more things to add to this. This is really meant to be a project for me, not necessarily building “the next git viewer for everyone”.

I figured I would upload this here in case my tokens are useful for others. Enjoy!