CLI tool
initialcommit-com/git-sim avatar
initialcommit-com/git-sim

git-sim: rendering Git commands as images and video before you run them

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

4,695 stars127 forksPythonGPL-2.0

At a glance

What is it?
git-sim turns a Git command into an interactive graph of your repository, so you can see what a merge or rebase would do before it touches your working tree. It is a teaching and documentation tool, not a replacement for git.
Who is it for?
Adopt git-sim if you teach Git, write documentation, or want a picture of a merge or rebase before running it. Skip it if you need an online playground; the tool renders media, it does not execute the command.
Can I use it commercially?
Yes, with conditions. GPL-2.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
Is it still maintained?
Yes. The repository last received commits 34 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • initialcommit-com/git-sim4,695 ★ · +10
Star history
Repository2026-09-232026-11-15
initialcommit-com/git-sim4.7k4.7k

10 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What git-sim actually solves, and for whom

Git's command line tells you what happened after the fact. A rebase that reorders commits, a cherry-pick that lands on the wrong parent, a reset that moves a branch pointer: the result is a graph, and the graph is what most people cannot hold in their head. git-sim exists to draw that graph. The README describes it as "the visual layer for Git in your own repos," for simulating, recording, replaying, auditing and sharing individual Git commands or entire Git workflows.

The audience follows from that. Instructors and people writing tutorials get static diagrams or short animations without hand-drawing them. Developers who are new to rebase or cherry-pick get a preview. Teams that keep a runbook can attach a rendered image of the exact command they recommend. The README also points at a companion command, git-dummy, which creates Git repos in whatever structure you want to play with, so you can simulate against something disposable rather than your real history.

One thing to be clear about: git-sim is not a dry run in the sense of a conflict check. It renders what the command means for the commit graph. For risk, the README points to git-sim preflight, which reports how risky a command is and what you could lose.

How the rendering pipeline is put together

The dependency list in pyproject.toml is the clearest description of the architecture. gitpython reads the repository, skia-python renders static images, fonttools handles fonts, mcp provides the MCP server, manim and opencv-python-headless are an optional extra for animated video, typer provides the command-line interface, pydantic_settings backs the configuration and environment variables, and git-dummy is pulled in as a runtime dependency so the bundled dummy-repo command is always available.

That stack explains both the strengths and the costs. Because Manim is only needed for animated video (--animate), the default install renders without it, and the README lists MP4 video among the formats a visualization can be shared as. Because gitpython is the reader, git-sim works on your local repository, not on a remote service, so nothing is uploaded.

The command surface is deliberately Git-shaped. Command syntax is based directly on Git's own command-line syntax, so git-sim merge <branch> mirrors git merge <branch>. The README says to prefix any Git command with git-sim instead of git, and git-sim -h lists all commands.

Installing git-sim and producing your first diagram

The README's requirements are Windows, macOS or Linux, Python 3.10 to 3.14, and Git; animated video (--animate) needs Manim. Minimal Linux distros may also need libEGL, libGL and fontconfig.

The package installs from PyPI:

bash
pip3 install git-sim

Then move into the repository you want to visualize and run the command with Git's own argument shape:

bash
cd path/to/git/repo
git-sim merge <branch>

The README states that by default git-sim creates a web-first, shareable visualization that opens in your browser, without running the real Git command. The page is also saved locally; the Dockerfile notes git-sim saves to the user's cache folder by default and uses the git_sim_media_dir environment variable to put git-sim_media elsewhere. Animated video needs --animate and Manim.

If you have no repository to experiment on, git-dummy creates one. The README gives this example:

bash
git-dummy --scenario orders

Global options can also be set as environment variables. The README's convention is the prefix git_sim_ followed by the option name, so --open-in local can be set as git_sim_open_in=local, and the Dockerfile sets git_sim_media_dir:

bash
export git_sim_media_dir=~/Desktop

There is also a Dockerfile for a container-based install, built on python:3.14; it installs libegl1, libgl1, libfontconfig1 and fonts-dejavu-core plus build-essential, python3-dev, libcairo2-dev, libpango1.0-dev and ffmpeg, then pip3 install "git-sim[extras]", with git-sim as the entrypoint.

Where git-sim stops being the right tool

Animated video is the heavier path: --animate needs Manim, which the Dockerfile notes builds against cairo and pango and records with FFmpeg. For a quick look at a graph, the default interactive graph is the sensible choice, and animation is for material you intend to present or publish. Planning around that distinction saves a lot of waiting.

