Update readme and setup

Signed-off-by: Jacob Stopak <jacob@initialcommit.io>

Author: initialcommit-io

README.md

@@ -1,21 +1,23 @@
 # git-sim
-Simulate git commands on your own repos by generating a .mp4 visualization before running the actual command.
+Simulate Git commands on your own repos by generating an image (default) or video visualization depicting the command's behavior.
 
 ## Use cases
-- Visualizing Git commands before running them to understand the effect
-- Sharing desired parts of your workflow with your team
-- Creating animated Git videos for blog posts or YouTube
-- Helping newer developers learn Git
+- Visualize Git commands to understand their effects on your repo before actually running them
+- Share visualizations of your Git workflow with your team, or the world
+- Create static Git diagrams or dynamic animated videos for your content
+- Save visualizations as a part of your teams documentation to prevent recurring issues
+- Help newer developers learn Git
 
 ## Features
-- Run a one-liner git-sim command in the terminal to generate a custom Git command visualization (.mp4) in your repo
-- Speed up or slow down animation speed as desired
-- Add custom branded intro/outro sequences if desired
+- Run a one-liner git-sim command in the terminal to generate a custom Git command visualization (.jpg) from your repo
+- Supported commands: `status`, `add`, `branch`, `tag`, `reset`, `revert`
+- Generate an animated video (.mp4) instead of a static image using the `--animate` flag (note: significant performance slowdown)
 - Choose between dark mode (default) and light mode
+- Animation only: Add custom branded intro/outro sequences if desired
+- Animation only: Speed up or slow down animation speed as desired
 
 ## Commands
-
-Basic usage is similar to Git itself - `git-sim` takes a familiar set of subcommands such as "add", "reset", "branch", "merge", etc, along desired options.
+Basic usage is similar to Git itself - `git-sim` takes a familiar set of subcommands such as "status", "add", "commit", "branch", "reset", "revert", etc, along with corresponding options.
 
 
 ```console
@@ -24,8 +26,11 @@ $ git-sim [global options] <subcommand> [subcommand options]
 
 The `[global options]` apply to the overarching `git-sim` simulation itself, including:
 
-`--speed=n`: Set the multiple of animation speed of the output simulation, `n` can be an integer or float, default is 1.
 `--light-mode`: Use a light mode color scheme instead of default dark mode.
+`--animate`: Instead of outputting a static image, animate the Git command behavior in a .mp4 video. 
+
+Animation-only global options (to be used in conjunction with `--animate`:
+`--speed=n`: Set the multiple of animation speed of the output simulation, `n` can be an integer or float, default is 1.
 `--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.
@@ -36,16 +41,46 @@ The `[global options]` apply to the overarching `git-sim` simulation itself, inc
 
 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 options.
+The following is a list of Git commands that can be simulated and their corresponding options/flags.
 
-### git reset
+### git status
+Usage: `git-sim status`
+
+- Simulated output will show the state of the working directory, staging area, and untracked files
+- Note that simulated output will also show the most recent 5 commits on the active branch
+
+### git add
+Usage: `git-sim add --name=<file>`
+
+- Specify <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 --name=<new-branch>`
+
+- Specify <new-branch> 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 tag
+Usage: `git-sim tag --name=<new-tag>`
+
+- Specify <new-tag> as the name of the new tag to simulate creation of
+- Simulated output will show the newly create tag ref along with most recent 5 commits on the active branch
+
+### git reset
 Usage: `git-sim reset --commit=<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 as desired using  `--mixed`, `--soft`, or `--hard`
