Git simulator tool

Git is an essential tool for developers. But certain Git concepts and commands are notoriously difficult for developers to learn, specially if it is the first time.

Git simulator is a command-line tool written in Python that allows Git users to quickly and easily generate images (or even video animations) illustrating the impact of a Git command will have on the local repo.

Visualize Git commands to understand their effects on your repo before actually running them
Prevent unexpected working directory and repository states by simulating before running
Share visualizations (jpg/png image or mp4/webm video) of your Git commands with your team, or the world
Save visualizations as a part of your team documentation to document workflow and prevent recurring issues
Create static Git diagrams (jpg/png) or dynamic animated videos (mp4/webm) to speed up content creation
Help visual learners understand how Git commands work
Combine with bundled command git-dummy to generate a dummy Git repo and then simulate operations on it

Install dependencies

sudo apt update
sudo apt install build-essential python3-dev libcairo2-dev libpango1.0-dev ffmpeg
sudo apt install python3-pip
pip3 install manim

Install git-sim:

pip3 install git-sim

Go to the git repository where you want to simulate the git commands:

cd path/to/git/repo

Run the simulator

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

Note: If you don't have an existing Git repository to simulate commands on, you can generate a dummy Git repo with the desired number of branches and commits to simulate operations on with git-sim:

git-dummy --name="dummy-repo" --branches=3 --commits=10
cd dummy-repo
git-sim [global options] <subcommand> [subcommand options]

That could be useful for teaching purposes.

You can also execute it in a single command:

git-dummy --no-subdir --branches=3 --commits=10 && git-sim [global options] <subcommand> [subcommand options]

Once the process ends, an output will be created as a .jpg file. Output files are named using the subcommand executed combined with a timestamp, and by default are stored in a subdirectory called git-sim_media/.

The location of this subdirectory is customizable using the command line flag --media-dir=path/to/output. Note that when the --animate global flag is used, render times will be much longer and a .mp4 video output file will be produced.

This is the example tested:

git-sim --img-format=jpg checkout origin/feature/update-gstplayer-patch-pie

And this is the output:

Social Media Traffic

Environment variables

They can be set for any global command-line option available in git-sim. All environment variables start with git_sim_ followed by the name of the option.

For instance, the --media-dir option can be set as an environment variable like:

export git_sim_media_dir=~/Desktop

Similarly, the --speed option can be set like:

export git_sim_speed=2

Boolean flags can be set like:

export git_sim_light_mode=true

In general, the syntax is:

export git_sim_option_name=option_value

Troubleshoot

If there are problems with git-sim, I would recommend to run it on Conda

conda create -n my-manim-environment
conda activate my-manim-environment
conda install -c conda-forge manim

Then, follow the steps on Install dependencies and install git-sim.

❯