Knowledge Base

gitlogue

4 min read

Gitlogue

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

🖥️ 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
 
# 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:

gitlogue theme set dracula

Or manually create/edit the config file:

# 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:

# 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:

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:

# 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)

Graph View