gitlogue: Replaying Git History as Terminal Animation

The gap between git log output and a readable commit story

Git history is stored as a sequence of snapshots, but the tools that display it flatten that sequence into either a one-line-per-commit log or a unified diff. Neither shows the shape of a change over time. gitlogue addresses that by replaying a commit as a timed animation: characters appear, the cursor moves, lines are deleted, and files are created or removed in sequence. The README describes this as turning Git history into a living, animated story, and the feature list names realistic typing, cursor movement, deletions, and file operations as the animated elements. The audience is narrow and specific. The README lists presentations, education, content creation with VHS or asciinema, desktop ricing, and a self-described look busy mode. This is a rendering layer over Git, not an interface for doing Git work.

What gitlogue reads and how it renders it

The mechanism visible in the material is a pipeline from Git objects to terminal frames. gitlogue takes a commit, a commit range, or the working tree, extracts the changed files and their contents, and then plays that content back character by character at a configurable speed. Tree-sitter supplies syntax highlighting across the 32 languages the README lists, which is why the language support list reads like a parser inventory (Astro, Godot's GDScript and shader formats, Nix, Zig) rather than a general-purpose text list. A separate file tree view shows directory structure with change statistics. The terminal UI is built on ratatui, per the repository topics. The playback model has two granularities: stepping one line at a time with h and l, and stepping one change at a time with H and L, which suggests the animation engine tracks change hunks as units rather than only emitting a character stream. The README does not document the internal architecture in the excerpt available here; docs/ARCHITECTURE.md is referenced but its contents are not included, so the exact data flow between the Git reader, the highlighter, and the render loop cannot be confirmed from this material.

Installation paths and the commands you actually run

gitlogue ships through several channels. The README recommends the install script: curl -fsSL https://raw.githubusercontent.com/unhappychoice/gitlogue/main/install.sh | bash. Homebrew users run brew install gitlogue, Cargo users run cargo install gitlogue, Arch users run pacman -S gitlogue, and Nix users can run it without installing via nix run github:unhappychoice/gitlogue or install it with nix profile install github:unhappychoice/gitlogue. Building from source is git clone followed by cargo install --path . in the repository directory. Piping a remote script into bash is the recommended path, which is a trust decision the user makes rather than a technical one; the Homebrew and Cargo routes avoid it. Once installed, the bare command gitlogue starts the screensaver mode, replaying random commits. Targeted replay uses gitlogue --commit abc123 for a single commit or gitlogue --commit HEAD~5..HEAD for a range. Ordering defaults are not stated for ranges, but --order asc replays oldest first. Adding --loop repeats the selection indefinitely. The diff subcommand is separate from replay: gitlogue diff shows staged changes by default and gitlogue diff --unstaged shows unstaged ones. Filtering accepts --author with case-insensitive partial matching, plus --after and --before with values like 2024-01-01 or the relative form 1 week ago. Presentation controls include --theme dracula, --speed 20 for milliseconds per character, per-pattern overrides such as --speed-rule "*.java:50" and --speed-rule "*.xml:5", and exclusion via --ignore "*.ipynb" or --ignore-file .gitlogue-ignore. Themes are managed with gitlogue theme list and gitlogue theme set dracula. Configuration lives at ~/.config/gitlogue/config.toml, and the README states it covers the default theme, typing speed, and background preferences; the full key list is in docs/configuration.md, which is not reproduced here.

The speed-rule and ignore options are where the tuning happens

Most of the command-line surface is selection (which commits, which author, which date window) and the rest is presentation. The presentation flags are the interesting part because they encode an assumption about what makes a replay watchable. Typing speed is expressed in milliseconds per character, and --speed-rule lets you override it per glob pattern. The README's own example pairs "*.java:50" with "*.xml:5", which is a sensible pairing: verbose source types slowly enough to read, dense configuration and markup types fast enough not to stall the animation. The --ignore and --ignore-file options exist for the same reason. Notebooks and lock files generate enormous diffs that carry little narrative value, so the README's example of --ignore "*.ipynb" --ignore "poetry.lock" is really guidance about what breaks the pacing. If you replay a repository with generated files committed, the animation will spend most of its runtime on content nobody wants to watch. There is no documented auto-detection for this; the user supplies the patterns.

Screensaver mode is a display mode, not a screensaver

The README carries an explicit warning block, and it is worth taking literally. gitlogue does not include traditional screensaver functions such as power management or screen blanking; it is purely a visual display. That means it will not prevent your display from sleeping, and on a laptop it will keep the terminal active while the machine's own power settings do whatever they are configured to do. The second warning is about OLED burn-in: static elements like the editor background and border lines may cause burn-in over extended periods, while LCD displays are generally safe. Anyone planning to leave gitlogue running unattended on an OLED panel should treat that as a real constraint rather than boilerplate. The two warnings together define the tool's boundary: it is an ambient display that assumes you are looking at it occasionally, not an unattended kiosk application.

Where gitlogue is the wrong tool

gitlogue renders history; it does not help you reason about it. If you need to find when a function changed, bisect a regression, or review a branch before merge, the animation is overhead. The diff subcommand shows staged or unstaged changes, but it shows them as an animation, which is the opposite of what you want when you are deciding whether to commit. There is also a scaling failure mode implied by the design: a replay is linear in the size of the change, so a commit that touches thousands of lines will take a long time to play at any readable speed, and the speed-rule escape hatch only helps when the bulk sits in a few file types. The README does not document a maximum diff size, a skip-ahead to the end of a file, or a summary mode. The key bindings offer line and change stepping plus commit navigation (p, n) and a menu on Esc, but nothing that jumps to the end of a large hunk. For repositories with a long single-commit history, for example a code drop, the tool has little to work with.

How it differs from the projects it is listed beside

The README's related projects section is short but informative. GitType, from the same author, is a CLI code-typing game that turns source code into typing challenges. Both projects involve typing animations, but the direction of the interaction is inverted. GitType asks the user to type the code and scores them; gitlogue types the code at the user. That is the difference between a practice tool and a display tool, and it decides which one belongs in a training session versus a demo recording. The other neighbor, tarts, is a collection of terminal screensavers in Rust (Matrix, Game of Life, Boids). tarts generates synthetic visuals; gitlogue renders real repository data. If the goal is decoration with no connection to your work, tarts is the simpler fit. If the goal is decoration that happens to be your own project's history, gitlogue is the one that reads .git.

Licence, release cadence, and what to check first

gitlogue is licensed under ISC, a permissive licence that the repository states in its LICENSE file and that crates.io reports via the license badge. ISC is short and permissive in the same family as MIT; this is a description of the identifier, not legal advice, and anyone redistributing a modified binary should read the actual licence text. The release history shows v0.9.0 in April 2026, v0.10.0 in July, and v0.11.0 in August, with the last push in September 2026. That is a roughly quarterly cadence on a pre-1.0 version, which means the command-line surface and config.toml keys can still change between releases. Pin a version if you script it. Two things are worth verifying before you commit to it. First, check docs/configuration.md for the actual config.toml keys, because the README names only three settings and the file path. Second, confirm your terminal renders the animation acceptably, since the README documents no minimum terminal requirements and the demo is distributed as a GIF rather than as a specification.

Editorial conclusion

Adopt gitlogue if you record terminal demos, teach version control, or want a commit-history display running in a spare pane, and verify that your terminal supports the rendering it needs and that your display is not OLED before leaving it in screensaver mode. Do not adopt it as a substitute for git log, git diff, or a code review tool: it renders history rather than helping you reason about it, and the README explicitly states it has no power management or screen blanking. Before installing, check the docs/configuration.md file for the config.toml keys, since the README only names the file path and the three settings it accepts.

Official sources

1. Issues
2. License: ISC
3. README
4. Releases
5. unhappychoice/gitlogue on GitHub