Visually simulate Git operations in your individual repos

Desk of Contents

Introduction

Regardless of its easy design underneath the hood, Git is a notoriously complicated instrument for brand new devs to study to make use of and perceive. In my view that is as a result of following 3 elements:

1. The broad breadth of ideas that underlie Git’s mannequin (working listing, staging space, object database, Git objects, SHA-1, native repo, distant repo, DAG, branching, merging, and so forth, and so forth, and so forth…)
2. The situational consciousness required to be versatile with Git
3. The big variety of instructions that Git gives

And regardless of repeatedly being instructed by skilled customers that Git is a really “protected” instrument in that it’s truly fairly laborious to lose your work, new Git customers usually function with a low-level of fixed underlying anxiousness that their information shall be misplaced or corrupted round each nook. Additionally it is widespread apply for newbies to repeat total repos earlier than working instructions in case they find yourself in a state they do not know learn how to get better from.

Even intermediate and superior Git customers usually discover themselves in conditions the place they are not 100% positive what the end result of a specific command is perhaps. This normally results in Googling and Stackoverflow to hopefully discover somebody in a parallel state of affairs and extrapolate their answer to your native repo.

This received me fascinated by methods to assist Git customers of all expertise ranges perceive precisely how working a selected Git command will impression their very own native repo earlier than working it. Particularly:

What for those who may simply get a visible image of how any Git command would impression your native repo, with out interrupting your dev workflow?

When –dry-runs aren’t sufficient

Some Git instructions implement a -n or --dry-run flag that allows customers to get some concept of how that command will have an effect on the state of their repository. Though these could be helpful, not all instructions have them, and the purely text-based output could be fairly sparse as is typical of Git’s command-line interface.

Furthermore, many individuals on the market are visible learners and may benefit drastically from a visible strategy to simulating the impression of a Git command earlier than working it.

So as to tackle this, I created Git-Sim – a free and open-source command-line instrument written in Python.

What’s Git-Sim?

Git-Sim is a command-line instrument written in Python that enables Git customers to rapidly and simply generate photographs (and even video animations) illustrating the impression of a Git command could have on the native repo.

For instance, you’ll be able to simulate a git reset of your department to the earlier commit utilizing the next command:

$ git-sim reset HEAD^

Output:

Or, you’ll be able to simulate a Git merge of the department dev into the lively department primary utilizing the next command:

$ git-sim merge dev

Output:

The purpose in these examples is to allow Git customers overview these photographs to make sure that they perceive how the reset/merge will impression their native repo earlier than executing the precise git merge command.

Moreover, these visualizations could be animated utilizing the --animate flag as follows (be mindful the efficiency is considerably slower when animating because the Git-Sim program must generate an mp4 video as output as a substitute of a static jpg picture):

$ git-sim --animate reset HEAD^

Output:

These visualizations could be particularly helpful for notoriously complicated instructions comparable to git reset, git restore, git merge, git rebase, and git cherry-pick, though it by no means hurts to simulate even easier instructions (comparable to git add or git commit), particularly for those who’re a Git beginner or are creating documentation in your crew :D.

Git-Sim Targets

The first aim of Git-Sim is to rapidly and simply create and visualize the results of Git instructions, whereas minimizing interruption to the developer workflow. Extra particularly, Git-Sim ought to:

1. Present a command-line interface so devs can run Git-Sim instantly within the terminal inside their native Git repos
2. Preserve a parallel syntax to Git instructions (subcommands and choices/flags), in order that utilizing Git-Sim is as acquainted as potential
3. Be environment friendly and quick, producing simulated output photographs in a matter of seconds

Future updates and enhancements to Git-Sim will primarily be targeted round these objectives.

What Does Git Sim Do?

Extra usually, Git-Sim permits customers to run terminal instructions within the type:

$ git-sim [global options] <subcommand> [subcommand options]

The [global options] apply to the overarching git-sim simulation itself, together with:

--light-mode: Use a lightweight mode colour scheme as a substitute of default darkish mode.

--animate: As an alternative of outputting a static picture, animate the Git command conduct in a .mp4 video.

--reverse: Show commit historical past within the reverse route.

