Image of I struggled with Git, so I'm making a game to spare others the pain

Table of Contents

It's been 2 years...

...since I created and released Git-Sim, a free and open-source tool to visualize Git commands directly in your own repos.

The most important takeaway I got from that experience was that there is a pretty strong demand out there for visual coding aids.

In the weeks after the release, I got to thinking... Visualizing and simulating the output of Git commands with handy diagrams is great, but I realized it only helps people already familiar with Git to some degree.

For instance, visualizing the command git merge dev (as shown in the Git-Sim generated image below) provides little value to someone who has never used Git before. For Git-Sim to be useful, users need at least a basic understanding of what each Git command does and why they would want to run it in the first place.

Git-Sim merge dev command

I wondered whether there was a variation or enhanced version of Git-Sim that could be more broadly applicable to coders of all skill levels - even total newbies - AND be even more immersive and intuitive than Git-Sim.

Then a thought popped into my head:

What if you could literally walk through your Git repository to see, touch, and feel Git concepts in a much more tangible way?

This became the kernel of my idea for building the next-generation version of Git-Sim.

Sitting on my couch

One evening a few weeks later, I sat on my couch pondering what this "more immersive" version of Git-Sim might look like, when another thought popped into my head.

What if a Git branch was like a hallway you could walk down? And rooms along the hallway were commits, and the room number was the commit ID? What if you could enter those rooms to see information related to the commit, such as which files were changed, what code changed in those files (i.e. the diffs), the author, and timestamp data?

That seemed pretty weird, but maybe kinda cool?

Long story short - I stumbled upon a YouTube tutorial for building an open-source Doom remake in Python's Pygame framework...

I cloned down the code for it and rejiggered it to read Git repo data using the GitPython library to display it on various surfaces in the game. It was absurd. The result looked like this:

The first half of this video shows what I described above - a Git branch represented as a hallway that you can walk down and explore commit data as rooms on either side.

The second half of the video shows a big room where you can simulate a large number of Git commands by pressing red buttons on the wall. This invoked Git-Sim behind the scenes to generate a visual image of how that command would impact the underlying Git repo.

I won't lie - it was really cool seeing Git data rendered in a game like this for the first time and gave me a little buzz.

However, it didn't seem particularly likely that people would want to use something like this. Doom is a scary, stressful game where you shoot monsters, and Git is a confusing, stressful tool. Squishing them together just seemed... hazardous. And multiplied the inherent stressors in each.

I realized that I needed an environment that would counteract the confusing and sometimes intimidating nature of Git by setting a welcoming, relaxing, and engaging tone. I needed something more zen.

Graduating to a voxel world

A few months later, the same creator of the Pygame Doom tutorial released something else: A YouTube tutorial for an open-source voxel world recreated in Pygame.

In case you don't know, a "voxel world" is a world made out of individual blocks called voxels, arranged into large chunks that make up the world. Honestly, it may as well just be called a "blocky world."

As soon as I saw this, I knew it would be a perfect fit, as it ticked all the following boxes:

  • Written in Python using the Pygame framework, which is something I was comfortable with, having used it in various projects since I was a kid
  • Had the ingredients for building blocky worlds, including the data structures required to store the state of the world, 3D visuals, camera movement, procedural island generation, and the ability for the player to add and remove blocks
  • The potential to be the calm, relaxing, natural-world environment that would portray Git and coding in an approachable (not intimidating) way
  • Free and open-source (under the MIT license)

Essentially, I used this open-source codebase as a starting point and framework for building my next-generation Git tool.

Plus it seemed way more fun to enhance and mold a small project like this built by a single person (where I could see and learn how all the code worked) than to use a trendy game development darling like Unity, Unreal Engine, or Godot.

So now, my visual Git tool looks a little something like this:

As you may have guessed, that was staging an untracked file in the working directory! I call this the "working directory wall".

And who wouldn't enjoy walking down a beachy boardwalk through their commit history?

So what did it take to make this?

For me, making this gamified Git tool is part technical deep dive, part unapologetic nostalgia, and part reckless enthusiasm.

Understanding the engine

I started by trying to understand the guts of the voxel engine itself - an intricate, but well structured combination of Pygame and OpenGL that handled the basics of chunk loading, player movement, procedural island generation, and adding/removing blocks in the world.

That alone was a multi-week rabbit hole, as I dug into the rendering pipeline (a brand new concept for me) while tinkering with the structure and mechanics of the game world.

Tweaking the island generation parameters took a good bit of time and effort to yield islands of the right size and form. It didn't help that at this point in the journey, I didn't have a clear image of what the final thing might look like.

After much trial, error, and performance profiling, I settled on a medium-sized island that would be big enough to have separate areas for visualizing Git concepts like the working directory, staging area, commit history, and stash, but small enough to perform well on relatively older hardware like my regretful 2020 Intel Macbook Pro.

Adding basic game mechanics

Next, I had to build some basic game mechanics. This included things like gravity, world boundaries, more responsive player movement, the ability to run and jump, collision detection, and the ability to do fluid camera "LERPs" (linear-interpolations) between points in the world. The camera LERP functionality would come in handy for focusing the player's attention on a specific scene in the world, when learning about a particular Git concept.

Integrating Git

