Tools
git-story
The story of your repo as a video: animate a commit history into an .mp4, straight from the command line.
- Turn any range of commits into an animated video: from any branch, tag or commit, oldest to newest or reversed..mp4 outputAny repo--commit-id--commits--reverse
- Make it yours: an intro and outro with your title and logo, dark or light mode, your own speed.--show-intro--show-outro--logo--light-mode--speed
- Made for talks, READMEs, blog posts and videos, and for showing newer developers how a history grew.TalksREADMEsBlog postsYouTubeOnboarding
$ git-story --commits=6 --reverse
See one
Eight commits on a small repository, as git-story draws them.
Commits appear one by one along their branches, with HEAD, branch and tag labels drawn where they belong.
What it is for
A history is easier to follow when it moves.
Show how a feature came together, or how a release was assembled, without paging through a log on stage.
A short loop of the project's history says more about its shape than a paragraph does.
Animate just the commits that matter, from a chosen ref, to walk your team through what happened.
Watching commits, branches and merges appear in order helps newer developers see what the graph means.
Want the video to show what a command would do rather than what happened? git-sim simulates the command first and, with --animate, writes that as a video too.
Install and run
Python 3.9 or newer, Manim and GitPython. The video is rendered by Manim, so its system dependencies come first.
Follow the Manim installation guide: it needs FFmpeg and, on some systems, a LaTeX distribution and Cairo.
pip3 install gitpython
pip3 install git-storycd path/to/project/root
git-storyA default .mp4 of the most recent eight commits on the checked-out branch is written to git-story_media/ in the current directory. --media-dir=path/to/output puts it elsewhere.
Examples
Each option adds to the default; combine them as you like.
Start from a commit or a ref, choose how many commits, and reverse their order:
$ git-story --commit-id a1b2c3 --commits=6 --reverseAdd an intro with your own title and logo, and an outro with your own text:
$ git-story --commit-id dev --commits=10 --show-intro --title "My Git Repo" --logo path/to/logo.png
$ git-story --show-outro --outro-top-text "My Git Repo" --outro-bottom-text "Thanks for watching!" --logo path/to/logo.pngLight mode, a different branch orientation, twice the speed, and a quick low-quality render while you get the options right:
$ git-story --light-mode
$ git-story --invert-branches
$ git-story --speed=2
$ git-story --low-qualityOptions
git-story -h prints the same list.
| Option | What it does | Default |
|---|---|---|
--commits | The number of commits to animate. | 8 |
--commit-id | The ref (branch, tag) or first characters of the commit to animate backwards from. | HEAD |
--hide-merged-chains | Show only mainline commits, hiding those from merged branches. | off |
--reverse | Draw the commits in reverse order. | off |
--invert-branches | Flip where branches are placed, where it applies. | off |
--max-branches-per-commit, --max-tags-per-commit | How many branch and tag labels a commit may carry. | 2, 1 |
--show-intro, --title, --logo | An intro sequence with a title and logo. | off |
--show-outro, --outro-top-text, --outro-bottom-text | An outro sequence with text above and below the logo. | off |
--light-mode | White background, dark text. | off |
--speed | A multiple of the normal animation speed: 2 is twice as fast, 0.5 half. | 1 |
--low-quality | A quick render for testing options. | off |
--media-dir | Where the animation data and video go. | . |
Questions
Does git-story change my repository?
No. It reads the history and writes a video into git-story_media/, or wherever --media-dir points. Nothing in the repository is touched.
How complex a history can it draw?
It works best with simpler branching, and copes with more complex ones. --hide-merged-chains keeps the mainline only, and --max-branches-per-commit limits how many labels crowd a commit.
How does it relate to git-sim?
git-story animates what happened. git-sim shows what a command would do, before it runs, as an interactive graph you can share, and can write that as a video with --animate. Both come from Initial Commit.
Why does it need Manim?
Manim is the animation engine that draws and renders the frames. Its installation brings FFmpeg and a few system libraries, which is why installing it is the first step.
git-story is free and open source, made by Jacob Stopak for Initial Commit.