org-heatmap

Introduction

Org-heatmap is an Emacs package for Org-mode users to keep track of their task consistency in a visual manner. It presents an overview heatmap on Org-mode agendas or Calendar, providing visual representation of task completions and task statistics.

Contents

• Screenshots
• Installation
• Usage
  • Functions
  • Variables
  • Examples
• TODOs

Screenshots

Show habit completion overview in org agenda buffer.

Display habit heatmap in Calendar

Add habit statistics after habits: (current streak, max streak and total done number).

Installation

You must also install these packages:

• Emacs >= 28.2
• emacsql >= 3.1.1
• org-mode >= 9.6

ps. I have not tested in the lower versions of the mentioned packages.

Then put org-heatmap.el in your load-path, and eval:

 (use-package org-habit
	:custom
	(org-habit-graph-column 1)
	(org-habit-preceding-days 10)
	(org-habit-following-days 1)
	(org-habit-show-habits-only-for-today nil))

 (use-package org-heatmap
	:init
	(add-to-list 'load-path "/path-to/emacsql/")
	(add-to-list 'load-path "/path-to/org-heatmap/")
	(require 'org-heatmap)
	:after (org)
	:custom
	(org-agenda-files '("/path-to/org-heatmap/examples/examples.org"))
	(org-heatmap-db-location "/path-to/org-heatmap/examples/org-heatmap.db")
	:config
	(org-heatmap-mode))

Usage

Functions

Note: When you run these functions for the first time, you may experience some lag (the lag time depends on the length of your habits record).

• org-heatmap-habit-draw-overview

  Draw an overview heatmap for the habit at point. When your cursor is on a habit in org-agenda-mode, you can call this function or press h to generate a heatmap for the habit. Call this function or press h again will erase the heatmap.

  You can hover your mouse over a rectangle, and you will see the time you spent on the habit on that day. Clicking the rectangle will redirect you to an agenda view of that day.

Note: This function uses org-heatmap-rectangle to draw heatmap, and for different fonts, the display effect may vary. The font used in the screenshots is Cascadia Mono. You can choose suitable characters based on the font you are using.

• org-heatmap-calendar

  Display a three-month Gregorian calendar. Add highlights indicating the activities on the current calendar date.

  Whenever you complete a task (when a item is changed to DONE in org-mode.), the activity counter for the day will increase by one and update the database. You can use org-heatmap-calendar to generate a heatmap of your everyday activity, and use built-in functions such as org-calendar-goto-agenda to see details.

• org-heatmap-habit-calendar

  Like org-heatmap-calendar, display a three-month Gregorian calendar for the habit at point.

  Add highlights indicating the times spent on the habit on the current calendar date.

  Whenever you complete a habit (when a item is changed to DONE in org-mode.), org-heatmap will record the time you spent on this habit today and write it to the database. You can use this command to generate a heatmap of your everyday time spent, and use built-in functions such as org-calendar-goto-agenda to see details.

• org-heatmap-calendar-query

  In Calendar-mode with org-heatmap highlights, you can use this function (bound to f in calendar-mode) to get information about the activities on the current calendar date.

  When used with org-heatmap-calendar, it shows how many items are done on the current calendar date.

  When used with org-heatmap-habit-calendar, it shows how many times is spent on the habit on the current calendar date.

• org-heatmap-adjust

  Change the number of done items on the current calendar date, used with org-heatmap-calendar (bound to j in calendar-mdoe).

  Note that this function is not applied to org-heatmap-habit-calendar for now.

• org-heatmap-db--drop

  Delete a table from org-heatmap database.

Variables

• org-heatmap-rectangle

  Characters used to draw overview heatmap.

  When your overview heatmap is not displayed ideally, you can consider changing to suitable characters.

• org-heatmap-enable-habit-statics

  Whether to shoaw habit statics.

  Add three data after the habit entry: (current streak, max streak and total done number).

  Note: If you want to chage this variable, please set it before loading org-heatmap or use setopt.

• org-heatmap-threshold

  Choose a different face based on the threshold arrived.

• org-heatmap-db-location

  Default database location.

TODOs

• [ ] Speed up database writes
• [ ] Add project management
• [ ] Record more data
• [ ] Support for more complex database operations
• [ ] Support for more data display modes