relapse

What it does

Point it at a git repo. It runs gource to animate the commit history, pipes the frames through ffmpeg, and (optionally) burns captions you write yourself onto the result. The captions are the part that turns "watch some files appear" into a story.

STEP 1

timelapse.sh

Gource walks the commit graph; ffmpeg encodes 1080p mp4. Tunable via env vars (resolution, fps, seconds-per-day).

STEP 2

captions.txt

One line per caption: unix_ts|text. Pulled straight from git log --format='%ct|%s' if you want.

STEP 3

overlay.sh

Builds an SRT, burns subtitles into the video at the right moments. Stop after step 1 if you don't want captions.

Quickstart

You need gource, ffmpeg, and bash (git-bash works on Windows).

# clone relapse
git clone https://github.com/bitmousekatze/relapse.git
cd relapse
chmod +x timelapse.sh overlay.sh

# 1. render the gource animation
./timelapse.sh /path/to/your/repo my_project.mp4

# 2. (optional) edit captions.txt, then burn them in
./overlay.sh my_project.mp4 captions.txt my_project_final.mp4

Using Claude Code? The repo includes a CLAUDE.md that teaches Claude the full workflow — picking a sensible SECONDS_PER_DAY from your repo's history span, proposing caption candidates from git log, and avoiding the common pitfalls. Just open the cloned folder in Claude Code and say "make a timelapse of this repo."

Captions

captions.txt is plain text — one caption per line, format unix_timestamp|caption text. Lines starting with # are ignored. The first timestamp anchors t=0 in the video; later captions appear at the matching moment in the gource animation, scaled by SECONDS_PER_DAY.

1774821600|Project kickoff
1775426400|Major redesign
1776031200|New feature shipped
1776636000|v1.0 launch

Get a timestamp for any commit:

git log --format="%ct|%s" <hash> -1

Tuning

Both scripts read environment variables. Defaults are sensible.

timelapse.sh

var	default	what it does
`WIDTH` / `HEIGHT`	1920 / 1080	output resolution
`SECONDS_PER_DAY`	1	how fast time moves — bump up for short histories
`FPS`	60	output framerate
`HIDE`	`filenames,mouse,progress`	gource `--hide` values
`TITLE`	repo folder name	shown in the gource header

overlay.sh

var	default	what it does
`SECONDS_PER_DAY`	1	must match what timelapse.sh used
`HOLD`	4	seconds each caption stays on screen
`FONT_SIZE`	42
`BOX_OPACITY`	0.55	background box opacity behind text (0 = off)

Why it exists

relapse is a side-product of building HART — a platform for human-made art. We wanted to show the project's growth as a video, with captions calling out the moments that mattered. The scripts were small enough to share, so here they are. MIT licensed.