git-sim

Visually simulate Git operations in your own repos with a single terminal command.

This generates an image (default) or video visualization depicting the Git command's behavior.

Command syntax is based directly on Git's command-line syntax, so using git-sim is as familiar as possible.

Example: $ git-sim merge <branch>

Check out the git-sim release blog post for the full scoop!

Support git-sim

Git-Sim is Free and Open-Source Software (FOSS). Your support will help me work on it (and other Git projects) full time! - Sponsor Git-Sim on GitHub - Support Git-Sim via Patreon

Use cases

• 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

Features

• Run a one-liner git-sim command in the terminal to generate a custom Git command visualization (.jpg) from your repo
• Supported commands: add, branch, checkout, cherry-pick, clean, clone, commit, config, fetch, init, log, merge, mv, pull, push, rebase, remote, reset, restore, revert, rm, stash, status, switch, tag
• Generate an animated video (.mp4) instead of a static image using the --animate flag (note: significant performance slowdown, it is recommended to use --low-quality to speed up testing and remove when ready to generate presentation-quality video)
• Color commits by parameter, such as author with the --color-by=author option
• Choose between dark mode (default) and light mode
• Specify output formats of either jpg, png, mp4, or webm
• Combine with bundled command git-dummy to generate a dummy Git repo and then simulate operations on it
• Animation only: Add custom branded intro/outro sequences if desired
• Animation only: Speed up or slow down animation speed as desired

Quickstart

Note: If you prefer to install git-sim with Docker, skip steps (1) and (2) here and jump to the Docker installation section below, then come back here to step (3).

1) Install Manim and its dependencies for your OS / environment: - Install Manim on Windows - Install Manim on MacOS - Install Manim on Linux - Install Manim in Conda

2) Install git-sim:

$ pip3 install git-sim

Note: For MacOS, it is recommended to NOT use the system Python to install Git-Sim, and instead use Homebrew to install a version of Python to work with Git-Sim. Virtual environments should work too.

3) Browse to the Git repository you want to simulate Git commands in:

$ cd path/to/git/repo

4) Run the program:

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

Optional: If you don't have an existing Git repo to simulate commands on, use the bundled git-dummy command to 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]

Or if you want to do it all in a single command:

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

5) Simulated 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.

6) For convenience, environment variables 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 example, 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:

$ export git_sim_option_name=option_value

Explicitly specifying options at the command-line takes precedence over the corresponding environment variable values.

7) See global help for list of global options/flags and subcommands:

$ git-sim -h

8) See subcommand help for list of options/flags for a specific subcommand:

$ git-sim <subcommand> -h

Requirements

• Python 3.7 or greater
• Pip (Package manager for Python)
• Manim (Community version)

Commands

Basic usage is similar to Git itself - git-sim takes a familiar set of subcommands including "add", "branch", "checkout", "cherry-pick", "clean", "clone", "commit", "config", "fetch", "init", "log", "merge", "mv", "pull", "push", "rebase", "remote", "reset", "restore", "revert", "rm", "stash", "status", "switch", "tag" along with corresponding options.

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

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

-n <number>: Number of commits to display from each branch head.
--all: Display all local branches in the log output.
--animate: Instead of outputting a static image, animate the Git command behavior in a .mp4 video.
--color-by author: Color commits by parameter, such as author.
--invert-branches: Invert positioning of branches by reversing order of multiple parents where applicable.
--hide-merged-branches: Hide commits from merged branches, i.e. only display mainline commits.
--media-dir: The path at which to store the simulated output media files.
-d: Disable the automatic opening of the image/video file after generation. Useful to avoid errors in console mode with no GUI.
--light-mode: Use a light mode color scheme instead of default dark mode.
--reverse, -r: Display commit history in the reverse direction.
--img-format: Output format for the image file, i.e. jpg or png. Default output format is jpg.
--stdout: Write raw image data to stdout while suppressing all other program output.
--output-only-path: Only output the path to the generated media file to stdout. Useful for other programs to ingest.
--quiet, -q: Suppress all output except errors.
--highlight-commit-messages: Make commit message text bigger and bold, and hide commit ids.
--style: Graphical style of the output image or animated video, i.e. clean (default) or thick.

Animation-only global options (to be used in conjunction with --animate):

--video-format: Output format for the video file, i.e. mp4 or webm. Default output format is mp4.
--speed=n: Set the multiple of animation speed of the output simulation, n can be an integer or float, default is 1.5.
--low-quality: Render the animation in low quality to speed up creation time, recommended for non-presentation use.
--show-intro: Add an intro sequence with custom logo and title.
--show-outro: Add an outro sequence with custom logo and text.
--title=title: Custom title to display at the beginning of the animation.
--logo=logo.png: The path to a custom logo to use in the animation intro/outro.
--outro-top-text: Custom text to display above the logo during the outro.
--outro-bottom-text: Custom text to display below the logo during the outro.
--font: Font family used to display rendered text.

The [subcommand options] are like regular Git options specific to the specified subcommand (see below for a full list).

The following is a list of Git commands that can be simulated and their corresponding options/flags.

git add

Usage: git-sim add <file 1> <file 2> ... <file n>

• Specify one or more <file> as a modified working directory file, or an untracked file
• Simulated output will show files being moved to the staging area
• Note that simulated output will also show the most recent 5 commits on the active branch

git branch

Usage: git-sim branch <new branch name>

• Specify <new branch name> as the name of the new branch to simulate creation of
• Simulated output will show the newly create branch ref along with most recent 5 commits on the active branch

git checkout

Usage: git-sim checkout [-b] <branch>

• Checks out <branch> into the working directory, i.e. moves HEAD to the specified <branch>
• The -b flag creates a new branch with the specified name <branch> and checks it out, assuming it doesn't already exist

git cherry-pick

Usage: git-sim cherry-pick <commit>

• Specify <commit> as a ref (branch name/tag) or commit ID to cherry-pick onto the active branch
• Supports editing the cherry-picked commit message with: $ git-sim cherry-pick <commit> -e "Edited commit message"

git clean

Usage: git-sim clean

• Simulated output will show untracked files being deleted
• Since this is just a simulation, no need to specify -i, -n, -f as in regular Git
• Note that simulated output will also show the most recent 5 commits on the active branch

git clone

Usage: git-sim clone <url>

• Clone the remote repo from <url> (web URL or filesystem path) to a new folder in the current directory
• Output will report if clone operation is successful and show log of local clone

git commit

Usage: git-sim commit -m "Commit message"

• Simulated output will show the new commit added to the tip of the active branch
• Specify a commit message with the -m option
• HEAD and the active branch will be moved to the new commit
• Simulated output will show files in the staging area being included in the new commit
• Supports amending the last commit with: $ git-sim commit --amend -m "Amended commit message"

git config

Usage: git-sim config [--list] <section.option> <value>

• Simulated output describes the specified configuration change
• Use --list or -l to display all configuration

git fetch

Usage: git-sim fetch <remote> <branch>

• Fetches the specified <branch> from the specified <remote> to the local repo

git init

Usage: git-sim init

• Simulated output describes the initialized .git/ directory and it's contents

![git-sim-init_04-16-24_08-34-47](https