Gitlogue
4 min read
A cinematic Git commit replay tool for the terminal, turning your Git history into a living, animated story.
Watch commits unfold with realistic typing animations, syntax highlighting, and file tree transitions, transforming code changes into a visual experience.
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
sh
# 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
# 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
# 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"
Configuration
gitlogue supports configuration via a TOML file located at ~/.config/gitlogue/config.toml.
All configuration options are optional. CLI arguments take precedence over config file values.
Set your default theme using the theme set command:
bash
gitlogue theme set dracula
Or manually create/edit the config file:
bash
# Create config directory
mkdir -p ~/.config/gitlogue
# Edit config file
vim ~/.config/gitlogue/config.toml
Configuration File Format
The config file uses TOML format. Here's a complete example:
toml
# gitlogue configuration file
# All settings are optional and will use defaults if not specified
# Theme to use for syntax highlighting
theme = "dracula"
# Typing speed in milliseconds per character
speed = 50
# Show background colors (set to false for transparent background)
background = true
# Commit playback order: random, asc, or desc
order = "random"
# Loop the animation continuously
loop = false
# Ignore patterns (gitignore syntax)
# Examples: ["*.ipynb", "poetry.lock", "docs/api/**"]
ignore_patterns = []
Configuration Options
theme
Theme name for syntax highlighting.
• Type: String
• Default: "tokyo-night"
• Example: theme = "dracula"
See all available themes:
bash
gitlogue theme list
Available themes: ayu-dark, catppuccin, dracula, everforest, github-dark, gruvbox, material, monokai, night-owl, nord, one-dark, rose-pine, solarized-dark, solarized-light, tokyo-night
speed
Typing speed in milliseconds per character. Lower values = faster typing animation.
• Type: Integer
• Default: 30
• Range: Typically 10-100
• Example: speed = 20
background
Whether to show background colors in themes.
• Type: Boolean
• Default: true
• Example: background = false
Set to false for transparent background (useful for terminal transparency).
order
Commit playback order.
• Type: String
• Default: "random"
• Example: order = "asc"
Available orders:
• random - Randomly selects commits (default)
• asc - Replays commits from oldest to newest
• desc - Replays commits from newest to oldest
loop
Whether to loop the animation continuously.
• Type: Boolean
• Default: false
• Example: loop = true
When enabled, the animation will repeat indefinitely after completing. Especially useful with specific commits for demonstrations and ambient displays.
ignore_patterns
List of patterns for files to ignore during animation.
• Type: Array of strings
• Default: [] (empty array)
• Example: ignore_patterns = ["*.ipynb", "poetry.lock"]
Pattern syntax (gitignore-style):
• *.ipynb - All Jupyter notebook files anywhere in the repository
• poetry.lock - Poetry lock file in repository root
• docs/api/** - All files under docs/api directory
Note: Binary files (images, videos, etc.) are already automatically excluded and don't need to be specified here.
Common use cases:
toml
# Ignore Jupyter notebooks (JSON format, hard to read as text diff)
ignore_patterns = ["*.ipynb"]
# Ignore lock files that are tracked in git
ignore_patterns = ["poetry.lock", "Cargo.lock", "yarn.lock"]
# Ignore generated documentation
ignore_patterns = ["docs/api/**"]
# Combine multiple patterns
ignore_patterns = [
"*.ipynb",
"poetry.lock",
"**/*.test.js",
"**/__snapshots__/**"
]
Note: These patterns are additive with CLI --ignore flags and --ignore-file options. The ignore order is:
1. Config file ignore_patterns
2. --ignore-file patterns
3. CLI --ignore flags (highest priority)