project-timeline

Turn a git repository's history into a self-contained interactive HTML page — a cumulative code-growth curve over real calendar time, plus a scrollable, filterable commit list. One file, no server, no build step, no dependencies. Open it in a browser and you're looking at how your project actually grew.

The screenshot above is this repo's own commit history, rendered by the tool itself.

Why

git log tells you what happened, one line at a time. It doesn't show you shape — the bursts, the plateaus, the day a refactor deleted 40k lines. This turns that history into something you can see and share: a growth chart for the story, a filterable commit list for the detail, all inlined into a single .html you can email, drop in a slide, or open offline.

Features

• Code-growth chart — cumulative net lines over real timestamps, not commit index.
• Filterable commit list — by type (feat / fix / refactor / docs / chore …) and, in multi-project mode, by project.
• Multi-project on one axis — pass several repos; each gets its own color and a badge, trajectories overlaid so you can compare progress.
• Bilingual (中 / EN) — a top-right toggle flips the whole page. Each mode is fully single-language: in 中 mode every commit line is clean Chinese, in EN mode clean English — never a half-translated line. (See Bilingual below.)
• Zero dependencies — plain Python 3 + stdlib. The output is one HTML file with an inline <script>. Nothing to install, nothing to serve.

Quick start

python3 scripts/project-timeline.py /path/to/your/repo
# → writes /path/to/your/repo/timeline.html — open it in a browser

That's the whole tool: one script, one command.

Usage

# Single repo, full history (default)
python3 scripts/project-timeline.py ~/Code/my-project

# A date window
python3 scripts/project-timeline.py ~/Code/my-project --since 2026-05-01 --until 2026-05-20

# Several repos on one timeline, custom output
python3 scripts/project-timeline.py ~/projA ~/projB ~/projC --since "1 month ago" -o ~/timeline.html

# Not sure of the paths? Discover every git repo under your home dir:
python3 scripts/project-timeline.py --list

Options

Option	Effect
--since DATE	Only commits on/after DATE (anything git understands: 2026-05-01, "3 weeks ago").
--until DATE	Only commits on/before DATE.
-o, --output PATH	Where to write the HTML.
--title "..."	Custom page title.
--list	List every git repo found under the scan root, then exit.
--scan-root DIR	Where --list searches (default: home directory).
--translations PATH	A JSON file of clean per-language commit subjects — see below.

A "project" is any directory containing .git — code repos, note vaults, knowledge bases, content pipelines all count.

Bilingual

The page is English by default with a 中 toggle. The hard rule: each mode is fully single-language. Raw git subjects are messy (English-authored, Chinese-authored, or mixed, with feat: / fix: prefixes), so a clean bilingual page needs a clean subject in both languages for every commit.

You supply those via --translations trans.json:

[
  {"hash": "a1b2c3d", "zh": "新增章节导航与运行锁", "en": "Add chapter nav and run lock"},
  {"hash": "e4f5g6h", "zh": "修复暂停后无法恢复的问题", "en": "Fix resume after pause"}
]

The page swaps the whole subject by language, so a line is never half-Chinese, half-English. If a hash has no entry, it falls back to the raw git subject. Don't need bilingual? Skip the flag — the page still works, single-language.

Pairs naturally with an LLM coding agent: have it read the commit list, write clean zh + en for each, and re-run with --translations. SKILL.md documents that workflow (glossary + residue check) for Claude Code.

Use as a Claude Code skill

This repo is a Claude Code skill. Clone it into your skills directory and Claude can drive it for you in plain language ("make a timeline of my last month"):

git clone https://github.com/MasaHaruLab/project-timeline.git \
  ~/.claude/skills/project-timeline

SKILL.md tells the agent when to use it, how to discover repos, and how to generate the bilingual translations cleanly.

How it works

One file, scripts/project-timeline.py, plain Python + stdlib:

• classify_commit — buckets each commit by conventional-commit prefix (keyword fallback otherwise).
• build_model — reads git log --all per repo, computes cumulative net lines.
• generate_html — renders everything into one HTML string with an inline <script>.

No framework, no assets, no network. Edit the f-string template to restyle it.

中文

把一个 git 仓库的历史变成一页自包含的交互式 HTML:一条随真实日历推进的代码增长曲线, 加一份可按类型/项目筛选的提交列表。无服务、无构建、无依赖,浏览器直接打开。支持中/EN 一键切换, 且每种语言都是纯净单语——中文模式下每行都是干净中文,不夹英文。多仓库可叠在同一时间轴上对比。

python3 scripts/project-timeline.py /path/to/your/repo

License

MIT