Heatmap

Stability: experimental (org-extensions-stability)

A calendar heatmap in the style of GitHub's contribution graph: a column per week, a row per weekday, each day shaded by what was done that day.

require("org").setup({ extensions = { heatmap = { weeks = 26 } } })

:Org heatmap [clock|closed|habit] [tag|file], or the action
heatmap_open (<prefix>Vh). The kinds:
  clock   minutes clocked (CLOCK lines; a clock over midnight is split
          between the two days, a running clock counts up to now)
  closed  tasks marked done: CLOSED dates, - State "DONE" and
          - CLOSING NOTE log entries and the LAST_REPEAT property, once
          per task and day
  habit   the same for habits (STYLE: habit)

A habit only leaves a trace when marking it done logs something: with log_repeat on (the default) every completion is counted; with it off, only the last one (its LAST_REPEAT, which clocked tasks get too) is.

A bare word is a tag (+work and :work: work too); a path ending in .org is the source.

There are five shades: empty days, then four levels. By default the levels split the days with any value in quartiles; thresholds sets the lower bound of each level instead (e.g. { 30, 60, 120, 240 } minutes). The colours are mixed from the foreground of color_group and the background of Normal, and follow colorscheme changes; colors sets all five. Under the grid: the total, active days, the average of an active day, the current streak (ending today, or yesterday while today is empty), the longest one and the best day.

The cursor starts on today; the line at the bottom shows the selected day's total and its biggest entries. With weeks = 0 the number of weeks follows the editor's width when it is resized. Only the days shown are counted, so years of CLOCK lines cost little (100,000 clocks: about 30 ms).

Keys

  <Tab>     next kind (clock, closed, habit)
  h / l     previous / next week
  k / j     previous / next day
  <CR>      the agenda of that day (a split heatmap stays open)
  r         refresh
  <Esc> q   quit

Options (defaults)

  kind          "clock"
  source, tag "agenda", nil
  weeks         0 (fit the window, at most 53)
  cell          "■"
  thresholds    nil
  color_group   "DiagnosticOk"
  colors        nil
  layout        "float"
  keys          next_kind, prev_week, next_week, next_day,
                  prev_day, agenda, refresh, quit

Highlight groups: OrgHeatmap0 to OrgHeatmap4 (the shades, set from the options), OrgHeatmapTitle, OrgHeatmapHint, OrgHeatmapLabel, OrgHeatmapValue, OrgHeatmapDetail.