5.3.3 Tracking your habits

Org has the ability to track the consistency of a special category of TODOs,
called “habits”. A habit has the following properties:

You have enabled the habits module by customizing org-modules.

The habit is a TODO item, with a TODO keyword representing an open state.

The property STYLE is set to the value habit.

The TODO has a scheduled date, usually with a .+ style repeat
interval. A ++ style may be appropriate for habits with time
constraints, e.g., must be done on weekends, or a + style for an
unusual habit that can have a backlog, e.g., weekly reports.

The TODO may also have minimum and maximum ranges specified by using the
syntax ‘.+2d/3d’, which says that you want to do the task at least every
three days, but at most every two days.

You must also have state logging for the DONE state enabled
(see Tracking TODO state changes), in order for historical data to be
represented in the consistency graph. If it is not enabled it is not an
error, but the consistency graphs will be largely meaningless.

To give you an idea of what the above rules look like in action, here’s an
actual habit with some history:

What this habit says is: I want to shave at most every 2 days (given by the
SCHEDULED date and repeat interval) and at least every 4 days. If
today is the 15th, then the habit first appears in the agenda on Oct 17,
after the minimum of 2 days has elapsed, and will appear overdue on Oct 19,
after four days have elapsed.

What’s really useful about habits is that they are displayed along with a
consistency graph, to show how consistent you’ve been at getting that task
done in the past. This graph shows every day that the task was done over the
past three weeks, with colors for each day. The colors used are:

Blue

If the task wasn’t to be done yet on that day.

Green

If the task could have been done on that day.

Yellow

If the task was going to be overdue the next day.

Red

If the task was overdue on that day.

In addition to coloring each day, the day is also marked with an asterisk if
the task was actually done that day, and an exclamation mark to show where
the current day falls in the graph.

There are several configuration variables that can be used to change the way
habits are displayed in the agenda.

org-habit-graph-column

The buffer column at which the consistency graph should be drawn. This will
overwrite any text in that column, so it is a good idea to keep your habits’
titles brief and to the point.

org-habit-preceding-days

The amount of history, in days before today, to appear in consistency graphs.

org-habit-following-days

The number of days after today that will appear in consistency graphs.

org-habit-show-habits-only-for-today

If non-nil, only show habits in today’s agenda view. This is set to true by
default.

Lastly, pressing K in the agenda buffer will cause habits to
temporarily be disabled and they won’t appear at all. Press K again to
bring them back. They are also subject to tag filtering, if you have habits
which should only be done in certain contexts, for example.