This is the official manual for the latest Org-mode release.
Org has the ability to track the consistency of a special category of TODOs, called “habits”. A habit has the following properties:
habitsmodule by customizing
STYLEis set to the value
.+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.
DONEstate 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:
** TODO Shave SCHEDULED: <2009-10-17 Sat .+2d/4d> - State "DONE" from "TODO" [2009-10-15 Thu] - State "DONE" from "TODO" [2009-10-12 Mon] - State "DONE" from "TODO" [2009-10-10 Sat] - State "DONE" from "TODO" [2009-10-04 Sun] - State "DONE" from "TODO" [2009-10-02 Fri] - State "DONE" from "TODO" [2009-09-29 Tue] - State "DONE" from "TODO" [2009-09-25 Fri] - State "DONE" from "TODO" [2009-09-19 Sat] - State "DONE" from "TODO" [2009-09-16 Wed] - State "DONE" from "TODO" [2009-09-12 Sat] :PROPERTIES: :STYLE: habit :LAST_REPEAT: [2009-10-19 Mon 00:36] :END:
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:
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.
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.