Package: git-sim
git-simVisually 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>Use casesVisualize Git commands to understand their effects on your repo before actually running themPrevent unexpected working directory and repository states by simulating before runningShare visualizations (jpg/png image or mp4/webm video) of your Git commands with your team, or the worldSave visualizations as a part of your team documentation to document workflow and prevent recurring issuesCreate static Git diagrams (jpg/png) or dynamic animated videos (mp4/webm) to speed up content creationHelp visual learners understand how Git commands workCombine with bundled commandgit-dummyto generate a dummy Git repo and then simulate operations on itFeaturesRun a one-liner git-sim command in the terminal to generate a custom Git command visualization (.jpg) from your repoSupported commands:log,status,add,restore,commit,stash,branch,tag,reset,revert,merge,rebase,cherry-pick,switch,checkout,fetch,pull,push,clone,rm,mv,cleanGenerate an animated video (.mp4) instead of a static image using the--animateflag (note: significant performance slowdown, it is recommended to use--low-qualityto speed up testing and remove when ready to generate presentation-quality video)Color commits by parameter, such as author with the--color-by=authoroptionChoose between dark mode (default) and light modeSpecify output formats of either jpg, png, mp4, or webmCombine with bundled commandgit-dummyto generate a dummy Git repo and then simulate operations on itAnimation only: Add custom branded intro/outro sequences if desiredAnimation only: Speed up or slow down animation speed as desiredQuickstartNote: If you prefer to install git-sim with Docker, skip steps (1) and (2) here and jump to theDocker installationsection below, then come back here to step (3).Install Manim and its dependencies for your OS / environment:Install Manim on WindowsInstall Manim on MacOSInstall Manim on LinuxInstall Manim in CondaInstallgit-sim:$pip3installgit-simNote: For MacOS, it is recommended toNOTuse the system Python to install Git-Sim, and instead useHomebrewto install a version of Python to work with Git-Sim. Virtual environments should work too.Browse to the Git repository you want to simulate Git commands in:$cdpath/to/git/repoRun the program:$git-sim[globaloptions]<subcommand>[subcommandoptions]Optional: If you don't have an existing Git repo to simulate commands on, use the bundledgit-dummycommand 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$cddummy-repo$git-sim[globaloptions]<subcommand>[subcommandoptions]Or if you want to do it all in a single command:$git-dummy--no-subdir--branches=3--commits=10&&git-sim[globaloptions]<subcommand>[subcommandoptions]Simulated output will be created as a.jpgfile. Output files are named using the subcommand executed combined with a timestamp, and by default are stored in a subdirectory calledgit-sim_media/. The location of this subdirectory is customizable using the command line flag--media-dir=path/to/output. Note that when the--animateglobal flag is used, render times will be much longer and a.mp4video output file will be produced.For convenience, environment variables can be set for any global command-line option available in git-sim. All environment variables start withgit_sim_followed by the name of the option.For example, the--media-diroption can be set as an environment variable like:$exportgit_sim_media_dir=~/DesktopSimilarly, the--speedoption can be set like:$exportgit_sim_speed=2Boolean flags can be set like:$exportgit_sim_light_mode=trueIn general:$exportgit_sim_option_name=option_valueExplicitly specifying options at the command-line takes precedence over the corresponding environment variable values.See global help for list of global options/flags and subcommands:$git-sim-hSee subcommand help for list of options/flags for a specific subcommand:$git-sim<subcommand>-hRequirementsPython 3.7 or greaterPip (Package manager for Python)Manim (Community version)CommandsBasic usage is similar to Git itself -git-simtakes a familiar set of subcommands including "log", "status", "add", "restore", "commit", "stash", "branch", "tag", "reset", "revert", "merge", "rebase", "cherry-pick", "switch", "checkout", "fetch", "pull", "push", "clone", "rm", "mv", "clean" along with corresponding options.$git-sim[globaloptions]<subcommand>[subcommandoptions]The[global options]apply to the overarchinggit-simsimulation 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.jpgorpng. Default output format isjpg.--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) orthick.Animation-only global options (to be used in conjunction with--animate):--video-format: Output format for the video file, i.e.mp4orwebm. Default output format ismp4.--speed=n: Set the multiple of animation speed of the output simulation,ncan 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.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 logUsage:git-sim log [-n <number>] [--all]Simulated output will show the most recent 5 commits on the active branch by defaultUse-n <number>to set number of commits to display from each branch headSet--allto display all local branches in the log outputgit statusUsage:git-sim statusSimulated output will show the state of the working directory, staging area, and untracked filesNote that simulated output will also show the most recent 5 commits on the active branchgit addUsage:git-sim add <file 1> <file 2> ... <file n>Specify one or more<file>as amodifiedworking directory file, or an untracked fileSimulated output will show files being moved to the staging areaNote that simulated output will also show the most recent 5 commits on the active branchgit restoreUsage:git-sim restore <file 1> <file 2> ... <file n>Specify one or more<file>as amodifiedworking directory file, or staged fileSimulated output will show files being moved back to the working directory or discarded changesNote that simulated output will also show the most recent 5 commits on the active branchgit commitUsage:git-sim commit -m "Commit message"Simulated output will show the new commit added to the tip of the active branchSpecify a commit message with the-moptionHEAD and the active branch will be moved to the new commitSimulated output will show files in the staging area being included in the new commitSupports amending the last commit with:$ git-sim commit --amend -m "Amended commit message"git stashUsage:git-sim stash [push|pop|apply] <file>Specify one or more<file>as amodifiedworking directory file, or staged fileIf no<file>is specified, all available files will be includedSimulated output will show files being moved in/out of the Git stashNote that simulated output will also show the most recent 5 commits on the active branchgit branchUsage:git-sim branch <new branch name>Specify<new branch name>as the name of the new branch to simulate creation ofSimulated output will show the newly create branch ref along with most recent 5 commits on the active branchgit tagUsage:git-sim tag <new tag name>Specify<new tag name>as the name of the new tag to simulate creation ofSimulated output will show the newly create tag ref along with most recent 5 commits on the active branchgit resetUsage:git-sim reset <reset-to> [--mixed|--soft|--hard]Specify<reset-to>as any commit id, branch name, tag, or other ref to simulate reset to from the current HEAD (default:HEAD)As with a normal git reset command, default reset mode is--mixed, but can be specified using--soft,--hard, or--mixedSimulated output will show branch/HEAD resets and resulting state of the working directory, staging area, and whether any file changes would be deleted by running the actual commandgit revertUsage:git-sim revert <to-revert>Specify<to-revert>as any commit id, branch name, tag, or other ref to simulate revert forSimulated output will show the new commit which reverts the changes from<to-revert>Simulated output will include the next 4 most recent commits on the active branchgit mergeUsage:git-sim merge <branch> [-m "Commit message"] [--no-ff]Specify<branch>as the branch name to merge into the active branchIf desired, specify a commit message with the-moptionSimulated output will depict a fast-forward merge if possibleOtherwise, a three-way merge will be depictedTo force a merge commit when a fast-forward is possible, use--no-ffIf merge fails due to merge conflicts, the conflicting files are displayedgit rebaseUsage:git-sim rebase <new-base>Specify<new-base>as the branch name to rebase the active branch ontogit cherry-pickUsage:git-sim cherry-pick <commit>Specify<commit>as a ref (branch name/tag) or commit ID to cherry-pick onto the active branchSupports editing the cherry-picked commit message with:$ git-sim cherry-pick <commit> -e "Edited commit message"git switchUsage:git-sim switch [-c] <branch>Switches the checked-out branch to<branch>, i.e. movesHEADto the specified<branch>The-cflag creates a new branch with the specified name<branch>and switches to it, assuming it doesn't already existgit checkoutUsage:git-sim checkout [-b] <branch>Checks out<branch>into the working directory, i.e. movesHEADto the specified<branch>The-bflag creates a new branch with the specified name<branch>and checks it out, assuming it doesn't already existgit fetchUsage:git-sim fetch <remote> <branch>Fetches the specified<branch>from the specified<remote>to the local repogit pullUsage:git-sim pull [<remote> <branch>]Pulls the specified<branch>from the specified<remote>to the local repoIf<remote>and<branch>are not specified, the active branch is pulled from the default remoteIf merge conflicts occur, they are displayed in a tablegit pushUsage:git-sim push [<remote> <branch>]Pushes the specified<branch>to the specified<remote>and displays the local resultIf<remote>and<branch>are not specified, the active branch is pushed to the default remoteIf the push fails due to remote changes that don't exist in the local repo, a message is included telling the user to pull first, along with color coding which commits need to be pulledgit cloneUsage:git-sim clone <url>Clone the remote repo from<url>(web URL or filesystem path) to a new folder in the current directoryOutput will report if clone operation is successful and show log of local clonegit rmUsage:git-sim rm <file 1> <file 2> ... <file n>Specify one or more<file>as atrackedfileSimulated output will show files being removed from Git trackingNote that simulated output will also show the most recent 5 commits on the active branchgit mvUsage:git-sim mv <file> <new file>Specify<file>as file to update name/pathSpecify<new file>as new name/path of fileSimulated output will show the name/path of the file being updatedNote that simulated output will also show the most recent 5 commits on the active branchgit cleanUsage:git-sim cleanSimulated output will show untracked files being deletedSince this is just a simulation, no need to specify-i,-n,-fas in regular GitNote that simulated output will also show the most recent 5 commits on the active branchVideo animation examples$git-sim--animateresetHEAD^https://user-images.githubusercontent.com/49353917/210943230-f38d879b-bb0d-4d42-a196-f24efb9e351a.mp4$gitcheckoutmain$git-sim--animatemergedevhttps://user-images.githubusercontent.com/49353917/210943418-22c2cd11-be96-41bc-b621-7018eebc6bc0.mp4$gitcheckoutdev$git-sim--animaterebasemainhttps://user-images.githubusercontent.com/49353917/210943815-4b8be2da-18da-4c42-927a-61cf9a22834e.mp4$gitcheckoutmain$git-sim--animatecherry-pickdevhttps://user-images.githubusercontent.com/49353917/210944001-77bd0130-306b-40a8-ba0b-22e50172802b.mp4Basic command examplesSimulate the output of the git log command:$cdpath/to/git/repo$git-simlogSimulate the output of the git status command:$git-simstatusSimulate adding a file to the Git staging area:$git-simaddfilename.extSimulate restoring a file from the Git staging area:$git-simrestorefilename.extSimulate creating a new commit based on currently staged changes:$git-simcommit-m"Commit message"Simulate stashing all working directory and staged changes:$git-simstashSimulate creating a new Git branch:$git-simbranchnew-branch-nameSimulate creating a new Git tag:$git-simtagnew-tag-nameSimulate a hard reset of the current branch HEAD to the previous commit:$git-simresetHEAD^--hardSimulate reverting the changes in an older commit:$git-simrevertHEAD~7Simulate merging a branch into the active branch:$git-simmergefeature1Simulate rebasing the active branch onto a new base:$git-simrebasemainSimulate cherry-picking a commit from another branch onto the active branch:$git-simcherry-pick0ae641Command examples with extra options/flagsUse light mode for white background and black text, instead of the default black background with white text:$git-sim--light-modestatusAnimate the simulated output as a .mp4 video file:$git-sim--animateaddfilename.extAdd 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.pngstatusCustomize the output image/video directory location:$git-sim--media-dir=path/to/outputstatusOptionally, set the environment variablegit_sim_media_dirto set a global default media directory, to be used if no--media-diris provided. Simulated output images/videos will be placed in this location, in subfolders named with the corresponding repo's name.$exportgit_sim_media_dir=path/to/media/directory$git-simstatusNote:--media-dirtakes 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-qualitystatusInstallationSeeQuickstartsection for details on installing manim and other dependencies. Then run:$pip3installgit-simDocker installationClone down the git-sim repository:$gitclonehttps://github.com/initialcommit-com/git-sim.gitBrowse into thegit-simfolder and build the Docker image:$dockerbuild-tgit-sim.Run git-sim commands as follows:Windows:docker run --rm -v %cd%:/usr/src/git-sim git-sim [global options] <subcommand> [subcommand options]MacOS / Linux: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 normalgit-simcommand. To do so add the following line to your.bashrcor equivalent, then restart your terminal:git-sim(){dockerrun--rm-v$(pwd):/usr/src/git-simgit-sim"$@";}This will enable you to run git-sim subcommands asdescribed above.Learn MoreLearn more about this tool on thegit-sim project page.AuthorsJacob Stopak- on behalf ofInitial Commit