gitlogue Documentation

1. Project Overview & Quickstart (unhappychoice/gitlogue) Copy Chapter

Watch commits unfold with realistic typing animations, syntax highlighting, and file tree transitions, transforming code changes into a visual experience.

Installation Copy Chapter

Using Install Script (Recommended) Copy Section

curl -fsSL https://raw.githubusercontent.com/unhappychoice/gitlogue/main/install.sh | bash

Using Homebrew Copy Section

brew install gitlogue

Using Cargo Copy Section

cargo install gitlogue

On Arch Linux Copy Section

pacman -S gitlogue

Using Nix Copy Section

# 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 Copy Section

git clone https://github.com/unhappychoice/gitlogue.git
cd gitlogue
cargo install --path .

See the Installation Guide for more options and troubleshooting.

Features Copy Chapter

🎬 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 Copy Chapter

Popular Use Cases Copy Section

🖥️ 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 Copy Section

# 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 Copy Chapter

Playback Copy Section

Menu Copy Section

Configuration Copy Chapter

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 Copy Chapter

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 Copy Chapter

Installation Guide
Usage Guide
Configuration Guide
Theme Customization
Contributing Guidelines
Architecture Overview

Related Projects Copy Chapter

Git Visualization & Coding Copy Section

• GitType - A CLI code-typing game that turns your source code into typing challenges

Terminal Screensavers Copy Section

• 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 Copy Chapter

Contributions are welcome.
See the Contributing Guidelines for details.

License Copy Chapter

ISC License. See LICENSE for details.

Author Copy Chapter

@unhappychoice

Support Copy Chapter

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!

2. Official Technical Reference & Guides (unhappychoice/unhappychoice.github.io) Copy Chapter

unhappychoice.com

Personal site for @unhappychoice, served from GitHub Pages at https://unhappychoice.com.

It is a small static site with two pages and an hourly data-refresh job that
keeps the OSS showcase in sync with GitHub.

Pages Copy Chapter

• index.html: profile, skills, philosophy, links.
• oss/index.html: OSS showcase. Lists repositories across
  unhappychoice and four orgs
  (circleci-tools, bitflyer-tools, irasutoya-tools, kotlinz,
  deariary), with stats, language filter, and a per-repo activity modal.

Layout Copy Chapter

index.html             Profile page
oss/index.html         OSS showcase page
style.css              Shared stylesheet
js/repos.js            Renders repo cards, filter, sort, modal
js/stats.js            Renders aggregate stats block
images/                Static assets (avatar, etc.)
data/
  repos.json           Repo metadata snapshot (generated)
  stats.json           Aggregate stats snapshot (generated)
  activity/*.json      Per-repo recent events (generated)
  featured.json        Hand-written highlights shown on top of the showcase
  excluded.json        Repo full_names to hide from the showcase
scripts/refresh-data.sh   Regenerates data/*.json from the GitHub API
.github/workflows/refresh-data.yml   Hourly cron that runs the script and commits
CNAME                  GitHub Pages custom domain

No build step. The site is plain HTML / CSS / vanilla JS loaded directly by
GitHub Pages.

Local preview Copy Chapter

python3 -m http.server 8000
# open http://localhost:8000

Refreshing data manually Copy Chapter

Requires gh, jq, and curl. gh must be authenticated.

./scripts/refresh-data.sh

This rewrites data/repos.json, data/stats.json, and data/activity/*.json.
The hourly GitHub Actions workflow runs the same script and commits the diff
as chore(data): refresh OSS snapshots.

Editing the showcase Copy Chapter

• Highlight a repo: add an entry to data/featured.json. The order in
  this file controls the order in the "Featured" sort.
• Hide a repo: add its full_name (e.g. owner/name) to
  data/excluded.json. The next refresh will drop it.
• Add a tracked org: append to the ORGS array in
  scripts/refresh-data.sh.