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!
Git-Sim is Free and Open-Source Software (FOSS). Your support will help me work on it (and other Git projects) full time!
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
--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-by=author
optionNote: 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:
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
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.
Usage: git-sim add <file 1> <file 2> ... <file n>
<file>
as a modified working directory file, or an untracked fileUsage: git-sim branch <new branch name>
<new branch name>
as the name of the new branch to simulate creation ofUsage: git-sim checkout [-b] <branch>
<branch>
into the working directory, i.e. moves HEAD
to the specified <branch>
-b
flag creates a new branch with the specified name <branch>
and checks it out, assuming it doesn't already existUsage: git-sim cherry-pick <commit>
<commit>
as a ref (branch name/tag) or commit ID to cherry-pick onto the active branch$ git-sim cherry-pick <commit> -e "Edited commit message"
Usage: git-sim clean
-i
, -n
, -f
as in regular GitUsage: git-sim clone <url>
<url>
(web URL or filesystem path) to a new folder in the current directoryUsage: git-sim commit -m "Commit message"
-m
option$ git-sim commit --amend -m "Amended commit message"
Usage: git-sim config [--list] <section.option> <value>
--list
or -l
to display all configurationUsage: git-sim fetch <remote> <branch>
<branch>
from the specified <remote>
to the local repoUsage: git-sim init
.git/
directory and it's contentsUsage: git-sim log [-n <number>] [--all]
-n <number>
to set number of commits to display from each branch head--all
to display all local branches in the log outputUsage: git-sim merge <branch> [-m "Commit message"] [--no-ff]
<branch>
as the branch name to merge into the active branch-m
option--no-ff
Usage: git-sim mv <file> <new file>
<file>
as file to update name/path<new file>
as new name/path of file Usage: git-sim pull [<remote> <branch>]
<branch>
from the specified <remote>
to the local repo<remote>
and <branch>
are not specified, the active branch is pulled from the default remoteUsage: git-sim push [<remote> <branch>]
<branch>
to the specified <remote>
and displays the local result<remote>
and <branch>
are not specified, the active branch is pushed to the default remoteUsage: git-sim rebase <new-base>
<new-base>
as the branch name to rebase the active branch ontoUsage: git-sim remote [add|rename|remove|get-url|set-url] [<remote>] [<url>]
git-sim remote
with no options will list all existing remotes and their details Usage: git-sim reset <reset-to> [--mixed|--soft|--hard]
<reset-to>
as any commit id, branch name, tag, or other ref to simulate reset to from the current HEAD (default: HEAD
)--mixed
, but can be specified using --soft
, --hard
, or --mixed
Usage: git-sim restore <file 1> <file 2> ... <file n>
<file>
as a modified working directory file, or staged fileUsage: git-sim revert <to-revert>
<to-revert>
as any commit id, branch name, tag, or other ref to simulate revert for<to-revert>
Usage: git-sim rm <file 1> <file 2> ... <file n>
<file>
as a tracked fileUsage: git-sim stash [push|pop|apply] <file>
<file>
as a modified working directory file, or staged file<file>
is specified, all available files will be includedUsage: git-sim status
Usage: git-sim switch [-c] <branch>
<branch>
, i.e. moves HEAD
to the specified <branch>
-c
flag creates a new branch with the specified name <branch>
and switches to it, assuming it doesn't already existUsage: git-sim tag <new tag name>
<new tag name>
as the name of the new tag to simulate creation of$ git-sim --animate reset HEAD^
$ git checkout main
$ git-sim --animate merge dev
$ git checkout dev
$ git-sim --animate rebase main
$ git checkout main
$ git-sim --animate cherry-pick dev
Simulate the output of the git log command:
$ cd path/to/git/repo
$ git-sim log
Simulate the output of the git status command:
$ git-sim status
Simulate adding a file to the Git staging area:
$ git-sim add filename.ext
Simulate restoring a file from the Git staging area:
$ git-sim restore filename.ext
Simulate creating a new commit based on currently staged changes:
$ git-sim commit -m "Commit message"
Simulate stashing all working directory and staged changes:
$ git-sim stash
Simulate creating a new Git branch:
$ git-sim branch new-branch-name
Simulate creating a new Git tag:
$ git-sim tag new-tag-name
Simulate a hard reset of the current branch HEAD to the previous commit:
$ git-sim reset HEAD^ --hard
Simulate reverting the changes in an older commit:
$ git-sim revert HEAD~7
Simulate merging a branch into the active branch:
$ git-sim merge feature1
Simulate rebasing the active branch onto a new base:
$ git-sim rebase main
Simulate cherry-picking a commit from another branch onto the active branch:
$ git-sim cherry-pick 0ae641
Use light mode for white background and black text, instead of the default black background with white text:
$ git-sim --light-mode status
Animate the simulated output as a .mp4 video file:
$ git-sim --animate add filename.ext
Add an intro and outro with custom text and logo (must include --animate
):
$ git-sim --animate --show-intro --show-outro --outro-top-text="My Git Repo" --outro-bottom-text="Thanks for watching!" --logo=path/to/logo.png status
Customize the output image/video directory location:
$ git-sim --media-dir=path/to/output status
Optionally, set the environment variable git_sim_media_dir
to set a global default media directory, to be used if no --media-dir
is provided. Simulated output images/videos will be placed in this location, in subfolders named with the corresponding repo's name.
$ export git_sim_media_dir=path/to/media/directory
$ git-sim status
Note: --media-dir
takes precedence over the environment variable. If you set the environment variable and still provide the argument, you'll find the media in the path provided by --media-dir
.
Generate output video in low quality to speed up rendering time (useful for repeated testing, must include --animate
):
$ git-sim --animate --low-quality status
See Quickstart section for details on installing manim and other dependencies. Then run:
$ pip3 install git-sim
1) Clone down the git-sim repository:
$ git clone https://github.com/initialcommit-com/git-sim.git
2) Browse into the git-sim
folder and build the Docker image:
$ docker build -t git-sim .
3) Run git-sim commands as follows:
docker run --rm -v %cd%:/usr/src/git-sim git-sim [global options] <subcommand> [subcommand options]
docker run --rm -v $(pwd):/usr/src/git-sim git-sim [global options] <subcommand> [subcommand options]
Optional: On MacOS / Linux / or GitBash in Windows, create an alias for the long docker command so your can run it as a normal git-sim
command. To do so add the following line to your .bashrc
or equivalent, then restart your terminal:
git-sim() { docker run --rm -v $(pwd):/usr/src/git-sim git-sim "$@"; }
This will enable you to run git-sim subcommands as described above.
Learn more about this tool on the git-sim project page.
Jacob Stopak - on behalf of Initial Commit