The [subcommand options] mimic common Git choices particular to the desired subcommand.

See the Git-Sim readme Instructions part for a full record of supported subcommands and choices together with instance simulated output for every subcommand.

Full record of Git-Sim supported instructions

Here’s a record of Git subcommands that may at the moment be simulated with Git-Sim:

• git log
• git standing
• git add
• git restore
• git commit
• git stash
• git department
• git tag
• git reset
• git revert
• git merge
• git rebase
• git cherry-pick

Git-Sim options

• Run a one-liner git-sim command within the terminal to generate a customized Git command visualization (.jpg) out of your repo
• Supported instructions: log, standing, add, restore, commit, stash, department, tag, reset, revert, merge, rebase, cherry-pick
• Generate an animated video (.mp4) as a substitute of a static picture utilizing the --animate flag (observe: important efficiency slowdown, it’s endorsed to make use of --low-quality to hurry up testing and take away when able to generate presentation-quality video)
• Select between darkish mode (default) and light-weight mode
• Animation solely: Add customized branded intro/outro sequences if desired
• Animation solely: Velocity up or decelerate animation velocity as desired

Set up and Run Git-Sim

To put in Git-Sim:

1. Set up Manim and Manim dependencies in your OS
2. Set up git-sim: $ pip3 set up git-sim

To run Git-Sim:

1. Open a command-line terminal
2. cd to the basis listing of your challenge (on the similar stage because the .git folder)
3. Run your Git-Sim command within the type: git-sim [global options] <subcommand> [subcommand options]

This executes Git-Sim with default settings, which is able to create and routinely open a .jpg picture simulating the Git operations in query.

Notice that the output picture file shall be created in a brand new subdirectory inside your challenge, on the path “./git-sim_media/photographs/”

How Does Git-Sim Work?

Git-Sim is an easy Python package deal that makes use of the Manim (Math-animation) Python library. Manim was initially written by Grant Sanderson, a well-liked content material creator of the 3blue1brown math channel. Grant wrote Manim to simply create explanatory math movies utilizing Python code. These movies usually require visualizing graphs, geometries, and equations. Finally, Grant’s authentic codebase was forked and is now maintained because the Manim “group” version.

Git-Sim makes use of Manim to attract the circles, arrows, textual content, department names, and refs that signify the Git objects and operations going down in your repository.

However, earlier than drawing something, Manim must know what to attract. On this context, Git-Sim queries your Git repo utilizing the GitPython library. This permits the Python code to work together together with your Git repo to establish an inventory of commits and related info to attract within the animation.

At the moment Git-Sim does not carry out any “write” operations in your Git repo, regardless of this being potential with GitPython. Git-Sim will solely ever learn info out of your native repo to generate simulated Git command output.

Notice: I’m contemplating including a function sooner or later that may permit the consumer to determine whether or not to execute the precise Git command similtaneously working the Git-Sim simulation. This is able to probably be completed with an non-compulsory command-line flag referred to as --execute, or related.

Contributing to Git-Sim

To this point I’ve simply been engaged on Git-Sim myself, however I might like to have some assist!

Should you’re concerned with contributing to Git-Sim, be at liberty to attain out to me by e mail with any concepts, recommendations, enhancements, function requests, suggestions, set up points, or bugs!

Should you favor to let your code communicate for itself, pull requests are all the time welcome on our GitHub web page.

Abstract

Git-Sim is a command-line instrument written in Python that enables Git customers to rapidly and simply generate photographs (and even video animations) visualizing the impression of a Git command could have on the native repo.

It’s written in Python and primarily leverages the Manim and GitPython dependencies.

The primary aim of the instrument is to permit Git customers of all expertise ranges to totally perceive how executing a Git command will impression the state of their repo, earlier than truly working the command.

Subsequent Steps

Be taught extra and set up Git-Sim now to begin visualizing your Git instructions!

Comply with @initcommit to remain up to date with Git-Sim

If in case you have any questions or recommendations relating to Git-Sim, be at liberty to e mail me at jacob@initialcommit.io.

If you would like to contribute to Git-Sim, pull requests are all the time welcome on our GitHub web page.

Thanks and blissful coding!