git-poster

Turn your Git history into a beautiful poster.

A zero-config CLI that parses your Git log and renders a contribution heatmap poster as an SVG or PNG — no account required, fully local.

Installation

Run directly (no install needed):

npx git-poster

Install globally:

npm install -g git-poster
git-poster

Install locally in a project:

npm install --save-dev git-poster
npx git-poster

PNG support (optional):

npm install -g sharp
git-poster --png

Requires Node.js 18 or later.

Quick Start

cd your-repo
git-poster

That's it. Run from any Git repository and get git-poster.svg in the current directory.

Features

• 5 built-in themes — dark, light, midnight, forest, ocean
• SVG and PNG output — crisp at any resolution; PNG via optional sharp
• Zero config — sensible defaults, works out of the box
• Flexible filters — by author, branch, date range
• Terminal summary — commit stats printed to stderr before the file is written
• Requires only Node 18+ — no external dependencies beyond npm

Usage Examples

Basic — generate poster from cwd:

npx git-poster

Choose a theme:

npx git-poster --theme midnight

Filter by date range:

npx git-poster --since 2024-01-01 --until 2024-12-31

Export as PNG:

npm install sharp   # one-time optional peer dep
npx git-poster --png -o poster.png

Quiet mode (no terminal output):

npx git-poster -q -o ~/Desktop/poster.svg

Stats only (no file written):

npx git-poster --stats-only

Specific repo, branch, and author:

npx git-poster --repo ~/projects/myapp --branch develop --author "Kerim Gulen"

CLI Reference

| Flag | Description | Default | |---|---|---| | --repo <path> | Repository path | cwd | | -o, --output <file> | Output file path | git-poster.svg | | --png | Export as PNG (requires sharp) | — | | --theme <name> | Color theme | dark | | --branch <name> | Specific branch | all branches | | --since <date> | Start date (YYYY-MM-DD) | — | | --until <date> | End date (YYYY-MM-DD) | — | | --author <name> | Filter commits by author name | — | | --width <px> | Poster width in pixels | 1200 | | --height <px> | Poster height in pixels | 800 | | -q, --quiet | Suppress terminal output | — | | --stats-only | Print stats only, no file written | — | | -V, --version | Print version | — | | -h, --help | Show help | — |

Themes

| Name | Background | Heatmap | Style | |---|---|---|---| | dark (default) | Dark gray | Green | GitHub dark mode | | light | Off-white | Green | GitHub light mode | | midnight | Deep navy | Blue tones | Late-night coding | | forest | Dark green | Natural greens | Organic, muted | | ocean | Dark blue-teal | Teal/cyan | Deep sea |

npx git-poster --theme ocean

How It Works

CLI (commander)
  └─ Core
       ├─ git (simple-git)       — parse commit log
       └─ analyzer               — aggregate by day, compute heatmap buckets
  └─ Output
       ├─ poster (SVG builder)   — render contribution grid + metadata
       ├─ terminal (chalk)       — print stats table to stderr
       └─ export (sharp)         — optional raster conversion to PNG

1. CLI parses flags and resolves the repository path.
2. Core reads the Git log via simple-git, groups commits by calendar day, and maps counts into heatmap intensity buckets.
3. Output builds an SVG string from scratch (no external renderer), optionally converts it to PNG with sharp, and prints a summary table to the terminal.

Contributing

1. Fork the repository.
2. Create a feature branch: git checkout -b feat/my-change
3. Make your changes and add tests under tests/.
4. Open a pull request against main.

All contributions are welcome — new themes, output formats, performance improvements, or bug fixes.

License

MIT — see LICENSE.

Made by Kerim Gulen