## 1. Project Overview & Quickstart (unhappychoice/gitlogue)

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

## Installation

### Using Install Script (Recommended)

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

### Using Homebrew

```bash
brew install gitlogue
```

### Using Cargo

```bash
cargo install gitlogue
```

### On Arch Linux

```bash
pacman -S gitlogue
```

### Using Nix

```bash
# 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

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

See the [Installation Guide](docs/installation.md) 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** — 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

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

```bash
# 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](docs/configuration.md) for full options and examples.

## Supported Languages

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

[Installation Guide](docs/installation.md)  
[Usage Guide](docs/usage.md)  
[Configuration Guide](docs/configuration.md)  
[Theme Customization](docs/themes.md)  
[Contributing Guidelines](docs/CONTRIBUTING.md)  
[Architecture Overview](docs/ARCHITECTURE.md)

## Related Projects

### Git Visualization & Coding

- [**GitType**](https://github.com/unhappychoice/gittype) - A CLI code-typing game that turns your source code into typing challenges

### Terminal Screensavers

- [**tarts**](https://github.com/oiwn/tarts) - Collection of terminal screensavers in Rust (Matrix, Game of Life, Boids, 3D effects, and more)
- [**cbonsai**](https://gitlab.com/jallbrit/cbonsai) - Grow beautiful bonsai trees in your terminal
- [**asciiquarium**](https://github.com/cmatsuoka/asciiquarium) - Enjoy the mysteries of the sea from your terminal
- [**cmatrix**](https://github.com/abishekvashok/cmatrix) - The Matrix screensaver effect for your terminal
- [**pipes.sh**](https://github.com/pipeseroni/pipes.sh) - Animated pipes flowing through your terminal

## Contributing

Contributions are welcome.  
See the [Contributing Guidelines](docs/CONTRIBUTING.md) for details.

## License

ISC License. See [LICENSE](LICENSE) for details.

## Author

[@unhappychoice](https://unhappychoice.com)

## Support

If you find this project useful, please consider:

- ⭐️ [Star on GitHub](https://github.com/unhappychoice/gitlogue)
- 🐦 [Share on X](https://x.com/intent/post?text=Your%20Git%20history%20as%20cinema.%20gitlogue%20replays%20commits%20as%20a%20terminal%20animation%20%F0%9F%8E%9E%EF%B8%8F&url=https%3A//github.com/unhappychoice/gitlogue&hashtags=gitlogue,CLI,Rust,git)
- 🦋 [Share on Bluesky](https://bsky.app/intent/compose?text=Your%20Git%20history%20as%20cinema.%20gitlogue%20replays%20commits%20as%20a%20terminal%20animation%20%F0%9F%8E%9E%EF%B8%8F%20%23gitlogue%20%23CLI%20%23Rust%20%23git%20https%3A//github.com/unhappychoice/gitlogue)
- 🧵 [Share on Threads](https://www.threads.net/intent/post?text=Your%20Git%20history%20as%20cinema.%20gitlogue%20replays%20commits%20as%20a%20terminal%20animation%20%F0%9F%8E%9E%EF%B8%8F%20%23gitlogue%20%23CLI%20%23Rust%20%23git%20https%3A//github.com/unhappychoice/gitlogue)
- 💼 [Share on LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A//github.com/unhappychoice/gitlogue)
- 📘 [Share on Facebook](https://www.facebook.com/sharer/sharer.php?u=https%3A//github.com/unhappychoice/gitlogue)
- 🟧 [Submit to Hacker News](https://news.ycombinator.com/submitlink?u=https%3A//github.com/unhappychoice/gitlogue&t=Your%20Git%20history%20as%20cinema.%20gitlogue%20replays%20commits%20as%20a%20terminal%20animation%20%F0%9F%8E%9E%EF%B8%8F)
- 💬 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)

# unhappychoice.com

Personal site for [@unhappychoice](https://github.com/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

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

## Layout

```
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

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

## Refreshing data manually

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

```sh
./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

- **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`.