The second constraint is coverage: run git-sim -h to list all commands before relying on a specific one.

The third is conceptual. git-sim visualizes commit topology. For risk, the README points to git-sim preflight, which reports how risky a command is and what you could lose. A clean-looking diagram is not a guarantee that the command will succeed, and treating it as one is the main way to misuse the tool. For a genuinely risky operation on shared history, the safer habit is still a throwaway clone or a scratch branch.

The repository is not archived and the last push was on 2026-10-12.

git-sim compared with a browser playground and with plain git log

The closest everyday alternative is an online Git playground, the kind of sandbox where you type commands against a fake repository in a browser tab. The difference in approach is ownership of the repository. A playground gives you a synthetic repo and a fixed interface, which is fine for learning the vocabulary of commit, branch and merge. git-sim runs against your own repository through gitpython, so the graph you see is your history, with your branch names and your commit messages. That is the whole point for documentation and for debugging a real merge, and it is impossible in a hosted sandbox unless you upload your repo.

The other alternative is the tool you already have: git log --graph --oneline --all. It is instant, it needs no dependencies, and it is text. What it cannot do is show you the state after a command you have not run yet, and it cannot produce a shareable image or a short animation for a slide deck. git-sim's value is concentrated in those two gaps.

Between the two, the trade is dependencies for presentation. A playground or git log costs you nothing to install. git-sim costs you a Python environment (plus Manim for animated video), and in exchange you get a media file that depicts a hypothetical command on a real repository.

Licence, maintenance and the cost of upgrading

git-sim is GPL-2.0, and pyproject.toml declares license = { text = "GPL-2.0" } with the matching classifier for GNU General Public License v2. The practical consequence for most users is minimal, because you are invoking a command-line tool, not linking a library into your own code. If you intend to modify git-sim and distribute the result, or to embed it in a product, the copyleft terms of GPL-2.0 apply and are worth reading in full. That is a description of the licence, not legal advice.

On maintenance, the facts are narrow. The repository is not archived, and the last push was on 2026-10-12. The most recent tagged release listed is v0.4.0 from 2026-10-10, with v0.3.5 (2024-04-16) and v0.3.3 before it. Anyone tracking versions should note that the release cadence and the commit activity are not the same thing.

Upgrade cost is dominated by dependencies rather than by git-sim itself. Because Manim (needed for --animate) in turn needs system libraries such as cairo, pango and ffmpeg (the Dockerfile installs libcairo2-dev, libpango1.0-dev and ffmpeg), a Python or Manim upgrade can be more disruptive than a git-sim upgrade. The declared floor is requires-python = ">=3.10". If you install inside a virtual environment, you can pin and rebuild that environment without disturbing the rest of the machine, which is the cheapest way to absorb a broken dependency.

Editorial conclusion

Adopt git-sim if you teach Git, write documentation, or want a picture of a merge or rebase before running it. Skip it if you need an online playground; the tool renders media, it does not execute the command. Before relying on it, check git-sim -h for your command and verify that your Python is 3.10 or newer, since pyproject.toml sets requires-python = ">=3.10".

Frequently asked questions

How do I install git-sim?

Run pip install git-sim (or pipx install git-sim, or uv tool install git-sim); Manim is only needed for animated video with --animate. The repository also provides a Dockerfile that installs the required system packages and git-sim[extras], with git-sim as the container entrypoint.

Which Git commands can git-sim simulate?

The README says to prefix any Git command with git-sim instead of git, with examples such as git-sim merge dev, git-sim reset --hard HEAD^ and git-sim rebase main, and git-sim -h lists all commands. Command syntax follows Git's own command-line syntax, so git-sim merge <branch> mirrors git merge <branch>.

Does git-sim need Manim installed separately?

Only for animated video. The README says --animate needs Manim, and pyproject.toml puts manim in the optional extras group (git-sim[extras]); the core install uses skia-python for static images. The Dockerfile installs git-sim[extras].

Where does git-sim put the generated image or video?

By default git-sim opens an interactive graph in your browser and also saves the page locally, with a filename built from the command and a timestamp. The Dockerfile notes git-sim saves to the user's cache folder by default, and the git_sim_media_dir environment variable puts the git-sim_media folder elsewhere.

Official sources

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

Where developers are discussing it

Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 0 in the last 30 days; newest first.

Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/initialcommit-com-git-sim.svg)](https://hysenlabs.com/projects/initialcommit-com-git-sim)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/initialcommit-com-git-sim.svg)](https://hysenlabs.com/projects/initialcommit-com-git-sim)

Was this useful?