-- Simulated command animation will be placed in the path `./git-sim_media/GitSim.mp4`
-- Simulated command animation will show branch resets and resulting state of the working directory, staging area, and whether any file changes would be deleted by running the actual command.
+- As with a normal git reset command, default reset mode is `--mixed`, but can be specified as desired using  `--mixed`, `--soft`, or `--hard`
+- Simulated 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 command
+
+### git revert
+Usage `git-sim revert --commit=<to-revert>`
+
+- Specify <to-revert> as any commit id, branch name, tag, or other ref to simulate revert for
+- Simulated output will show the new commit which reverts the changes from <revert-to>
+- Simluated output will include the next 4 most recent commits on the active branch
 
 ## Video animation example
 https://user-images.githubusercontent.com/49353917/179362209-48748966-6d6c-46ff-9424-b1a7266fc83f.mp4
@@ -55,17 +90,12 @@ https://user-images.githubusercontent.com/49353917/179362209-48748966-6d6c-46ff-
 * Pip (Package manager for Python)
 * [Manim (Community version)](https://www.manim.community/)
 * GitPython
+* OpenCV
 
 ## Quickstart
 1) Install [manim and manim dependencies for your OS](https://www.manim.community/)
 
-2) Install GitPython
-
-```console
-$ pip3 install gitpython
-```
-
-3) Install `git-sim`:
+2) Install `git-sim`:
 
 ```console
 $ pip3 install git-sim
@@ -80,100 +110,93 @@ $ cd path/to/project/root
 4) Run the program:
 
 ```console
-$ git-sim <subcommand> [subcommand options]
+$ git-sim [global options] <subcommand> [subcommand options]
 ```
 
-5) Simulation animations will be created as `.mp4` files. By default, the video
-output file is called `GitSim.mp4` and is stored within a subdirectory called `git-sim_media`. The location of this subdirectory is customizeable using the command line flag `--media-dir=path/to/output`.
+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 customizeable 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) Use command-line options for customization, see usage:
+6) See global help for list of global options/flags and subcommands:
 
 ```console
 $ git-sim -h
+```
 
-usage: git-sim [-h] [--commits COMMITS] [--commit-id COMMIT_ID] [--hide-merged-chains] [--reverse] [--title TITLE] [--logo LOGO] [--outro-top-text OUTRO_TOP_TEXT]
-                 [--outro-bottom-text OUTRO_BOTTOM_TEXT] [--show-intro] [--show-outro] [--max-branches-per-commit MAX_BRANCHES_PER_COMMIT] [--max-tags-per-commit MAX_TAGS_PER_COMMIT]
-                 [--media-dir MEDIA_DIR] [--low-quality] [--light-mode] [--invert-branches]
-
-optional arguments:
-  -h, --help            show this help message and exit
-  --commits COMMITS     The number of commits to display in the Git animation (default: 8)
-  --commit-id COMMIT_ID
-                        The ref (branch/tag), or first 6 characters of the commit to animate backwards from (default: HEAD)
-  --hide-merged-chains  Hide commits from merged branches, i.e. only display mainline commits (default: False)
-  --reverse             Display commits in reverse order in the Git animation (default: False)
-  --title TITLE         Custom title to display at the beginning of the animation (default: Git Sim, by initialcommit.com)
-  --logo LOGO           The path to a custom logo to use in the animation intro/outro (default: /usr/local/lib/python3.9/site-packages/git_sim/logo.png)
-  --outro-top-text OUTRO_TOP_TEXT
-                        Custom text to display above the logo during the outro (default: Thanks for using Initial Commit!)
-  --outro-bottom-text OUTRO_BOTTOM_TEXT
-                        Custom text to display below the logo during the outro (default: Learn more at initialcommit.com)
-  --show-intro          Add an intro sequence with custom logo and title (default: False)
-  --show-outro          Add an outro sequence with custom logo and text (default: False)
-  --max-branches-per-commit MAX_BRANCHES_PER_COMMIT
-                        Maximum number of branch labels to display for each commit (default: 2)
-  --max-tags-per-commit MAX_TAGS_PER_COMMIT
-                        Maximum number of tags to display for each commit (default: 1)
-  --media-dir MEDIA_DIR
-                        The path to output the animation data and video file (default: .)
-  --low-quality         Render output video in low quality, useful for faster testing (default: False)
-  --light-mode          Enable light-mode with white background (default: False)
-  --invert-branches     Invert positioning of branches where applicable (default: False)
-  --speed SPEED         A multiple of the standard 1x animation speed (ex: 2 = twice as fast, 0.5 = half as fast) (default: 1)
-```
-
-## Command Examples
-Default - draw 8 commits starting from `HEAD`, from oldest to newest:
+7) See subcommand help for list of options/flags for a specific subcommand:
 
 ```console
-$ cd path/to/project/root
-$ git-sim
+$ git-sit <subcommand> -h
+
+## Basic command examples
+Simulate the output of the git status command:
+
+```console
+$ cd path/to/git/repo
+$ git-sim status
 ```
 
-Customize the start commit and number of commits, and reverse their display order:
+Simulate adding a file to the Git staging area:
 
 ```console
