Skip to content

Getting started

Requirements

  • Node.js 20 or newer, inside a git repository
  • Optional: Ollama with a pulled model for --model

Basic usage

npx gitscribe                      # since the latest tag, template mode
npx gitscribe v1.0.0..HEAD         # explicit range
npx gitscribe --version v1.1.0     # set the heading
npx gitscribe HEAD~20..HEAD        # last 20 commits

Ranges are standard git revision ranges. With no range, gitscribe uses <latest tag>..HEAD, or all history if there are no tags.

Polishing with a local LLM

ollama pull llama3.2
npx gitscribe v1.0.0..HEAD --model llama3.2
npx gitscribe v1.0.0..HEAD --model llama3.2 --host http://localhost:11434

The commits are grouped first, then the categorized summary is sent to the model — so even a small local model produces good notes, and it can't invent changes that aren't in your history.

Best results

  • Use Conventional Commits (feat:, fix:, feat(scope)!: …). Non-conforming commits still show up under "Other".
  • Tag releases so the default range works (git tag v1.0.0).