gitlogue README

The project's README from github.com/unhappychoice/gitlogue. As one markdown file: README.md.

gitlogue

crates.io release CI codecov license Terminal Trove Tool of The Week Featured|HelloGitHub

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

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 — 32 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

🖥️ 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, Godot (GDScript / Shader / Resource), 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

Git Visualization & Coding

Terminal Screensavers

Contributing

Contributions are welcome.
See the Contributing Guidelines for details.

License

ISC License. See LICENSE for details.

Author

@unhappychoice

Support

If you find this project useful, please consider:

Every bit of support helps. Thanks!

gitlogue (unhappychoice/gitlogue)

Searching Database…

What is this?gitlogue is a cinematic Git commit replay tool for the terminal: it turns your Git history into a living, animated story with realistic typing, syntax highlighting, and file tree transitions.
Is this a GUI app or something that lives in my terminal?It's a terminal app — a TUI written in Rust (with ratatui) that renders the animated replay right inside your terminal.
How do I get it installed?Several routes: an install script (recommended), Homebrew, Cargo, an Arch Linux package, Nix, or building from source — the README links an Installation Guide with all options.
Do I need Rust or anything else installed first?No — the install script, Homebrew, Arch Linux, and Nix routes give you a ready binary; only the Cargo and from-source routes need a Rust toolchain.
Can it blank my screen or handle power management like a real screensaver?No — it's purely a visual display tool with no power management or screen blanking. Static elements may also cause burn-in on OLED displays over long sessions; LCDs are generally safe.
What does a commit replay actually show?Realistic typing, cursor movement, deletions, and file operations, plus tree-sitter syntax highlighting and a project file tree with change statistics as files change.
Does it only replay old commits, or can I show uncommitted work too?It also has a Working Tree Diff View, so you can visualize staged and unstaged changes before committing them.
Which languages get syntax highlighting?32 languages via tree-sitter — the usual ones like Rust, Go, Python, JavaScript, TypeScript, Java and C++, plus Astro, Godot GDScript, Svelte, Nix and Zig.
Can I control playback while it runs?Yes — Space toggles play/pause, h/l step one line, H/L one change, p/n jump between commits, Esc opens a menu, and q quits.
Can I change the theme or typing speed?There are 9 built-in themes plus full customization, and ~/.config/gitlogue/config.toml sets the default theme, typing speed, and background preferences.
What do people use it for?An ambient screensaver for your workspace, education, presentations, demos recorded with VHS or asciinema, desktop ricing — or a 'look busy' mode in meetings. Screensaver mode replays random commits endlessly.
What are similar projects?toast, cbirds, superfile, difftastic, edit, rataflow, micro, spotatui
Size
79.7 MB
Stars
5.1K
Age
11mo
Commits · 90 Days