README.md
May 14, 2026 · View on GitHub
A cinematic Git commit replay tool for the terminal.
Turn your Git history into a living, animated story — typing, syntax highlighting, file tree transitions.
Watch commits unfold with realistic typing animations, syntax highlighting, and file tree transitions, transforming code changes into a visual experience.
Installation
Using Install Script (Recommended)
curl -fsSL https://raw.githubusercontent.com/unhappychoice/gitlogue/main/install.sh | bash
Using Homebrew
brew install gitlogue
Using Cargo
cargo install gitlogue
On Arch Linux
pacman -S gitlogue
Using Nix
# Run directly without installation
nix run github:unhappychoice/gitlogue
# Or install to your profile
nix profile install github:unhappychoice/gitlogue
# For flake-based configurations, add to your inputs:
# inputs.gitlogue.url = "github:unhappychoice/gitlogue";
# Then use: inputs.gitlogue.packages.${system}.default
From Source
git clone https://github.com/unhappychoice/gitlogue.git
cd gitlogue
cargo install --path .
See the Installation Guide for more options and troubleshooting.
Features
🎬 Commit Replay as Animation — Realistic typing, cursor movement, deletions, and file operations 🔍 Working Tree Diff View — Visualize staged/unstaged changes before committing 🎨 Tree-sitter Syntax Highlighting — 29 languages supported 🌳 Project File Tree — Directory structure with change statistics 🖥️ Screensaver Mode — Endless random commit playback 🎭 Themes — 9 built-in themes + full customization support ⚡ Fast & Lightweight — Built with Rust for performance
Usage
Popular Use Cases
🖥️ Screensaver — Ambient coding display for your workspace
🎓 Education — Visualize how code evolved over time
📺 Presentations — Replay real commit histories live
🎬 Content Creation — Record demos with VHS or asciinema
🎨 Desktop Ricing — A living decoration for your terminal
💼 Look Busy Mode — Appear productive during meetings
Warning
Not a True Screensaver — gitlogue does not include traditional screensaver functions like power management or screen blanking. It's purely a visual display tool.
OLED Burn-in Risk — Static elements (like the editor background and border lines) may cause burn-in on OLED displays over extended periods. LCD displays are generally safe from this issue.
Quick Start
# Start the cinematic screensaver
gitlogue
# View a specific commit
gitlogue --commit abc123
# Replay a range of commits
gitlogue --commit HEAD~5..HEAD
# Replay commits in chronological order (oldest first)
gitlogue --order asc
# Loop a specific commit continuously
gitlogue --commit abc123 --loop
# Loop through a commit range
gitlogue --commit HEAD~10..HEAD --loop
# View staged changes (default)
gitlogue diff
# View unstaged changes instead
gitlogue diff --unstaged
# Filter commits by author or email (case-insensitive partial match)
gitlogue --author "john"
# Filter commits by date
gitlogue --after "2024-01-01"
gitlogue --before "1 week ago"
gitlogue --after "2024-06-01" --before "2024-07-01"
# Use a different theme
gitlogue --theme dracula
# Adjust typing speed (ms per character)
gitlogue --speed 20
# Set different speeds for different file types
gitlogue --speed-rule "*.java:50" --speed-rule "*.xml:5"
# Ignore specific file patterns (e.g., notebooks, lock files)
gitlogue --ignore "*.ipynb" --ignore "poetry.lock"
# Use an ignore file
gitlogue --ignore-file .gitlogue-ignore
# List available themes
gitlogue theme list
# Set default theme
gitlogue theme set dracula
# Combine options
gitlogue --commit HEAD~5 --author "john" --theme nord --speed 15 --ignore "*.ipynb"
Key Bindings
Playback
| Key | Action |
|---|---|
Space | Toggle play / pause |
h | Step one line backward |
l | Step one line forward |
H (Shift+h) | Step one change backward |
L (Shift+l) | Step one change forward |
p | Previous commit |
n | Next commit |
Esc | Open menu |
q / Ctrl+c | Quit |
Menu
| Key | Action |
|---|---|
j / ↓ | Move selection down |
k / ↑ | Move selection up |
Enter | Select item |
Esc | Close menu |
Configuration
gitlogue can be configured via ~/.config/gitlogue/config.toml.
You can set the default theme, typing speed, and background preferences.
See the Configuration Guide for full options and examples.
Supported Languages
Astro, Bash, C, C#, C++, Clojure, CSS, Dart, Elixir, Erlang, Go, Haskell, HTML, Java, JavaScript, JSON, Kotlin, Lua, Markdown, Nix, PHP, Python, Ruby, Rust, Scala, Svelte, Swift, TypeScript, XML, YAML, Zig
Documentation
Installation Guide
Usage Guide
Configuration Guide
Theme Customization
Contributing Guidelines
Architecture Overview
Related Projects
Git Visualization & Coding
- GitType - A CLI code-typing game that turns your source code into typing challenges
Terminal Screensavers
- tarts - Collection of terminal screensavers in Rust (Matrix, Game of Life, Boids, 3D effects, and more)
- cbonsai - Grow beautiful bonsai trees in your terminal
- asciiquarium - Enjoy the mysteries of the sea from your terminal
- cmatrix - The Matrix screensaver effect for your terminal
- pipes.sh - Animated pipes flowing through your terminal
Contributing
Contributions are welcome.
See the Contributing Guidelines for details.
License
ISC License. See LICENSE for details.
Author
Support
If you find this project useful, please consider:
- ⭐️ Star on GitHub
- 🐦 Share on X
- 🦋 Share on Bluesky
- 🧵 Share on Threads
- 💼 Share on LinkedIn
- 📘 Share on Facebook
- 🟧 Submit to Hacker News
- 💬 Drop it into your Discord server or developer chat
- ✍️ Write about it on your blog or in a newsletter
Every bit of support helps. Thanks!