git-hash-art

Generate beautiful, deterministic abstract art from git commit hashes. Perfect for creating unique visual representations of your project's commits, generating placeholder images, or creating artistic wallpapers.

Works in both Node.js and browser environments.

Features

• Deterministic output — same hash always produces the same image
• Hash-driven color palettes — 6 variation modes × 5 scheme types for dramatic palette diversity
• Per-layer blend modes — screen, multiply, overlay, soft-light, and more for painterly depth
• 6 shape render styles — fill+stroke, wireframe, dashed, double-stroke, watercolor bleed, fill-only
• 20+ shape types across three categories: basic, complex, and sacred geometry
• Layered composition with depth — early layers use simple shapes, later layers use intricate ones
• Atmospheric perspective — later layers desaturate for foreground/background separation
• Negative space — void zones and density-aware placement create intentional breathing room
• Watercolor-style transparency with semi-transparent fills and color blending
• Organic edges — ~15% of shapes get multi-pass watercolor bleed for hand-drawn quality
• Glow effects on sacred geometry shapes for an ethereal quality
• Layered backgrounds — faint shapes and concentric rings add texture before the main layers
• Tapered flow lines — brush-stroke curves with width and opacity tapering
• Radial gradient fills and organic color jitter for a hand-painted feel
• Organic bezier curves connecting nearby shapes
• Configurable canvas size, layers, shape sizes, and opacity
• Built-in presets for social media, device wallpapers, and print sizes
• CLI for generating art from the current commit or a specific hash
• Cross-platform: runs in Node.js (via @napi-rs/canvas) and browsers (native Canvas API)

Installation

npm install git-hash-art

For Node.js usage you also need the canvas backend:

npm install @napi-rs/canvas

Browser usage requires no additional dependencies — the library uses the native Canvas 2D API.

Node.js Usage

import { generateImageFromHash, saveImageToFile } from 'git-hash-art';

// Generate a PNG buffer from a git hash
const gitHash = '46192e59d42f741c761cbea79462a8b3815dd905';
const imageBuffer = generateImageFromHash(gitHash);

// Save to disk
saveImageToFile(imageBuffer, './output', gitHash, 'my-art', 2048, 2048);

Advanced Node.js Usage

import { generateImageFromHash } from 'git-hash-art';

const config = {
  width: 1920,
  height: 1080,
  gridSize: 6,
  layers: 5,
  shapesPerLayer: 40,
  minShapeSize: 20,
  maxShapeSize: 300,
  baseOpacity: 0.7,
  opacityReduction: 0.12
};

const imageBuffer = generateImageFromHash(gitHash, config);

Browser Usage

import { renderToCanvas, generateDataURL, generateImageBlob } from 'git-hash-art/browser';

Render onto an existing canvas element

import { renderToCanvas } from 'git-hash-art/browser';

const canvas = document.getElementById('art-canvas');
canvas.width = 1024;
canvas.height = 1024;

renderToCanvas(canvas, '46192e59d42f741c761cbea79462a8b3815dd905');

Generate a data URL (for <img> tags)

import { generateDataURL } from 'git-hash-art/browser';

const dataUrl = generateDataURL('46192e59d42f741c761cbea79462a8b3815dd905', {
  width: 512,
  height: 512,
});

document.getElementById('preview').src = dataUrl;

Generate a Blob (for downloads or uploads)

import { generateImageBlob } from 'git-hash-art/browser';

const blob = await generateImageBlob('46192e59d42f741c761cbea79462a8b3815dd905', {
  width: 1080,
  height: 1080,
});

// Trigger a download
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'hash-art.png';
a.click();

Core Renderer (Environment-Agnostic)

If you need full control, both entry points re-export renderHashArt which accepts any standard CanvasRenderingContext2D — useful for custom canvas setups, Web Workers with OffscreenCanvas, or server-side rendering frameworks.

import { renderHashArt } from 'git-hash-art'; // or 'git-hash-art/browser'

const ctx = myCanvas.getContext('2d');
renderHashArt(ctx, '46192e59d42f741c761cbea79462a8b3815dd905', {
  width: myCanvas.width,
  height: myCanvas.height,
});

Configuration Options

| Option | Type | Default | Description | | ----------------- | ------ | ------- | ---------------------------------------------------- | | width | number | 2048 | Canvas width in pixels | | height | number | 2048 | Canvas height in pixels | | gridSize | number | 5 | Controls base shape count per layer (gridSize² × 1.5)| | layers | number | 4 | Number of layers to generate | | shapesPerLayer | number | auto | Base shapes per layer (defaults to gridSize² × 1.5) | | minShapeSize | number | 30 | Minimum shape size in pixels (scaled to canvas) | | maxShapeSize | number | 400 | Maximum shape size in pixels (scaled to canvas) | | baseOpacity | number | 0.7 | Starting opacity for the first layer | | opacityReduction| number | 0.12 | Opacity reduction per layer |

Shape Categories

Shapes are selected with layer-aware weighting — early layers favor simple shapes for background texture, later layers favor intricate ones for foreground detail.

Basic — circle, square, triangle, hexagon, star, diamond, cube, heart

Complex — platonic solids, fibonacci spiral, islamic pattern, celtic knot, merkaba, mandala, fractal

Sacred Geometry — flower of life, tree of life, Metatron's cube, Sri Yantra, seed of life, vesica piscis, torus, egg of life

Preset Sizes

import { PRESETS } from 'git-hash-art';

// Use a preset's hash and config
const preset = PRESETS['instagram-square'];
const imageBuffer = generateImageFromHash(preset.hash, preset);

Available presets:

• Standard (1024×1024)
• Banner (1920×480)
• Ultrawide (3440×1440)
• Instagram Square (1080×1080)
• Instagram Story (1080×1920)
• Twitter Header (1500×500)
• LinkedIn Banner (1584×396)
• Phone Wallpaper (1170×2532)
• Tablet Wallpaper (2048×2732)
• Minimal, Complex (special configurations)

CLI Usage

# Generate from the current commit
npx git-hash-art current

# Generate from a specific hash
npx git-hash-art generate <hash>

# Custom size
npx git-hash-art generate <hash> --width 1920 --height 1080

Integration Examples

GitHub Actions

name: Generate Commit Art
on: [push]
jobs:
  generate-art:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
      - run: npm install git-hash-art @napi-rs/canvas
      - run: npx git-hash-art current --output artwork/

Git Hooks

#!/bin/sh
# .git/hooks/post-commit
hash=$(git rev-parse HEAD)
npx git-hash-art generate $hash --output .git/artwork/

React Component

import { useEffect, useRef } from 'react';
import { renderToCanvas } from 'git-hash-art/browser';

function CommitArt({ hash, width = 256, height = 256 }) {
  const canvasRef = useRef(null);

  useEffect(() => {
    if (canvasRef.current) {
      renderToCanvas(canvasRef.current, hash, { width, height });
    }
  }, [hash, width, height]);

  return <canvas ref={canvasRef} width={width} height={height} />;
}

Contributing

Contributions are welcome! Please see our Contributing Guidelines for more details.

License

MIT License - see LICENSE for details.