Field notes.

01 / Getting started

Open your repository in one command.

RepoRewind requires Node.js 24 (recommended) or Node.js 22.13+, npm 10+, and Git. Run it inside any local Git repository; the checked-out branch is analyzed and opened in a loopback-only viewer automatically.

cd /path/to/your/repository
npx reporewind .

RepoRewind starts on a random 127.0.0.1 port behind an unpredictable session path. Use --no-open to print the URL without launching a browser and press Ctrl C to stop it. The live fictional demo remains available from the Live demo link.

The first npx run contacts npm to download RepoRewind. Repository analysis and viewing require no account, database, source upload, or application API.

02 / Analyze

Turn Git into a portable archive.

Use the explicit analyzer when you want a JSON archive for the hosted viewer or another tool. It emits commit structure and numeric diffs—not source file contents.

npx reporewind analyze /path/to/repository \
  --output ./reporewind-history.json

Import the resulting JSON file from the app. Contributor email addresses are omitted unless --include-emails is explicitly supplied. The chosen branch follows first-parent history, so each city frame represents a state that actually existed on that line of development.

Useful analyzer options

# Explore another branch or remote ref
npx reporewind /path/to/repository --branch release/3.x

# Bound an exceptionally large history
npx reporewind /path/to/repository --max-commits 5000

# Pipe clean JSON to another tool
npx reporewind analyze /path/to/repository --stdout \
  > reporewind-history.json

# Explicitly replace an existing archive
npx reporewind analyze /path/to/repository \
  --output ./reporewind-history.json --force

Run npx reporewind --help for the complete interface.

03 / Explore

Read the city grammar.

Search any trace

Press ⌘K, Ctrl K, or / to search files, commit messages and hashes, contributors, releases, or reachable branch tips. Narrow a query with file:, commit:, author:, release:, and branch:. Results move the timeline and open the relevant building when possible.

Compare two eras

Choose Pin this era, travel elsewhere, and open the temporal diff. RepoRewind follows rename chains, reports line and building deltas, ranks consequential sites, and recolors the city: mint for construction, amber for rebuilding, blue for renames, and red for demolition.

04 / Film export

Render a deterministic time-lapse.

Choose Export film for a fixed-timeline 1080p or 4K MP4/WebM film with dates, commit titles, statistics, merge and release cards, and a cinematic grade. Visual frame selection, timestamps, event pacing, and keyframe scheduling are deterministic. Hardware encoders may produce different final bytes.

• MP4 appears only when the exact browser and hardware pass the H.264 WebCodecs probe.
• WebM remains available as the compatibility path when supported by MediaRecorder.
• Exports are cancelable and render entirely in the current browser tab.
• Keep the tab visible during export and use 1080p if 4K exceeds available memory.

05 / Architecture

A local analyzer. A static browser.

The CLI invokes Git without a shell using fixed argument arrays and NUL-delimited output. The browser validates the archive, builds roughly 64 replay checkpoints plus activity indexes in a worker, and reconstructs frames through a bounded cache. Stable coordinates derive from the complete path set, preventing scrubbing from rearranging districts.

The WebGL city is lazy-loaded so import, validation, and search remain useful even if the renderer cannot initialize. Repeated buildings, ruins, travelers, and event signals use instanced geometry. Reduced-motion preferences suppress nonessential motion.

06 / Privacy & security

No hosted data plane.

RepoRewind has no backend, accounts, analytics, telemetry, cookies, or remote ingestion. The browser keeps imports and indexes in memory. Reload or close the tab to delete that browser copy. The analyzer writes one JSON file to the path selected by the operator.

Archives can still expose names, file paths, commit messages, and sanitized remotes. Review a generated archive before sharing it. Runtime validation caps files at 256 MB, 250,000 commits, and 2,000,000 change entries, and checks bounded strings, valid dates, relationships, known statuses, and rename invariants.

Contributor IDs are archive-local sequential identifiers, not hashes or reusable derivatives of email addresses.

07 / Troubleshooting

Common recovery paths.

The development server does not start

node --version
npm --version
npm ci
npm run dev

Vite binds to localhost and prints another URL when its preferred port is occupied.

The analyzer cannot read a repository

Confirm the path is a Git working tree and the selected ref exists. Repositories with no commits cannot produce a city. RepoRewind reports Git's failure without retrying a different ref or reading working-tree contents.

The city is replaced by a WebGL message

Enable hardware acceleration, update the browser or GPU driver, and retry in a current desktop browser. Search, archive validation, and CLI generation do not require WebGL.

Run the complete diagnostic gate

npm run verify

08 / Development

One complete quality gate.

The project provides formatting, strict React and accessibility linting, documentation and runtime-license checks, unit and integration tests, TypeScript validation, browser and CLI builds, and a high-severity dependency audit.