Explainers

In 2011 interface designer Bret Victor wrote an article about reactive documents - documents that allow a reader to interact with the content, explain principles in context and within the broader setting of a bigger system that the principles are part of. The article also coined the term Explorable Explanations or Explainers for short. Since then a whole lot of amazing Explainers have seen the light of day, showing the potential of web platform as a great medium for the concept of reactive documents.

I've been intrigued by the concepts and examples since I first learned about it. I've been meaning to give a try on creating my own Explainer but it turns out it's not that easy to create one. Besides understanding the concepts you want to explain, you need to make the abstract concepts concrete - usually through a visual representation - and have good programming skills to design it for the web platform. Since there is no specialized technology for creating such documents, you're pretty much left to your own devices to figure it out.

The Git Explainer below is my first try for an Explainer. Even though it's quite modest and implements only the first basic git commands, the logic for that counts for about 1700 lines of code. It's built with Javascript, React, Redux and d3. It's a work-in-progress, so please cut the project some slack :-)

Git in Practice

Git is a popular version control system among software development geeks. It takes a snapshot of your whole working directory - unlike other version control systems that only save differences on the tracked files. It's a distributed system where every user gets an entire copy of a project. I'm not gonna be explaining the internals of git - there are already great resources for that. I'll be focusing on the practical workings of the most used git commands - visualizing graphically their actions.

This is not the first endeavor into a Git topic. There is a great game that teaches you the commads, as well as a Git playground you can check out. Unlike the mentioned resources I'll be visualizing the workings of git commands one at a time starting from scratch - meaning to create a kind of graphical dictionary of the most used git commands. So when you forget what a command does, you can easily brush up on it here.

Let's roll!

1. Starting out

So what's the point of using a version control system anyway? Well, imagine you're working on a project. You make changes here and there and all of a sudden you realize it lead you off on a tangent that doesn't go anywhere. Now, it's pretty tiresome or even impossible to step back. You may think about saving full copies of the project as you progress, and that can work - until the project gets too big and you run out of disk space. And what if you're cooperating on the project with other people? How do you get their changes neatly into your working copy? And how about testing out different versions to see which one works best? These are all the places where Git comes in handy.

no git

The circle represents changes you make on your project.
Click on the to make a few.

There's no way to step back easily though. Let's introduce Git.

2. Introducing Git

Ok, let's pull in Git. With git init commad you initialize a new git directory where all the magic happens. Basically there are three "components" of git. Your working directory (circle on the left), the index or staging area (dashed line) and the area for the snapshots of your working directory - or "commits" in git terminology (dashed circle on the right). Let's put our newly created git directory to a practical use with the following commands!

git init

Click on to initialize a new git directory.

3. Having a change ready to be commited

We make a few changes in our directory that introduce meaningful work that we want to commit. First we need to tell git which files we wanna track - that's what git add <file name> is used for. In our example we use "git add ." where the dot stands for "add all the changes made in the working directory" including new files, modifications and deletions.

git add .

First

Then

3.Creating a commit

We placed new changes in the staging area - now we only need to do "git commit"! In practice, the full version of the command would be: git commit -m "a commit message" to describe what changes the commit introduces. After you hit commit, a new red circle in the "working directory" appears - it shows off of which commit we are currently working off. Then next to the commit you see three things - unique hash number of the commit, branch name "main" for the default branch and arrow representing "HEAD" - the current position that is being displayed in the working directory.

git commit

First

Then

Then

4. Moving around between commits

Ok, we commited a few times but broke the code in the process. Now we want to go back to a previous working commit. Use the input area to place the hash of a commit and hit git checkout. The current branch is gonna say "detached" for "detached head" - we are no longer on a branch! Please note git commit is not yet implemented in the detached head position. Type in "main" to get back to the branch.

git checkout

First

Then

Then

Then
current branch:

git branch, git merge, git rebase, ...

To be continued.

Three stone cutters were asked about their jobs. The first said he was paid to cut stones.

The second one replied he used special techniques to cut stones in an exceptional state-of-the-art way
and proceed to show off his skills.

The third stone cutter just smiled and said: “I build cathedrals”.

wholessence
© 2021