Making Getting Things Done easier is etm's goal. Getting Things Done, commonly abbreviated as GTD, is an action management method, and the title of a extremely popular book by David Allen. GTD rests on the common sense notion that with a complete and current inventory of all commitments, organized and reviewed in a systematic way, the mind is freed from the job of remembering everything that needs to be done, and can focus on actually performing those tasks.
Three observations are critical:
GTD thus requires convenient methods for:
|planning:||storing and organizing all the bits.|
|acting:||displaying just the information you need, when you need it.|
|reviewing:||checking the status of all items your projects.|
etm allows you to store and organize your commitments using a simple, intuitive format using plain text files. Tasks can be entered in an 'outline format' in which which parent tasks are treated as prerequisites for their lower level offspring tasks.
Your commitments can be viewed grouped and sorted by date, context, keyword, location, priority or project. Using the outline groupby option '-g F' you can check the status of all items in your projects regardless of their due dates.You can hide finished tasks, or waiting tasks, or events. You can display only items whose contexts or keywords match a given regular expression. You can display busy and/or free times for an arbitrary period. You can prepare a ledger view of your time broken down by any combination of date, keyword, and/or context. You can export matchingitems in vCal/iCal format.
In short, etm makes it easy for you to store and organize all the bits and to display just the information you need, when you need it.
The current date and time is displayed at the left. This is followed by the interval of days currently being displayed and an entry area which permits a case-insensitve search for all items matching a regular expression. Matching items are listed in the outline panel below.
The color of each month day number reflects the number of minutes of scheduled events for that date. The days of the currently selected week (the selected day and the six following days) are highlighted.
With the focus in the calendar, the right and left arrow keys change the selection forward and backward one day at a time. Down and up arrow keys change the selection forward and backward one week at a time and Page Down and Page Up change the selection one month at a time.
The periods of schduled events for the selected days in calendar are highlighted. Clicking on a highlighted area will select the corresponding event in the outline panel and double clicking will open the event for editing in the details panel.
This panel displays data reflecting the current options in outline form. When an item is selected, the item's details are displayed below in the details panel.
When an item is selected in the outline panel, the item's details are displayed here.
Additionally, this area is used to edit exising items, to create new items and to set the options for the outline panel display and for busy reports. See Options for Actions, Events, Notes and Tasks and Options for Outline and Busy Views for details.
Press Shift-Return or Ctrl-S to process the contents or press Escape to cancel.
At the left, the status line displays a permanent reminder that pressing F1 activates the help system. If one or more alarms is in the queue for the current date, then the time of the next scheduled alarm follows. This is followed by a list of the current display options. The remaining space is used to display a variety of information. If a timer is running for an action, for instance, then the name of the action and the current elapsed time and status (running or paused) is displayed.
In etm there are four types of items:
A record of the time-consuming action required to complete a task or participate in an event. Actions are not reminders, they are instead records of how time was actually spent. Action lines begin with a '~' character.
Something that will happen on a particular day (or days) and, perhaps, at particular times. Alerts are optional for events with starting times. Event lines begin with a '**' character.
A record of some useful information. Note lines begin with a '!' character.
Something that needs to be done. It may or may not have a due date. Task lines begin with one or more '-' or '+' characters.
Etm data files begin with a 'project line' that gives the project title and, perhaps, options. Items follow with each item occupying one or more lines. Each item begins with '~', '*', '!', '-' or '+' as the first character on the line, followed by the title of the item and then field keys and values. The item continues either until the file ends or another line is found that begins with '~', '*', '!', '-' or '+'. E.g,
----------file begins------------------------------------- the title of the project file ... * my event title @d 8/23 @s 9a @n A note for my event that continues on the next line. ... ----------file ends --------------------------------------
See Options for Actions, Events, Notes and Tasks for details.
Note that item options added to the project line become the defaults for each of the items in the same file. Suppose, for example, that the project file concerns 'Project A' for client 'John Smith'. Then adding '@k Smith, John:Project A' to the project line would set the client and project keyword for every item in the file.
To create a new event, press 'e' (or '*') and the details bar will be focused and ready for your entry.To see how this works, create a test entry such as
* test event @s 3p @e 4p
and press Shift and Return at the same time to record your event. You will then be prompted for a file to store the entry. Before you choose a file, drag the file selection dialog to one side and notice that your entry has been changed to something like
* test event @d 2011-06-25 @s (3:00p) @e +1:00 @z Europe/Paris
with the starting time expanded, the ending time replaced with the duration of the event and with the current date and local timezone added.
Creating an action (press 'a' or '~'), a note (press 'n' or '!') or a task (press 't', '-' or '+') is similar.
An event without either a starting time or an extent (duratation) is regarded as an all day event. All day events are displayed at the top of the daily schedule.
An event with one or more staring times but without an extent is regarded as a reminder. E.g.,
* test reminder @d 6/25 @s (10a, 2p, 4p) @a (15, 0)
would create a reminder for 10:00am, 2:00pm and 4:00pm on June 25 with alerts to be triggered at both 15 minutes before and at the time of the reminder. Reminders, even with multiple starting times, are displayed only once in the daily schedule.
An event with one or more starting times and an extent is treated as a scheduled event. Each starting time is displayed on the daily schedule and the corresponding periods are displayed in the busy panel.
An action might be regarded as an event with an extent but without a starting time but since actions are important for uses such as time billing, they are treated as a separate type. When an action is created by pressing either 'a' or '~', you can provide an initial entry and then press Shift-Return. A timer will then be started which can be paused and restarted by pressing 'a'. A reminder will be sounded periodically to remind you when the timer is running. You can press 'A' to stop the timer and make final changes to the action entry. The total elapsed time will be entered automatically.
A note is created by pressing either 'n' or '!. You could, for example, use notes to keep a daily log or diary. As with other items, new lines and other white space within a field are preserved and can be used for rudimentary formatting.
A task is created by pressing either 't', '-' or '+'. A task without an "@d" entry is regarded as a floating task and always appears to be due on the current date. A task with an "@d" entry is treated as being due on the specified date. If unfinished, it will appear on the daily schedule for the due date. If it becomes past due then it will also appear on the daily schedule for the current date with a reminder of the number of days it is past due. Etm not only can nag you about past due tasks, it can also alert you to an upcomming due date as well. E.g.
- take out trash @d 6/1 @r w @w FR @b 1 @o s
would remind you to put out the trash each Friday and, because of the "@b 1" entry, you would be notified of this beginning one day before the due date. The "@o s" in this entry, by the way, means that when the task is (o)verdue, etm should (s)kip the nagging and simply inform you of the next due date.
When a task is completed, it will appear in the daily schedule for the date it was finished with an indication that it has been completed.
Tasks in etm can have prerequisites. E.g.,
- check sizes of existing air filters -- buy replacement filters --- install new air filters
The outline structure gives the dependencies.
Tasks with unfinished prerequisites are classified as waiting by etm.
It is also possible for tasks to have multiple, independent prerequisites. E.g.,
- borrow power drill from Ed + pick up hardware -- repair door
Here the '+' adds 'borrow' to 'pick up' as a prerequisite for 'repair'.
Thanks to etm's use of dateutil, events and tasks can be repeated in powerful ways. E.g.,
* payday @d 6/1 @r m @w (MO,TU,WE,TH,FR) @m (-3,-2,-1) @S -1
would repeat on the last weekday in each month.
See Options for Actions, Events, Notes and Tasks for details.
A variety of options are available in etm to classify items:
For GTD (Getting Things Done) usage. Typical contexts include 'home', 'office', 'phone', 'computer' and 'errands'. If you are about to run errands, for example, you could use the outline display option -c errands to show only items with the context 'errands'.
For time billing. One pattern of usage would be to use keywords with the format 'client:project'. Then the outline display option -g (k1, (y,m), k2) would group and total times first by k1 (client), then by year and month combined and finally by k2 (project).
This field is supported when exporting in vCal format.
This field is supported when exporting in vCal format. Note that etm's integer priorities may be converted by some applications. iCal, for example, makes the following conversions:etm iCal ----- ------ 1-4 High 5 Medium 6-9 Low
This field is exported as 'categories' in vCal format. Multiple tags can be used when separated by commas and enclosed in parentheses.
For multiuser application. This field could be used to distinguish responsibility for billing times or task completion.
Items can be grouped and/or filtered by any combination of these classifiers and additionally by the name of the file and by the title of the project (from the first line of the file). For details of these and other options see Options for Outline and Busy Views.
Fuzzy Date Parsing
Suppose that it is currently Tuesday, February 17, 2009. Then in fields calling for a date:entered after fuzzy parsing --------- --------------------- tue 2009-02-17 thu 2009-02-19 mon 2009-02-23 23 2009-02-23 mar 2 2009-03-02 3/2 2009-03-02 +0 2009-02-17 (today) +1 2009-02-18 (tomorrow) +45 2009-04-03 (45 days from now) -1 2009-02-16 (yesterday) -90 2008-11-19 (90 days ago)
Fuzzy Time Parsing
Similarly, in fields calling for a time, entering '6p' would give after parsing '06:00PM' and so would '18:00'.
A further option is available when entering the extent, @e, for an event. The extent can be specified as the duration or extent of the event by preceeding the entry with a plus sign or, for events with a single starting time, by the ending time of the event. For example, all of the following are equivalent:@s 9a @e 10:30a @s 9a @e +90m @s 9a @e +90 @s 9a @e +1:30 @s 9a @e +1h 30m
However entered, etm would record the extent as '@e +1:30'.
Alerts for an event or reminder are set by adding an '@a' field to the event, e.g.,* phone conference with CR @d tue @s 2p @a (15, 5)
would set alerts for 15 minutes before the event and 5 minutes before the event. What happens when an alert is triggered is determined by the setting for 'alertcmd' in '~/.etm/rc'. With the default settingalertcmd = ''
a message would be displayed with the current time and the text of the message.
Alternatively, on a mac (OS X leopard), you could usealertcmd = '''say -v "Alex" "%(t)s. %(m)s."'''
to announce the message using the voice 'Alex' oralertcmd = '''say -v "Alex" "%(t)s. %(m)s."; growlnotify -t %(T)s -m "%(m)s"'''
(all one one line) to have the message both spoken and displayed using growl. On linux systems with 'notify-send' (provided by libnotify-bin), a warning sound followed by a 5 second popup display of the alert message could be produced withalertcmd = '''aplay /usr/share/sounds/purple/receive.wav 2> /dev/null; notify-send "%(T)s" "%(m)s" -t 5000'''
With -t 0 the display would remain until you dismiss it.
Alternatively, you could receive an email reminder withalertcmd = '''echo "%(m)s" | mail -s "etm alert at %(T)s" email@example.com"'''
if either sendmail or postfix is enabled on your system.
More generally, any command that will accept a string argument could be used.
When items are processed whose titles contain a string of the form !YYYY!, the string will be replaced with N## where N is the number of years from YYYY until the current year and ## is either 'st', 'nd', 'rd', or 'th'. For example, on August 23, 2010, the event* Will's !1985! birthday @d 2010-01-01 @r y @M 8 @m 23
would be displayed asWill's 25th birthday
In displays when grouping by date, etm will only display an item or trigger an alert on the date of its starting time. This means, for example, that the event* event @d 2010-12-01 @s 23:00 @e +2h
would only display on December 1 even though the event lasts until 1:00 on December 2. Similarly* event @d 2010-12-01 @s 1:00 @a (90, 30)
would trigger an alert at 0:30 on 12/1 but would not trigger an alert at 23:30 on 11/30.
Dates and times in etm either have time zone information associated with them or are treated as 'naive' date times. The treatment of date times depends upon whether or not the item includes an @z ZONE entry and, if it does, the value of ZONE. There are two possibilities for lines in the etm data files:
Item date times are interpreted as naive and are displayed unchanged.
E.g., the events:
* event @d 2010-11-28 @s 17:00 * event @d 2010-11-28 @s 17:00 @z none
would both be interpreted as starting at 17:00 on Nov 28 no matter what the time zone of the user's system. Some calendar applications would refer to these as floating events.
The item has an @z ZONE entry and the value of ZONE is not 'none'.
Item date times are interpreted as being in ZONE time and would be displayed as local date times for the user's system time zone. E.g., the event:* event @d 2010-12-01 @s 12:00 @z Pacific/Auckland
would be interpreted as starting at 12:00 December 1 Pacific/Auckland time and, if the users time zone were US/Eastern, would be displayed as starting at 18:00 on November 30.
When creating new items in etm, time zone information that you enter, provided that it is valid, will be left unchanged. This includes '@z none'. What happens when you create an item without an '@z' entry depends upon the value of 'auto_set_timezone' in your rc file. If 'True' (the default), then '@z ZONE' will automatically be appended to your entry with ZONE equal to your local time zone. If 'False', then your entry will be saved as it is and its dates and times will subsequently be interpreted as naive.
When entering zone information in etm, completion is available. Suppose, for example, that you have entered
* event @d 12/1 @s 12 @z US
and press Ctrl-Space with the cursor after 'US'. Then etm would display a pop-up list of possible completions from 'timezones' in your rc file for your selection. With the default value of 'timezones', this list would include 'US/Alaska', 'US/Central', 'US/Eastern' and the others that begin with 'US'.
Zone information in etm, other than 'none', automatically adjusts for daylight saving. Consider, for example, the following two events:
* event @d 2010-08-01 @s 17:00 @z US/Eastern * event @d 2010-12-01 @s 17:00 @z US/Eastern
While both would display on the given dates as starting at 17:00, this would be EDT for the first and EST for the second. This means that when you change the date for a task with zone information, you do not need to concern yourself with making adjustments for daylight saving.
The values of 'due_hour' (0-23) and 'due_minute' (0-59) from your rc file set the implicit times for tasks and other items without starting times. These values have no effect unless '@z ZONE' is set and ZONE is not equal to 'none'. The default, 'due_hour = 12' and 'due_minute = 0', corresponds to most expectations. E.g, a task that is due at noon on November 30 in New York (12:00 11/30 EST), would also be due on November 30 in London (17:00 11/30 GMT) and Honolulu (7:00 11/30 HST), but would be due on December 1 on the other side of the international date line in Tokyo (2:00 12/1 JST) and Singapore (1:00 12/1 SGT).
Grouping and sorting is controlled by the '-g' outline display option. The default
groups and sorts items by y)ear, m)onth and d)ay combined to give output like
Fri Jun 3 2011 (17) 3.5h 3:00p Conference ... 16 other items for June 3 Sat Jun 4 2011 (3) 1.0h ... 3 items for June 4
As another example, suppose keywords have the format 'client name:project name'. Then
-g (k1, (y,q,m), k2)
would group and sort by k1 (client name), then y)ear, q)uarter and m)onth combined and finally k2 (project name) to give output such as:
client 1 (3) 1.5h 2nd quarter 2011 Jun (3) 1.5h project E (3) 1.5h ... 3 items for 'client 1:project E' ...
-g (k1, (y,m,d), T) -d 0 -T 1
would group by k1 (client), then y)ear, m)onth and d)ay combined and finally T (item title). With details omitted, '-d 0' and totals first, '-T 1', the output would be similar to:
3.6h) client 1 (4) 2.0h) Fri Aug 5 2011 (2) 1.0h) prepare order (1) 0.5h) review invoice (1) ... ...
Note in the examples above that the ledger information '(number of included items) total time' is automatically appended to each node.
Available group/sort keys include y (year), m (month), d (day), e (extent), w (week number in year), q (quarter number), c (context), l (location), u (user), s (item type), and k1, k2, k3, (first, second and all remaining keywords). E.g. with '@k A:B:C:D:E', k1 would be 'A', k2 would be 'B' and k3 would be 'C:D:E'.
A final groupby option is to use '-g F' to group and sort by project F)ile. When this option is used other groupby and begin and end date options are ignored to show all items outlined by project file.
show all your notes outlined by project file:-g F -o !n
show all your unfinished tasks organized by project file:-g F -o !ut
Etm supports the use of case-insensitive, regular expression matching when searching and when filtering by context, keyword, location, priority, tag, user, file and/or project. E.g., an option setting which included '-c errands' would limit the display to items which contain 'errands' in the context field.
Alternatively, '-c !errands' would limit the display to items which do not have contexts matching 'errands'. Note: when using the command line the latter expression should be wrapped in single quotes, e.g.,
e.py o -c '!errands'
An excellent introduction to the use of regular expressions is provided by
Skip down to 'Matching Patterns in Text: The Basics' and note that the surrounding '/' delimiters are not needed in etm.
Entering a regular expession in the search bar of the GUI or passing the expression as an option to outline view using '-s' works differently than the filters described above in two ways:
1) Search applies to all items processed by etm. This means all undated items and at least one occurance of all dated items are included in searches. Filters, on the other hand, apply only to undated items and those between '-b BEGIN' (default today) and '-e END' (default 6 days after BEGIN).
2) Search identifies items in which any field matches the expression. Thus '-s smith' would match items that have 'smith' (case insensitive) in the title, context, keyword, location, note or anywhere else. On the other hand, a filter such as '-k smith' would only match items with 'smith' in the keyword field.
an illustrative project
Suppose there is a department meeting at noon on Friday, March 13, 2009, that you want to remember. With etm, the following text file would accomplish this:
---- file begins ----------------- report * staff meeting @c work @d 2009-03-13 @s 12:00p ---- file ends -------------------
The asterisk before 'staff meeting' means that this line describes an event. The staff meeting would now appear on your agenda for March 13 associated with the project report and the context work. If you would like to be alerted 15 and 10 minutes before the meeting and be reminded to bring a report with you to the meeting, then change the event line to:
* staff meeting @c work @d 2009-03-13 @s 12:00p @a 15, 10 @n bring report
To make things more interesting, suppose that you are responsible for preparing the report and presenting it at the meeting. The following:
---- file begins ----------------- report @c work @d 2009-03-13 * staff meeting @s 12:00p @a 15, 10 @n bring report - prepare report @b 1 ---- file ends -------------------
would remind you of this task one day before the meeting.
Still more interesting, suppose you need sales data from Joe and inventory data from Mary to prepare the report. Just add two more tasks:
---- file begins ----------------- report @c work @d 2009-03-13 * staff meeting @s 12:00p @a 15, 10 @n bring report - get sales from Joe @b 2 - get inventory from Mary @b 2 - prepare report @b 1 ---- file ends -------------------
Tasks can begin with one or more '-' '+' characters. The tasks can be regarded as an outline with the number of '-' or '+' characters determining the level and thus the prerequisites of the task. Tasks at the same level in a branch of the outline can be completed in any order but none can be started until all higher level tasks in the same branch have been completed. The single minus sign before Joe, Mary and report mean that these tasks are at the same (first) level and thus can be completed in any order.
If we need to complete Mary before beginning report then the following should be used:
---- file begins ----------------- report @c work @d 2009-03-13 * staff meeting @s 12:00p @a 15, 10 @n bring report - get sales from Joe @b 2 - get inventory from Mary @b 2 -- prepare report @b 1 ---- file ends -------------------
The two minus signs before report mean that it is nested under Mary and thus that Mary must be finished before report can begin.
If we really need to complete both Joe and Mary before beginning report then we can use a plus sign before Mary to add the previous task, Joe, to the prerequisites for any tasks, such as report, that depend upon Mary:
---- file begins ----------------- report @c work @d 2009-03-13 * staff meeting @s 12:00p @a 15, 10 @n bring report - get sales from Joe @b 2 + get inventory from Mary @b 2 -- prepare report @b 1 ---- file ends -------------------
Finally, the following slight modification would cover such meetings when they repeat on the second Friday of every month:
---- file begins ----------------- report @c work @d 2009-03-13 @r m @w FR(2) * staff meeting @s 12:00p @a 15, 10 @n bring report - get sales from Joe @b 2 + get inventory from Mary @b 2 -- prepare report @b 1 ---- file ends -------------------
What could be easier?
In the GUI, press either 'a' or '~' to create an action, 'e' or '*' to create an event, 'n' or '!' to create a note and either 't', '-' or '+' to create a task. Optional (O) and required (R) fields are listed below.
|@d||DATE||R||R||O||O||a date (fuzzy parsed).|
|@b||BEGIN||O||an integer number of days before a task with a due date at which to begin giving advance warnings of the upcomming due date.|
|@f||FINISH||O||a date or, for a repeating task, a list of dates in parentheses, on which the task was completed (fuzzy parsed).|
|@s||STARTTIME||O||a time or a list of times in parentheses (fuzzy parsed). An event without a start time is regarded as an all day event.|
|@a||ALERTS||O||an interger or a list of integer minutes in parentheses. Alerts will be triggered at times corresponding the these numbers of minutes before STARTTIME.|
|@A||ALTCMD||O||an alternative command to run when alerts are triggered instead of the default. Accepts the same substitution strings as alertcmd in the etm rc file.|
|@e||EXTENT||R||O||O||a integer number of minutes preceeded by a "+" (plus sign). Optionally, an ending time (fuzzy parsed) can be given for an event with a single starting time. An event with one or more start times but without an extent is treated as a reminder.|
|@n||NOTE||O||O||O||O||a string. Newlines and leading whitespace are preserved within the body of the note.|
|@g||GOTO||O||O||O||O||a file path or URL, or a comma separated list of paths or URLs in parentheses, to be opened using the system default application if the user presses "g" when the item is selected. If a list is given, a selection list will be provided from which to choose the item to be opened.|
|@z||TIMEZONE||O||O||O||O||a time zone, e.g., "US/Eastern".|
|@k||KEYWORD||O||O||O||O||a string which optionally contains colons, e.g, "@k first:second:third:fourth". When grouping/sorting 'k1' would refer to 'first', 'k2' to 'second' and 'k3' to 'third:fourth'.|
|@p||PRIORITY||O||an integer in the range from 1 (highest priority) to 9 (lowest priority).|
|@t||TAGS||O||O||O||O||a string or a comma separated list of strings in parenthesis, e.g, "@t (tag 1, tag 2)".|
Events and task can be repeated using further keys and values
|@r||REPEAT||a single character from "d" (daily), "w" (weekly), "m" (monthly), "y" (yearly) or "l" (list) describing the frequency at which the event or task repeats. This field is always required for repeating items..|
|@i||INTERVAL||a positive integer interval at which the task repeats. E.g., "@r w @i 3" would repeat every third week. Default: 1.|
|@u||UNTIL||a date at which repetitions should end (fuzzy parsed). Default: none, i.e., repetitions continue forever.|
|@C||COUNT||an integer number of repetitions to allow. E.g., "@d 2011-01-01 @r m @m (15, 30) @C 4" would repeat on Jan 15, Jan 30, Feb 15 and Mar 15 of 2011. Default: none, i.e., repetitions continue forever.|
|@w||WEEKDAY||a string or list of strings in parentheses from "MO", "TU", "WE", "TH", "FR", "SA", "SU" or an integer or list of integers from 0 (MO) through 6 (SU). Default: any weekday. E.g., "@r m @w (MO(1), FR(-1))" would repeat on the first Monday and the last Friday of each month.|
|@W||WEEKNUM||an integer week number or a list of week numbers from 0 through 53. Default: any week number.|
|@m||MONTHDAY||an integer month day number or a list of month day numbers from 1 through 31. Note that "@r m @m 31" would only repeat on months that have 31 days but "@r m @m -1" would repeat on the last day of every month. Default: any month day.|
|@M||MONTHNUM||an integer month number or a list of month numbers from 1 through 12. Default: any month number.|
|@+||INCLUDEDATES||a date or a list of dates to add to the dates that would otherwise be generated by the recurrence rule. E.g., "@r m @m 1 @+ (Feb 5, Feb 7)" would repeat on the 1st of each month and, additionally, on Feb 5 and Feb 7. Note that it is possible with this field to specify specific dates for an item. E.g., "@r l @+ (Feb 28, Jul 3, Aug 27)" would repeat only on the three specified dates. When '@r l' (list) is used an entry for '@+ INCLUDEDATES' is required and an entry for '@d DATE' is optional. Otherwise, an entry for '@d DATE' is required and an entry for '@+ INCLUDEDATES' is optional. Default: none.|
|@-||EXCLUDEDATES||a date or a list of dates to remove from the dates that would otherwise be generated by the recurrence rule. E.g., "@r m @m 1 @- (Mar 1, Jun 1)" would repeat on the 1st of each month except for Mar 1 and Jun 1. Default: none.|
|@S||SETPOSITION||a integer specifying the date from the list of dates that would otherwise satisfy the recurrence rule. E.g., "@r m @w (MO, TU, WE, TH, FR) @m (23, 24, 25)" would repeat on every weekday that is a 23rd, 24th or 25th of the month. For June 2011, for example, this would include Thursday, June 23 and Friday, June 24. By adding "@S -1", only the last of these, Friday, June 24, would be included. Thus "@r m @w (MO, TU, WE, TH, FR) @m (23, 24, 25) @S -1" would repeat on the last weekday in each month that falls on or before the 25th. Default: none.|
|@o||OVERDUE||either 'k' (keep), 's' (skip) or 'r' (restart). The specification of how to handle due dates for repeating tasks. This is explained below. Default: k.|
A repeating task that is finished on its due date presents no difficulty. But what if it's finished early or becomes overdue? There are three options with etm:
@o k: Keep the current due date if it becomes overdue and use the next due date from the recurrence rule if it is finished early. This would be appropriate, for example, for the task 'file tax return'. The return due April 15, 2009 must still be filed even if it is overdue and the 2010 return won't be due until April 15, 2010 even if the 2009 return is finished early.
@o s: Skip overdue due dates and set the due date for the next repetition to the first due date from the recurrence rule on or after the current date. This would be appropriate, for example, for the task 'put out the trash' since there is no point in putting it out on Tuesday if it's picked up on Mondays. You might just as well wait until the next Monday to put it out. There's also no point in being reminded until the next Monday.
@o r: Restart the repetitions based on the last completion date. Suppose you want to mow the grass once every ten days and that when you mowed yesterday, you were already nine days past due. Then you want the next due date to be ten days from yesterday and not today. Similarly, if you were one day early when you mowed yesterday, then you would want the next due date to be ten days from yesterday and not ten days from today.
In the GUI, press 'o' to set options for outline view or 'b' to set options for busy view. Allowed options are indicated below by 'O'.
|-b||BEGIN||O||O||Date. Display items on or after this (fuzzy parsed) date. A relative date can be entered, e.g., '-b -14' would set BEGIN to 14 days before the current date. Relative month expressions can also be used so that, for example, '-b -1/1' would set BEGIN to the first day of the previous month.|
|-e||END||O||O||Date or a plus sign followed by an integer. Display items before (but not on) this (fuzzy parsed) date or for this integer number of days starting with BEGIN. E.g., both '-b 7/1 -e 7/8' and '-b 7/1 -e +7' would include items for the seven days from July 1 through July 7. As with BEGIN, relative month expressions can be used, e.g., '-b -1/1 -e 1' would include all items from last month and '-b -2/1 -e -1/1' from the month before last.|
|-g||GROUPBY||O||Available group/sort keys include y (year), m (month), d (day), e (extent), w (week number in year), q (quarter number), c (context), l (location), u (user), s (item type), k1, k2 and k3, (first, second and all remaining keywords). A final groupby option is to use '-g F' to group and sort by project F)ile. When this option is used other groupby and begin and end date options are ignored to show all items outlined by project file. See the discussion under Grouping and Sorting in Overview for further details.|
|-o||OMIT||O||O||String with characters from a (actions), b (task begin dates), d (all day events), e (scheduled events), n (notes), r (reminders), f (finished tasks), u (undated tasks), w (waiting tasks), p (past due tasks) and t (active tasks), If OMIT begins with '!', then only show items with types belonging to OMIT. Otherwise only show items with types not belonging to OMIT. Only items with extents (actions and events) are relevant to busy view.|
|-d||DETAILS||O||0, 1 or a string composed of item field keys or *. Display only group headings if 0. If 1 show items (leaves) as well. If a string of field keys, then open a print preview showing details corresponding to the keys as well as the items. E.g., '-d ln' would open a print preview showing items, their l)ocations and their n)otes. If '*' then show details corresponding to all field keys. Default: 1.|
|-T||TOTALSFIRST||O||0 or 1. Display time totals before the group titles if 1. Otherwise after the group titles. Default: 0.|
|-s||SEARCH||O||O||Regular expression. include items, regardless of date, in which any field value matches SEARCH (ignoring case). Prepend an exclamation mark to include items which do not have any field values matching SEARCH.|
|-c||CONTEXT||O||O||Regular expression. include items with contexts matching CONTEXT (ignoring case). Prepend an exclamation mark to include items which do not have contexts matching CONTEXT.|
|-k||KEYWORD||O||O||Regular expression. include items with keywords matching KEYWORD (ignoring case). Prepend an exclamation mark to include items which do not have keywords matching KEYWORD.|
|-p||PRIORITY||O||O||Regular expression. Include items with priorities matching PRIORITY. For example, '-p ' would select items with the top three priorities and '-p !' would select items with priorities lower than 3 or no priority.|
|-t||TAG||O||O||Regular expression. include items with tags matching TAG (ignoring case). Prepend an exclamation mark to include items which do not have tags matching TAG. Multiple uses of this option are possible. E.g., use '-t tag 1 -t tag 2' to show items with both 'tag 1' and 'tag 2'.|
|-l||LOCATION||O||O||Regular expression. include items with locations matching LOCATION (ignoring case). Prepend an exclamation mark to include items which do not have locations matching LOCATION.|
|-u||USER||O||O||Regular expression. include items with users matching USER (ignoring case). Prepend an exclamation mark to include items which do not have users matching USER.|
|-P||PROJECT||O||O||Regular expression. include items with projects matching PROJECT (ignoring case). Prepend an exclamation mark to include items which do not have projects matching PROJECT.|
|-f||FILE||O||O||Regular expression. include items with files matching FILE (ignoring case). Prepend an exclamation mark to include items which do not have projects matching FILE.|
|-i||INCLUDE||O||String. One or more characters from B (busy time bars), b (busy times), F (free time bars), f (free times), and c (conflict times). Default: Bfc|
|-O||OPENING||O||Time. The opening or earliest time (fuzzy parsed) to be considered when displaying free periods. Default: 8:00a.|
|-C||CLOSING||O||Time. The closing or latest time (fuzzy parsed) to be considered when displaying free periods. Default: 10:00p.|
|-m||MINIMUM||O||Positive integer. The minimum length in minutes for a free period to be displayed. Default: 60.|
|-w||WRAP||O||Positive integer. Provide a buffer of WRAP minutes before and after busy periods when computing free periods. Default: 15.|
|-v||VCAL||O||Export displayed items in vCal format to export.ics in the 'export' directory specified in the etm rc file.|
|-x||VALUES||O||Comma separated list of field keys. Export displayed items in CSV (comma separted values) format to export.csv in the 'export' directory specified in the etm rc file. Values exported for each item include 1) item id, 2) item type number, 3) item description (title) and, in order, values corresponding to the keys in VALUES. Possible keys include y (year), m (month), d (day), e (extent minutes), p (priority), w (week number), q (quarter number), c (context), k1, k2, k3, (keywords 1, 2 and beyond), l (location), u (user), P (project name), t (tags) and n (note).|
for complete usage information:
documented etm commands Enter '? X' (or 'help X') for details about command X ============================================================================= b c colors d e f help j m n numbers o q r u v w
or, for example,
e.py ? o
to get outline usage information:
Display outline report using provided options. Options: -h, --help show this help message and exit -b BEGIN_DATE Date. Display items beginning with this date (fuzzy parsed) and continuing until END_DATE. Default: today. -e END_DATE Date. Display items beginning with BEGIN and ending with this date (fuzzy parsed). Default: BEGIN plus 6 days. -f FILE Regular expression. Include items with project file names matching FILE (ignoring case) within the BEGIN ~ END interval. Prepend an exclamation mark, i.e., use !FILE rather than FILE, to include items which do NOT have file names matching FILE. -P PROJECT Regular expression. Include items with project titles matching PROJECT (ignoring case) within the BEGIN ~ END interval. Prepend an exclamation mark, i.e., use !PROJECT rather than PROJECT, to include items which do NOT have project titles matching PROJECT. -c CONTEXT Regular expression. Include items with contexts matching CONTEXT (ignoring case) within the BEGIN ~ END interval. Prepend an exclamation mark, i.e., use !CONTEXT rather than CONTEXT, to include items which do NOT have contexts matching CONTEXT. -k KEYWORD Regular expression. Include items with contexts matching KEYWORD (ignoring case) within the BEGIN ~ END interval. Prepend an exclamation mark, i.e., use !KEYWORD rather than KEYWORD, to include items which do NOT have keywords matching KEYWORD. -t TAG Regular expression. Include items with tags matching TAG (ignoring case) within the BEGIN ~ END interval. Prepend an exclamation mark, i.e., use !TAG rather than TAG, to include items which do NOT have tags matching TAG. This switch can be used more than once, e.g., use '-t tag 1 -t tag 2' to match items with tags that match 'tag 1' and 'tag 2'. -u USER Regular expression. Include items with user matching USER (ignoring case) within the BEGIN ~ END interval. Prepend an exclamation mark, i.e., use !USER rather than USER, to include items which do NOT match USER. -l LOCATION Regular expression. Include items with location matching LOCATION (ignoring case) within the BEGIN ~ END interval. Prepend an exclamation mark, i.e., use !LOCATION rather than LOCATION, to include items which do NOT match LOCATION. -p PRIORITY Regular expression. Include items with project titles matching PRIORITY within the BEGIN ~ END interval. Prepend an exclamation mark, i.e., use !PRIORITY rather than PRIORITY, to include items which do NOT have priorities matching PRIORITY. -s SEARCH Regular expression. Include items containing SEARCH (ignoring case) in the task title or note within the BEGIN ~ END interval. Prepend an exclamation mark, i.e., use !SEARCH rather than SEARCH, to include items which do NOT have titles or notes matching SEARCH. -o OMIT string. show/hide a)ctions, task b)egin dates, all d)ay events, scheduled e)vents, f)inished tasks, n)otes, r)eminders, u)ndated tasks, w)aiting tasks and/or active t)asks depending upon whether omit contains 'a', 'b', 'e', 'f', 'n', `'r', 'u', 'w' and/or 't' and begins with '!' (show) or does not begin with '!' (hide). default: none. -g COLS A tuple of elements from y (year), m (month), d (day), s (sort or type number), e (extent minutes), w (yearly week number), q (quarter number), c (context), k1 (keyword 1), k2 (keyword 2), k3 (keyword 3), l (location), n (item name), f (file name and line numbers), u (user), p (project name) and i (id). For example, the default, -g ((y, m, d),), sorts by year, month and day together to give output such as Fri Apr 1 2011 items for April 1 Sat Apr 2 2011 items for April 2 ... As another example, -g ((y, q), m, d), would sort by year and quarter, then month and finally day to give output such as 2011 2nd quarter Apr Fri 1 items for April 1 Sat 2 items for April 2 ... A final option is to group by file path using '-g F'. Note that if 'F' should not be combined with any other groupby options. -d DETAILS String. Controls the display of item details. With '-d 0', item details would not be displayed. With '-d 1' (the default), the prefix and title (description) would be displayed. With '-d len', for example, a second details line would be appended displaying the item l)ocation, e)xtent and n)ote entries. -T Boolian. Display minute totals at the beginning rather than the end of the line. -x VALUES Comma separated list of field keys. Export displayed items in CSV (comma separted values) format to export.csv in the 'export' directory specified in the etm rc file. Values exported for each item include 1) item id, 2) item type number, 3) item description (title) and, in order, values corresponding to the keys in VALUES. Possible keys include y (year), m (month), d (day), e (extent minutes), p (priority), w (week number), q (quarter number), c (context), k1, k2, k3, (keywords 1, 2 and beyond), l (location), u (user), P (project name), t (tags) and n (note). -v Export items in vCal/iCal format to export.ics in the directory specified by 'export' in the etm rc file.
You can run:
without any options to open an interactive version of the CLI:
$ e.py enter 'q' to quit or 'help' for usage information etm:
Entering 'o' at the prompt produces output such as:
etm: o Wed Aug 24 2011 (20) 4:00 10:00a meet with Client 1  1:00p meet with Client 2  5:00p Monday, Wednesday, Friday late afternoon event  5:00p workout  back exercises  Alert test  phone conference with Client 1  +1 make eye appointment  +7 set up luncheon meeting with Client 2  +14 Promote etm  monthly report preparation  Client 2 research  work on E draft  X E draft  X call Client 2  X Water house plants  etm examples  Thu Aug 25 2011 (12) 6:45 10:05a Tuesday/Thursday morning and afternoon events  12:00p staff lunch  2:50p Tuesday/Thursday morning and afternoon events  3:00p Meet with Client 3 re A  back exercises  Take out trash  make eye appointment  revisions for A  work on E revisions 
The numbers in square brackets that follow items can be used interactively to modify items. E.g.
etm: d 9
would prompt for confirmation and then delete item number 9 (set up luncheon). Similarly
etm: e 11
would open item number 11 (monthly report) using the editor specified by 'term_editor' in your etmrc file. Other interactive options include c (display 3 month calendar), f (finish item), m (move item to a different file), n (create new item), r (force data reload), u (unfinish item) and v (check for newer version).
Item numbers are only displayed in the interactve version and can be toggled on and off with:
The default value is given by 'show_nums' in your etmrc. Similarly, the use of colors in the display can be toggled on and off with:
The default value is given by 'use_colors' in your etmrc.
It is also possible to provide options on the command line to get a non-interactive version. E.g.,
e.py o -g(k1, (y,m), k2) > report.txt
would write an output report directly to the specified file.
Finally, you can run
to open the wx(python) GUI interface and press F1 to see a list of available commands.
Alternatively, a shell script such as:
#!/bin/bash e.pyw &
could be created and automatically invoked by your startup process. Under OS X, naming this file using the suffix 'command', e.g., 'etm.command', would allow you to add the file to your login items and/or add the command to your dock.
You will need to have python >= 2.5.2 (but < 3.0), wxPython >= 2.8.7 and the non-standard but easily-installed python module dateutil >= 1.4.1. Exporting a list view to iCal requires the python module vobject .
wxPython is being very actively developed and it is both easy and well worth the effort to update to the latest version. There are self-installing binaries for all common platforms. Just be sure to get one that matches your python version. (To check your python version run 'python -V' in a terminal.) I recommend getting the unicode version rather than the ansi version.
If you use either setup.py or easy_install to install etm, dateutil and vobject will automatically be installed along with etm. Otherwise, you can install them in the normal python way. Download, unpack, cd to the resulting directory and run 'sudo python setup.py install'.
etm can be installed in the normal python way: download, unpack the etm source in a temporary directory, open a terminal ('Command Prompt' in Windows), cd to that directory and then run:
sudo python setup.py install
Windows users can omit the 'sudo'. The temporary directory can then be removed. This will download and install any necessary supporting modules (dateutil, vobject), install the etm package in the 'site-packages' subdirectory of your python distribution and install the executable e.py in the 'bin' subdirectory of your python distribution.
If you have setuptools installed, you can skip downloading and use:
sudo easy_install -U etm
either to install etm or to update to the latest version.
Easy_install is part of the python package setuptools. To install it, download the appropriate egg file for your platform, e.g.,
Then cd to the directory containing the egg file and, if necessary, rename it to remove the '.sh' extension:
mv setuptools-0.6c11-py2.6.egg.sh setuptools-0.6c11-py2.6.egg
The last step is to run the (renamed) egg file as if it were a shell script:
sudo sh setuptools-0.6c11-py2.6.egg
Setuptools will install itself using the matching version of python (e.g. 'python2.6'), and will place the 'easy_install' executable in the default location for python scripts.
A standalone version, etm.app, is provided for Mac OS X users as a standard dmg file. Download this file, click on it and then drag etm.app to your Applications folder. Note that this application provides the gui version of etm but not the command line version.
If you would like to try etm out without installing the system files or if you don't have root privileges but would like to install etm for your own use, the process is simple. Unpack the etm source in a convenient directory, cd to that directory and then run
This does not require root privileges and will not install any system files but will create the user specific configuration, data and alert files mentioned below in your home directory. You could, of course, use aliases or symbolic links to these files and avoid even having to change to this directory, e.g., if these files are located in ETMDIR, then you could add these lines to your ~/.bash_profile:
replacing ETMDIR, of course, with the actual path. These aliases would then function in the way described under Command line usage below.
Users of etm versions prior to 800 can preview the new version by downloading the new version of etm, upacking it into a temporary directory, opening a terminal window, changing to the temporary directory and then running either './e.py' for the CLI version or './e.pyw' for the GUI version. This will display your data using the new version without affecting your existing installation in any way.
The directory '~/.etm' and the following files are created the first time you run e.py.
|~/.etm/etmrc:||All configuration settings are kept in this file. It will automatically be created if it doesn't already exist and populated with default values. This configuration file is self-documented and can be freely edited. If you make changes you don't like you can simply erase the offending part, or even the entire file, and it will be recreated with defaults the next time you run e.py.|
|Project files are, by default, kept in this directory and its subdirectories though the setting for etmdata can be changed in '~/.etm/rc'. It is automatically created and populated with the rotating project files for events and tasks for the previous and current months discussed in Monthly data files below.|
|~/.etm/export/:||Views exported in iCal or CSV format are, by default, kept in this directory.|
When entering options for items in the GUI details panel, completion is available for contexts, keywords and locations by pressing Ctrl-Space. E.g., if you are creating or modifying the event
* my event @c e| @d tue
and press Ctrl-Space with the cursor at the position indicated by '|', then you will be able to select a context from a list of those beginning with 'e'. Which contexts belong to this list depends upon the contents of 'context.txt' and whether 'addFileContexts' is true or false.
Contexts added to this file, one per line, will be available for Ctrl-Space completion. If 'addFileContexts = True', contexts used in your data files will also be available for Ctrl-Space completion.
Keywords added to this file, one per line, will be available for Ctrl-Space completion. If 'addFileKeywords = True', keywords used in your data files will also be available for Ctrl-Space completion.
Locations added to this file, one per line, will be available for Ctrl-Space completion. If 'addFileLocations = True', locations used in your data files will also be available for Ctrl-Space completion.
The file specified by 'abbreviationsFile' in etmrc is a plain text file with one abbreviation per line in the format "X|Y" where X is an alpha-numeric string without spaces (the abbreviation) and Y is the replacement string. Occurances of ":X:" in an etm action, event, note or task will then be replaced by "Y", e.g., if abbreviations.txt contains the line "chtc|Chapel Hill Tennis Club" then ":chtc:" in an event would become "Chapel Hill Tennis Club".
Many times it will be convenient to create a project file to hold a collection of related items as in the illustrative case of the report. Often, however, items will be created that are independent of one another. There is no need to create separate project files in such circumstances. etm, in fact, will automatically create files that can you can use for such independent items.
Suppose that it is currently July 2011. Then etm will automatically create '07_actns.text' in the '2011' subdirectory of the path for 'etmActions' the first time it is run. By default, actions created during July will be written to this file. Similar files will be automatically be created and become the defaults as subsequent months and years arrive. A similar thing happens for events, notes and tasks.
If you want to remove obsolete data entries, you could, of course, delete the file or directory or you could simply change the name of a file or directory to begin with a '.' (period) and, as a hidden file, etm would ignore it. On the other hand, you can use the values of 'year_beg' and 'year_end' in your etmrc file to control which items etm displays. Etm always processes all, non-hidden '*.text' files in its data directories. But it only loads (stores in memory) (1) undated items, (2) dated items with occurances (dates) between January 1 of the year that is 'year_beg' (default 1) years before the current year and December 31 of the year that is 'year_end' (default 5) years after the current year and, for dated items without occurances within this period, (3) the first occurance after and the last occurance before this period. Thus at least once occurance of everything is available, but repetitions are limited to the given period.
A backup is made of any file before any action by etm would change it. E.g., before a task in '02_tasks.text' would be marked finished, the file would first be copied to '.02_tasks.bk1'. If '.02_tasks.bk1' already exists, it would first be moved to '.02_tasks.bk2'. Similarly, if '.02_tasks.bk2' already exists, then it would be first be moved to '.02_tasks.bk3' and so forth. In this way, up to 'numbaks' (3 by default) rotating backups of are kept with '.bk1' the most recent.
Any etm action which changes a data file is logged. E.g. adding a new event to '07_evnts.text' would append a time stamped entry to '07_evnts.log':
### 2011-07-21 10:37:38 ### [+] * Book club pot luck dinner @d 2011-08-14 @s (6:30p) @e +3:00
Copyright (c) 2009-2012 Daniel Graham <firstname.lastname@example.org>. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.