Visually simulate Git operations in your personal repos

2023-01-22 09:01:36

Image of git-sim: Visually simulate Git operations in your own repos

Desk of Contents

Introduction

Regardless of its easy design underneath the hood, Git is a notoriously complicated device for brand spanking new devs to be taught to make use of and perceive. For my part that is as a result of following 3 elements:

The huge 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…)
The situational consciousness required to be versatile with Git
The big variety of instructions that Git offers

And regardless of repeatedly being instructed by skilled customers that Git is a really “secure” device in that it’s truly fairly exhausting to lose your work, new Git customers usually function with a low-level of fixed underlying nervousness that their information will likely be misplaced or corrupted round each nook. It is usually frequent observe for newbies to repeat total repos earlier than operating instructions in case they find yourself in a state they do not know tips on how to recuperate from.

Even intermediate and superior Git customers usually discover themselves in conditions the place they don’t seem to be 100% certain what the result of a specific command could be. This normally results in Googling and Stackoverflow to hopefully discover somebody in a parallel scenario and extrapolate their answer to your native repo.

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

What in case you might 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 permits customers to get some concept of how that command will have an effect on the state of their repository. Though these will be helpful, not all instructions have them, and the purely text-based output will 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 method to simulating the impression of a Git command earlier than operating it.

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

What’s Git-Sim?

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

For instance, you may simulate a git reset of your department to the earlier commit utilizing the next command:

$ git-sim reset HEAD^

Output:

Or, you may simulate a Git merge of the department dev into the energetic department predominant utilizing the next command:

$ git-sim merge dev

Output:

The purpose in these examples is to allow Git customers evaluation these photos 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 will be animated utilizing the --animate flag as follows (take into account 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 will be particularly helpful for notoriously complicated instructions resembling git reset, git restore, git merge, git rebase, and git cherry-pick, though it by no means hurts to simulate even less complicated instructions (resembling git add or git commit), particularly in case you’re a Git beginner or are creating documentation to your group :D.

Git-Sim Targets

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

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

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

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 coloration scheme as a substitute of default darkish mode.

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

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

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

See the Git-Sim readme Commands section 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: vital 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 lightweight mode
Animation solely: Add customized branded intro/outro sequences if desired
Animation solely: Velocity up or decelerate animation pace as desired

Tips on how to Set up and Run Git-Sim

To put in Git-Sim:

Set up Manim and Manim dependencies to your OS
Set up git-sim: $ pip3 set up git-sim

To run Git-Sim:

Open a command-line terminal
cd to the basis listing of your mission (on the similar stage because the .git folder)
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 mechanically open a .jpg picture simulating the Git operations in query.

Observe that the output picture file will likely be created in a brand new subdirectory inside your mission, on the path “./git-sim_media/photos/”

How Does Git-Sim Work?

Git-Sim is a straightforward Python bundle that makes use of the Manim (Math-animation) Python library. Manim was initially written by Grant Sanderson, a preferred 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 unique codebase was forked and is now maintained because the Manim “neighborhood” version.

Git-Sim makes use of Manim to attract the circles, arrows, textual content, department names, and refs that symbolize the Git objects and operations happening 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 allows 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 would not carry out any “write” operations in your Git repo, regardless of this being doable with GitPython. Git-Sim will solely ever learn info out of your native repo to generate simulated Git command output.

Observe: I’m contemplating including a characteristic sooner or later that can enable the consumer to determine whether or not to execute the precise Git command similtaneously operating the Git-Sim simulation. This might probably be achieved with an elective command-line flag referred to as --execute, or related.

Contributing to Git-Sim

Thus far I’ve simply been engaged on Git-Sim myself, however I would like to have some assist!

If you happen to’re enthusiastic about contributing to Git-Sim, be happy to reach out to me by email with any concepts, solutions, enhancements, characteristic requests, suggestions, set up points, or bugs!

If you happen to choose to let your code converse for itself, pull requests are at all times welcome on our GitHub page.

Abstract

Git-Sim is a command-line device written in Python that enables Git customers to rapidly and simply generate photos (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 principle purpose of the device 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 operating the command.