Knowledge Islands

Projects / git-almanac

Inspect one local Git repository's calendars, authors and reports offline.

Reads a single checkout and reports its calendars, authors, contributors and activity without contacting a forge, so repository history can be reviewed offline.

Released command-line tool · currently published as v0.1.0 · preview

The problem

What this is for.

Seeing the shape of a repository's history normally means a forge account, a network round trip, and whatever visualisation that forge happens to offer. Git Almanac reads the checkout in front of you and reports the same material — calendars, authors, contributors, activity — without contacting anything, which also means it works for repositories that are on no forge at all.

Whose problem

Whether it is yours.

You want this if you need to see who worked on something, when, and how the activity was distributed: reviewing a handover, writing a retrospective, or looking at a repository you have just inherited.

Capabilities

What it actually does.

  • calendar: activity calendars rendered as terminal output, SVG, HTML or JSON, with light and dark themes.
  • authors and contributors: per-identity reporting, filterable by date range and by path within the repository.
  • report: a complete linked static report written under the repository, rebuilt automatically when its inputs change and leaving unowned files alone.
  • A documented counting contract, so a number means the same thing on every run and between repositories.
  • Output to a file, a directory or standard output, with the format inferred from the extension unless you state it.

State

How finished it is.

Published as v0.1.0 and labelled preview — the newest of the four tools, and the one most likely to gain options. The counting contract and the report manifest are the settled parts.

Using it

How to start.

Install it and run it inside any checkout to report that repository's calendars, authors, contributors and activity.

Prefer Homebrew.

The Knowledge Islands tap packages git-almanac, so Homebrew owns upgrades and removal. Naming the tap in the argument taps it implicitly.

brew install knowledgeislands/tap/git-almanac

Or use the stable installer endpoint.

The URL below is this site's stable machine route. It redirects to the installer published at v0.1.0 in the source repository, which owns the installer's behaviour and any signature or checksum verification it performs.

curl -fsSL https://knowledgeislands.info/install/git-almanac | sh

Boundaries

What it deliberately does not do.

It reads one local repository and writes only where you point it. It makes no network request and contacts no forge, so it reports nothing about pull requests, issues or reviews: none of that lives in the checkout. It never modifies repository history.

Authority

What this repository owns.

Owns offline reporting over a single Git checkout. It contacts no forge, writes nothing, and holds no authority over how a repository is governed.

That boundary is deliberate. The ecosystem separates philosophy, engineering discipline, capability semantics, portable standards, and executable behaviour so that none of them can quietly absorb another. The full directory shows where this project sits relative to the rest.

Nearby

The rest of the released set.

  • ki — The Knowledge Islands command-line interface.
  • mgit — Run commands across many Git repositories at once.
  • rig — A declarative description manager for a person's working setup.

See every public project, or go straight to the released command-line tools.