Speaking of Git, the game needed Git integration! I added a Git interface using GitPython to handle all interactions with the underlying Git repository. This included fetching Git data for display in the game world and executing Git commands that impact the underlying repo.

Then the Git data needed to be rendered as physical objects in the game world, so there was an ideation and design phase related to that - (more on that in a future post)!

One thing I am particularly proud of is a novel saving/loading system that stores the state of the blocks in the world (block positions, types, and other project configuration), within the Git repo - specifically in a hidden Git ref - that you're working in, so any world you build and customize can be shared with your friends by pushing and pulling from a shared Git repo. (Don't tell anyone, but a planned future feature is a networked setup to enable multiplayer pair programming in the same hosted world).

Helping folks learn Git

The next big thing I implemented was an immersive, character-guided Git tutorial taking new coders through all the most important Git commands and concepts. This involved character-design, narrative scripting, adding a menu system, designing a UI for communicating Git knowledge to the player, and allowing the player to interact effectively with the tutorial.

Polishing

Finally, everything needed a coat of polish. Not being an artistically gifted individual myself, I worked with a very talented video game artist to redesign all game assets and create new ones, including a texture array for all the block types in the world, all menu and UI elements, the guide character for the tutorial, a world map, and seemingly endless little bits and bobs.

Note that this is a high-level list. Some of these items took a few days, and some took months. I'm still working on some. There were innumerable smaller tasks that I could never fully list... Unless I had some sort of version-tracking capability to help with that...

After months of work, I had made a lot of progress... but I still didn't even have a name for this tool!

What's in a name?

For not-so-subtle reasons, I initially fell in love with one name and one name only: Gitcraft. So much so that I impulse-bought the domain gitcraft.com for $2,660.16 (questionable move, as will soon become apparent).

But c'mon! Git + Minecraft... What could be better?

Unfortunately, months later I remembered something I had learned at a Git conference the year before - that the legal entity that manages Git's copyright and trademark protection (the Software Freedom Conservancy), doesn't exactly like it when other tools include the word "Git" in their name. This does make sense considering everyone and their Mom is using the name "Git" in their tools these days (including me with Git-Sim), which draws questions about whether these tools are associated with Git itself, or are just related products/tools in the ecosystem.

In case you're interested, here is the specific section in Git's trademark policy that prohibits this:

In addition, you may not use any of the Marks as a syllable in a new word or as part of a portmanteau (e.g., "Gitalicious", "Gitpedia") used as a mark for a third-party product or service without Conservancy's written permission. For the avoidance of doubt, this provision applies even to third-party marks that use the Marks as a syllable or as part of a portmanteau to refer to a product or service's use of Git code.

Although this was the initial factor that prompted me to choose a different name, there were other good reasons as well. "Gitcraft" is catchy, but it does pigeonhole the tool into forever revolving around Git. A more general name could make expanding or changing the scope of the tool more flexible later on. Software development is such a broad space, that keeping my options open seemed like a good idea.

In the end, after spending as much time naming this Git tool as I did on the name of my own child, I settled on the name Devlands. This fit perfectly - it implies a gamified world for developers, which could be shaped and molded in various ways in the development process. And thankfully the domain devlands.com was available for a whopping... $10.46.

And... what exactly is this thing?

At its core, Devlands is something I originally started working on just to see if it was possible - a way to literally walk through your own codebase inside an immersive world. I wanted to take something as abstract as Git and make it feel physical - something you could see, touch, and explore instead of just reading documentation, running commands in a terminal, and using menu-based GUIs.

Currently, Devlands is split into two "modes":

  1. A character-guided Git tutorial designed to walk new users through all the essential Git concepts and commands - or, if this isn't your first rodeo, you can just pick whichever topics you want to brush up on.
  2. A freeform mode where you can roam around your codebase and interact with it directly. Files, commits, branches, and tags all become blocks in the game, and even Git's stash is in there somewhere. You can simulate and run commands right from inside the game, view and edit your files, and there’s even an AI tool that can help explain confusing bits of code that you don't understand.

But I didn’t just want it to work, I wanted it to actually help people...

Relating to an abstract topic

The primary goal of Devlands is to make Git and coding more approachable and intuitive for the average person - even if they have little or no coding experience.

Git and coding concepts tend to be very abstract, so the ability to see tangible representations of these ideas helps people relate much better. Fostering this connection is essential to improve and speed up the learning process, and in some cases can make the difference between someone pursuing a career in software development versus throwing in the towel.

For example, if I explain Git to someone as:

"Git is a version control system that lets developers track their code changes and collaborate with others."

I get a bored and glazed look every time.

However, if I explain Git to someone as:

"Git is like Microsoft Word's track changes feature, but for coders."

I can see things start to click.

To connect with abstract concepts, people need to be able to relate to them.

My hope is for Devlands to provide a fresh and untapped perspective into the world of coding, offering developers the most intuitive way to interact with their code and gain deeper levels of knowledge and understanding.

TL;DR

Learning and using Git kinda sucks! So I'm building Devlands to make learning and using Git more accessible and intuitive for ... anyone.

Somehow, making visual Git tools and resources has become my passion over the past 10 years. Just wanted to take a moment and say thanks to everyone who’s supported me - whether by reading my posts, trying out my projects, spreading the word, or helping keep the lights on.