git-sim: see what a Git command will do before you let it do that

A dry run you can look at

git-sim visually simulates Git operations in your own repos with a single terminal command, generating an image by default or a video visualization depicting the Git command's behavior. The design decision that makes it usable is that command syntax is based directly on Git's command-line syntax, so using git-sim is as familiar as possible, git-sim merge with a branch name reads exactly like the command it previews. The use cases the README leads with are protective, visualize Git commands to understand their effects on your repo before actually running them, and prevent unexpected working directory and repository states by simulating before running, which reframes the tool as a safety aid for the commands people fear, rebase, reset, clean, rather than a toy.

Manim does the drawing, and installs first

The rendering engine is Manim, the community maintained mathematical animation library, and the quickstart reflects the dependency order, step one installs Manim and its OS specific dependencies with separate guides for Windows, macOS, Linux and Conda, step two installs git-sim itself:

$ pip3 install git-sim

Then browse to the repository to simulate in and run the program:

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

On macOS the guidance is emphatic, do not use the system Python, install Python through Homebrew or a virtual environment instead, the classic friction point for Manim's native stack. The Docker path sidesteps all of it, an image that apt installs build tools, cairo, pango and ffmpeg, pip installs manim and then git-sim, and sets git-sim as the entrypoint, so the whole visualization stack runs without touching the host. Requirements are Python 3.7 or greater, pip, and Manim Community.

Twenty five subcommands, one grammar

The supported command list reads as Git's own table of contents, 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 and tag, twenty five subcommands covering essentially everything a daily workflow runs, including the modern restore and switch. Help follows Git's conventions too, git-sim -h lists global options and subcommands, git-sim with a subcommand and -h shows that subcommand's options, so the discovery habits a Git user already has transfer without documentation reading. The general invocation is git-sim with global options, a subcommand, and subcommand options, run from inside the repository being simulated.

--animate, and the low-quality flag for patience

Static images are the default because video is expensive, the --animate flag generates an mp4 instead of a jpg, with an honest warning attached, significant performance slowdown, and a recommended workflow of using --low-quality to speed up testing and removing it when ready to generate presentation-quality video. The animation specific features exist for those final renders, custom branded intro and outro sequences for polished output, and adjustable animation speed for pacing. Output format is selectable among jpg, png, mp4 and webm, covering print, web and documentation embedding. The two tier quality approach acknowledges the real usage pattern, iterate cheaply on what the visualization shows, then pay the render cost once for the version that ships.

Dark by default, color by author

Presentation options are few and deliberate. Dark mode is the default with light mode a switch away, matching the terminal aesthetic of the audience. More interesting is --color-by, which colors commits by a parameter such as author via --color-by=author, turning the commit graph into an attribution view where who wrote what becomes visible in the topology itself. Combined with the shareable output formats, the stated use cases include saving visualizations as team documentation to document workflow and prevent recurring issues, and creating static diagrams or dynamic videos to speed up content creation, so the styling options serve documentation and teaching rather than decoration.

git-dummy: repositories to break without consequence

The tool ships with a companion command, git-dummy, that generates a dummy Git repository with a chosen number of branches and commits to simulate operations on, for users without a suitable repo or unwilling to point a simulation at real history. The quickstart shows the pair working together, git-dummy --name="dummy-repo" --branches=3 --commits=10 creates the fixture, and a --no-subdir variant enables the one line version, git-dummy --no-subdir --branches=3 --commits=10 chained directly into a git-sim invocation. git-dummy is a declared dependency in the package metadata, so installing git-sim installs it, and the pair effectively forms a complete Git learning environment, arbitrary history generator plus command visualizer, installable in one pip command.

Every option has an environment variable

Configuration follows a uniform rule, environment variables can be set for any global command-line option, named git_sim_ followed by the option name. The examples show the pattern, git_sim_media_dir pointing output at the Desktop, git_sim_speed set to 2, and boolean flags as git_sim_light_mode=true, with the general form git_sim_option_name=option_value. Precedence is explicit, options specified at the command line override the corresponding environment variable values. Output itself lands in a git-sim_media subdirectory by default, customizable with --media-dir, with files named by the executed subcommand plus a timestamp, so repeated simulations accumulate as a dated history rather than overwriting each other.

Devlands, sponsors, and a tool still pushed daily

The README opens with an announcement that reframes the project's future, the author is working on Devlands, described as the next generation of git-sim and an even more intuitive way to learn and use Git, enabling users to visualize the entire repo, literally walk through the codebase, simulate and run Git commands, and follow a character guided tutorial. git-sim itself remains supported as free and open source software under GPL-2.0, with sponsorship through GitHub Sponsors and Patreon framed as enabling full time work on it and other Git projects. Release tags are older, v0.3.5 from April 2024 after v0.3.2 and v0.3.3 in mid 2023, but the repository was pushed 2026-09-29, so development continues between releases, and the entry point script git-sim maps to the typer based CLI defined in the package.

Editorial conclusion

Use git-sim when a destructive or structural Git command needs a preview, a rebase or reset whose failure mode matters, or when teaching Git to people who learn visually, since the generated diagrams and videos document exactly what a command does to a specific repository. It is the wrong tool for interactive day to day Git, the simulation is a render, not a prompt. Before installing, follow the Manim installation order, the animation engine is the heavyweight dependency and OS specific, prefer Homebrew Python or a virtual environment on macOS over the system interpreter, and use the Docker image when the native dependency stack is unwanted. Note the maintainer's attention has shifted toward Devlands, described as the next generation of git-sim.

Frequently asked questions

Official sources

1. initialcommit-com/git-sim on GitHub
2. Issues
3. License: GPL-2.0
4. README
5. Releases