org: Tracking your habits
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:
1. You have enabled the ‘habits’ module by customizing ‘org-modules’.
2. The habit is a TODO item, with a TODO keyword representing an open
state.
3. The property ‘STYLE’ is set to the value ‘habit’.
4. 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.
5. 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.
6. You must also have state logging for the ‘DONE’ state enabled
(
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:
‘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.
Info Catalog
org: Tracking TODO state changes
org: Progress logging