TL;DR https://gitmachine.zubin.io is an interactive demo that models the local change management process in Git repositories.

I recently leveraged xstate, to build a finite state machine that models how local changes are managed in a git repository. This little experiment quickly turned into an interactive demo that allows users to issue actions (some simple git-related terminal commands) and behold the resulting state.

A finite state machine represents (or models) a dynamic system as two or more discrete states, each characterized by rules governing whether they are allowed (or disallowed) to transition to one state or another. A canonical example of this is a basic traffic light, which is always in one of the following three states: green, yellow or red. A green light cannot transition directly to a red light. It must first transition to a yellow light. Similarly, the red light can never transition to the yellow light. It can only transition to the green light. In this analogy, the color of the light represents a discrete state, to use the parlance of finite state machines.

Similar to the basic traffic light model, local changes in a git repository must fall into one of a set of discrete states: clean (no changes), un-staged, staged, or committed. If you click on an example command (left hand panel), the corresponding state will be highlighted. The command will also display in the mock terminal panel (right-hand panel), so you can view the order of actions, as if it was your command-line history.

Remember, certain commands cannot change the state, depending on what the current state is. Even if you are very comfortable using git on a daily basis, you might still be unfamiliar with the low-level details of how You may even be vaguely aware that you can’t affect a change using certain commands, while in certain states, even if you’re not sure the exact reason. For example, you can NOT checkout a change:

git checkout .

…if the change has already been staged using the following command:

git add new_file.txt

In the above scenario, the file is currently in the staged state, and in order to move the change back to the un-staged state, you would have to run:

git reset .

Unfortunately, this interactive demo (in its current state) does a poor job of indicating what states are available to transition to. Consequently, this is also a source of confusion for developers using Git! In the future, I might add an icon or indicator to suggest that a command is either enabled or disabled for a given state of the machine.

As a last note, another command that I did not account for in this interactive demo is git stash, only because stashing changes actually creates a whole new state machine, separate from (or embedded within) the currently implemented state machine. In the future, I might add a second state machine (representing the stashing process) that would allow users to volley between the currently implementation and a new (secondary) state machine that models how stashes work. In any case, you can play around with this demo here: https://gitmachine.zubin.io

// Hmm how to embed youtube. youtube