-$ git-sim --commit-id a1b2c3 --commits=6 --reverse
+$ git-sim --light-mode add --name=filename.ext
 ```
 
-Invert the branch orientation, if multiple branches exist in the commit range:
+Simluate creating a new Git branch:
 
 ```console
-$ git-sim --invert-branches
+$ git-sim branch --name=new-branch-name 
 ```
 
-Add an intro with custom title and logo:
+Simulate creating a new Git tag:
 
 ```console
-$ git-sim --commit-id dev --commits=10 --show-intro --title "My Git Repo" --logo path/to/logo.png
+$ git-sim tag --name=new-tag-name
 ```
 
-Add an outro with custom text and logo:
+Simulate a hard reset of the current branch HEAD to the previous commit:
 
 ```console
-$ git-sim --show-outro --outro-top-text "My Git Repo" --outro-bottom-text "Thanks for watching!" --logo path/to/logo.png
+$ git-sim reset --commit=HEAD^ --hard
 ```
 
-Customize the output video directory location:
+Simulate reverting the changes in an older commit:
 
 ```console
-$ git-sim --media-dir=path/to/output
+$ git-sim revert --commit=HEAD~7
 ```
 
+## Command examples with extra options/flags
 Use light mode for white background and black text, instead of the default black background with white text:
 
 ```console
-$ git-sim --light-mode
+$ git-sim --light-mode status
+```
+
+Animate the simulated output as a .mp4 video file:
+
+```console
+$ git-sim --animate add --name=filename.ext
+```
+
+Add an intro and outro with custom text and logo (must include `--animate`)
+
+```console
+$ 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:
+
+```console
+$ git-sim --media-dir=path/to/output status
 ```
 
-Generate output video in low quality to speed up rendering time (useful for repeated testing):
+Generate output video in low quality to speed up rendering time (useful for repeated testing, must include `--animate`):
 
 ```console
-$ git-sim --low-quality
+$ git-sim --animate --low-quality status
 ```
 
 ## Installation
-See **QuickStart** section for details on installing manim and GitPython dependencies. Then run:
+See **QuickStart** section for details on installing manim and other dependencies. Then run:
 
 ```console
 $ pip3 install git-sim

setup.py

@@ -8,7 +8,7 @@
     version="0.0.1",
     author="Jacob Stopak",
     author_email="jacob@initialcommit.io",
-    description="Simulate git commands with a visualization before running them",
+    description="Simulate Git commands on your own repos by generating an image (default) or video visualization depicting the command's behavior.",
     long_description=long_description,
     long_description_content_type="text/markdown",
     url="https://initialcommit.com/tools/git-sim",
@@ -24,7 +24,7 @@
         'manim',
         'opencv-python',
     ],
-    keywords='git sim simulation simulate git-simulate git-simulation git-sim manim animation gitanimation',
+    keywords='git sim simulation simulate git-simulate git-simulation git-sim manim animation gitanimation image video dryrun dry-run',
     project_urls={
         'Homepage': 'https://initialcommit.com/tools/git-sim',
     },