RepoCity
Work from the RepoCity repository root. The analyzed repository is read-only input; generate data only inside RepoCity unless the user chooses another output.
Build a city
Resolve the repository and ref. A local path, Git URL, or owner/repository slug is accepted. For a monorepo, inspect its tree and choose coherent --include paths before generating a large replay.
Copy template/repocity.config.json to public/repocity.config.json when starting a new customization. Set the title/palette and adjust classifiers before changing rendering code.
Run the extractor:
python3 scripts/build_replay.py REPOSITORY --ref REF --output public/data/replay.json
Add repeatable --include PATHSPEC and --exclude GLOB filters when needed. Read references/workflow.md for exact local, remote, and monorepo commands and failure handling.
Inspect the printed category totals. Fixtures/generated content belongs in the caveat summary, not the default source/test city. If source or test totals look wrong, fix classification patterns and regenerate.
Install and validate:
npm install
npm run test:data
npm run typecheck
npm run build
Render the app in a WebGL browser. Check hit detection, tooltips, first and final states, a normal mixed add/remove commit, and the largest add/remove events. At 1×, robots must reach the roof before their laser begins; at high speed, every crossed commit must still emit effects.
Preserve these invariants
- Animate first-parent events because adjacent events must be real tree states. Keep all reachable commits as metadata and aggregate explicit signals from branch commits into the event that integrates them.
- Keep additions and removals separate. A large deletion is meaningful work, not negative growth.
- Treat binary files separately and verify final text LOC against Git.
- Never rename
unmarked authorship to human or manual; absence of an explicit signal proves neither.
- Do not add GitHub PR, issue, factory, workspace, or article-framework dependencies to the generic path.
- Keep source/test building colors distinct from add/remove effect colors.
Customize deliberately
Read references/customization.md before changing layouts, categories, lasers, robots, timing, or camera behavior. Read references/replay-schema.md before changing the extractor or JSON contract.
Prefer configuration changes for names, colors, defaults, path categories, and identity patterns. Edit the model or Three.js scene only when the requested behavior cannot be expressed in public/repocity.config.json.
1---2name: repocity3description: Build or customize a standalone animated Three.js code city from a local or GitHub repository's Git history. Use for replayable file/LOC treemaps, commit robots and add/remove effects, test-versus-source views, or adapting RepoCity to a monorepo; do not use for PR/workflow analytics that require hosting-provider APIs.4---56# RepoCity78Work from the RepoCity repository root. The analyzed repository is read-only input; generate data only inside RepoCity unless the user chooses another output.910## Build a city11121. Resolve the repository and ref. A local path, Git URL, or `owner/repository` slug is accepted. For a monorepo, inspect its tree and choose coherent `--include` paths before generating a large replay.132. Copy `template/repocity.config.json` to `public/repocity.config.json` when starting a new customization. Set the title/palette and adjust classifiers before changing rendering code.143. Run the extractor:1516 ```bash17 python3 scripts/build_replay.py REPOSITORY --ref REF --output public/data/replay.json18 ```1920 Add repeatable `--include PATHSPEC` and `--exclude GLOB` filters when needed. Read [references/workflow.md](references/workflow.md) for exact local, remote, and monorepo commands and failure handling.214. Inspect the printed category totals. Fixtures/generated content belongs in the caveat summary, not the default source/test city. If source or test totals look wrong, fix classification patterns and regenerate.225. Install and validate:2324 ```bash25 npm install26 npm run test:data27 npm run typecheck28 npm run build29 ```30316. Render the app in a WebGL browser. Check hit detection, tooltips, first and final states, a normal mixed add/remove commit, and the largest add/remove events. At 1×, robots must reach the roof before their laser begins; at high speed, every crossed commit must still emit effects.3233## Preserve these invariants3435- Animate first-parent events because adjacent events must be real tree states. Keep all reachable commits as metadata and aggregate explicit signals from branch commits into the event that integrates them.36- Keep additions and removals separate. A large deletion is meaningful work, not negative growth.37- Treat binary files separately and verify final text LOC against Git.38- Never rename `unmarked` authorship to `human` or `manual`; absence of an explicit signal proves neither.39- Do not add GitHub PR, issue, factory, workspace, or article-framework dependencies to the generic path.40- Keep source/test building colors distinct from add/remove effect colors.4142## Customize deliberately4344Read [references/customization.md](references/customization.md) before changing layouts, categories, lasers, robots, timing, or camera behavior. Read [references/replay-schema.md](references/replay-schema.md) before changing the extractor or JSON contract.4546Prefer configuration changes for names, colors, defaults, path categories, and identity patterns. Edit the model or Three.js scene only when the requested behavior cannot be expressed in `public/repocity.config.json`.
enjalot