yeaGTD

yeaGTD

yeaGTD is an acronym for "yaml encoded approach to getting things done". Either a command line or a wxPython-based graphical interface can be used to create both simple and repeating projects, to add tasks, to mark tasks complete, to modify project files and to perform other convenient actions.

Data is stored in a collection of simple text files, one for each project, using 'yaml' (yet another markup language) - a simple, human-readable and writable data-serialization format. Flexible recurrence rules can be used to specify repeated projects.

Date, project, agenda and log views are supported. Output can optionally be printed.

Complete redesign! For versions 100 and beyond, the data file structure has been simplified and the focus has been changed from displaying tasks for the current date to displaying active tasks for any selected date. Current users of yeagtd will need to use yeaconvert (included in the distribution) to update the format of your existing gtd files to the new format. See Installation below for details.

Emphasis has shifted for interactive use from the command line tool, yeagtddata, to the GUI tool, yeagtd which now provides complete project support internally and makes the use of an external editor unnecessary. The number of active tasks on a given date determines the color of the date in the new calendar display and the status of the task determines the color of the task for the day in the new Gantt chart display. The new note display shows project and task notes for the selected task. Log and time entries in notes are now supported and reports can be generated which show times aggregated in user specified ways for, say, monthly billing.

[ICO]NameLast modifiedSizeDescription

[DIR]Parent Directory  -  
[TXT]CHANGES27-Feb-2009 13:29 16K 
[   ]etm-647.tar.gz07-Aug-2010 12:04 157K 
[DIR]examples/19-Jan-2013 10:47 -  
[DIR]images/19-Aug-2008 15:17 -  
[   ]yeagtd-110.tgz27-Feb-2009 13:29 59K 
[   ]yeagtd-src-110.tgz27-Feb-2009 13:29 39K 

Contents

Overview

YAML, a recursive acronym for "YAML Ain't Markup Language", is a human readable and writable data serialization format. YAML's contribution to yeaGTD is to make the format of the project files extremely simple both to create and to read.

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.

Suppose, for example, that the halogen bulb in the study lamp needs to be replaced. Getting this done requires first removing the old bulb, taking it with you to the hardware store to buy a similar replacement bulb and finally installing the new bulb. Though simple, this example illustrates several aspects of GTD.

1. Projects usually involve a series of steps, some of which must be carried out consecutively, e.g., the old bulb must be removed before it can be taken to the hardware store and the replacement must be purchased before it can be installed.

2. The steps of a project are carried out in a context which may vary from step to step, e.g., removing the old bulb and installing the new one both take place in the context "Home" but buying the required bulb takes place in the context "Errands".

3. While focusing on projects is great for planning, for actually doing things it would be more convenient to focus on context so that, for example, you could see all actions from all projects with context "Errands" before you drive away to run errands. To focus on what needs to be done, it would also be useful to be able to hide actions that are not yet available so that, for example, "Install new bulb" would not be displayed until "Buy required bulb" had been completed.

GTD thus requires:

planning:a method for storing and organizing all the bits.
acting:a method for displaying just the information you need, when you need it.

The Project File

Here are yeaGTD project files for the "Fix light" project and a simple repeating project:

   A non-repeating project                A repeating project
-----------------------------         ----------------------------

  agenda: Fix light                   agenda: Get a haircut

  tasks:                              date: 2007-05-18
  - a: Remove old halogen bulb
    c: Home                           frequency: WEEKLY
                                      interval: 2
  - a: Buy similar bulb               weekday: FR
    c: Errands                        next: RESTART

  - a: Install new bulb               tasks:
    c: Home                           - a: Get a haircut
                                        c: Errands

Simple, aren't they?

A slightly more complicated project is illustrated below as it appears in my editor (textmate) and in the internal yeaGTD project window.

         

Project files are text files with the extension .yaml that belong to your projects directory and its sub-directories. Each project file can include the following specifications though only agenda, tasks and, for each task, a and c, are required.

Fields

agenda:

The title for the project. Required.

date:

The target date for the project in YYYY-MM-DD format. Defaults to the current date if omitted. Fuzzy parsing of dates is supported in the internal yeaGTD project editor and activated by entering a period. E.g. if it is currently Friday August 15 2008, then entering:

  • thu. would give 2008-08-21
  • 25. would give 2008-08-25
  • 9/17. would give 2008-09-17
  • 9/1/17. would give 2009-01-17
early:

The number of days in advance of date at which project tasks, by default, should become available.

When early is omitted, date could be interpreted as the starting date for the project. Alternatively, when early is set, date could be interpreted as the ending date for the project which begins early days before date. In either case, project tasks become available early days before date by default.

finished:

The date on which the last of the project tasks was completed in YYYY-MM-DD format. Normally this date is entered automatically when the last task is completed and should not need to be edited. Fuzzy parsing of dates is supported in the internal yeaGTD project editor - see the discussion under date.

frequency:

The base period for repetitions. Must be one of the following: ONCE, DAILY, WEEKLY, MONTHLY or YEARLY. Use frequency: ONCE to disable repetition. Defaults to ONCE if omitted.

interval:

The number of frequency periods between repetitions. E.g. frequency: WEEKLY and interval: 2 would call for repetitions every two weeks. Defaults to 1 if omitted. Ignored with frequency: ONCE.

extent:

Enter either an integer number of repetitions or a repeat until date in YYYY-MM-DD format to specify when the repetitions will end. Omit to repeat forever. Ignored with frequency: ONCE. Fuzzy parsing of dates is supported in the internal yeaGTD project editor - see the discussion under date.

notes:

Notes for the overall project. These are free-form notes save for the fact that notes that begin with a date in YYYY-MM-DD format are treated as log entries. Notes for specific tasks can be entered under Show tasks.

Lines in project notes and task n that begin with a date in YYYY-MM-DD format followed by a semicolon are are regarded as log entries. For those who need to keep track of time spent, log entries that follow the date with a time duration in H:MM format followed, optionally, by a key phrase and then by a semicolon and, optionally, other text are treated as time entries. Such entries are not only included in log reports but also in time reports where time aggregates for the chosen outline structure are provided.

When creating notes (or task n's) with a text editor, begin each note on a new line preceded by a minus sign:

notes:
- This is a note.
- 2008-05-01; This is a log entry.
- 2008-05-01 1:15 Smith Account; This is a time entry.

When using the internal yeaGTD project editor, omit the leading minus sign and simply begin each note on a new line.

mode:

Treat project tasks as consecutive or concurrent.

CONSECUTIVE: This is the default mode. For projects where tasks should be completed consecutively by default. A task must be completed before the next task becomes available. Consecutive tasks with the same p value, however, are treated as CONCURRENT and become available simultaneously but only after earlier tasks with different p values have been completed.

CONCURRENT: This is a convenience setting for todo lists and similar projects where tasks are independent and the order in which they are completed does not matter. All tasks are treated as concurrent.

next:

Ignored with frequency: ONCE. This setting has no effect for the next repetition if the project was completed on or before the target date. Otherwise, the effect is as follows:

KEEP: The next target date occurs at the next date satisfying the recurrence rule that falls after the previous target date. This is for projects that can be completed late but cannot be skipped.

E.g., You have to file quarterly reports and, while they can be filed late, none can be skipped. The report for the last quarter of 2007 was due on January 1, 2008 but you didn't get around to filing it until April 21:

frequency:  MONTHLY
interval:   3
monthday:   1
next:       KEEP

The target date for the next quarterly report is still April 1, 2008, so the report for the first quarter is already past due.

SKIP: Regard a target date prior to current date as having been automatically completed. The next target date is the first date satisfying the recurrence rule which falls on or after the current date. This is for projects for which late completion is not an option.

E.g., The trash gets picked up every Tuesday and you forgot to put out the trash yesterday, Tuesday, April 22, 2008:

frequency:  WEEKLY
interval:   1
weekday:    TU
next:       SKIP

The next target date is Tuesday, April 29, 2008.

RESTART: Create a new recurrence rule which preserves everything from the original other than the starting date (date), then choose as the new starting date the first date which is consistent with the new rule and which falls on or after finished. Finally set the next target date equal to the second date from the new recurrence rule, i.e., the first date from the rule after the starting date. Note that the next target date will thus be at least frequency times interval later than finished.

E.g., You want to get a haircut every two weeks and Friday is the most convenient day. The target date for your last haircut was Friday, April 4, 2008 but you didn't get it until the following Thursday:

frequency:  WEEKLY
interval:   2
weekday:    FR
next:       RESTART

The next target date will be Friday, April 25.

weekday:

Repetitions occur only on these week days. Defaults to (MO, ..., SU) or, equivalently (1, ..., 7), if omitted. E.g., MO(-1) with frequency: MONTH and interval: 1, would repeat on the last Monday in every month or MO(+3) would repeat on the third Monday every month. Ignored with frequency: ONCE.

monthday:

Repetitions occur only on these days of the month. Defaults to (1, ..., 31) if omitted. Ignored with frequency: ONCE.

week:

Repetitions occur only on these week numbers. If left void defaults to (1, ..., 53). Ignored with frequency: ONCE.

month:

Repetitions occur only on these month numbers. If left void defaults to (1, ..., 12). Ignored with frequency: ONCE.

The entries for weekday, monthday, week and month can either be a single choice, e.g., MO, or a comma separated list enclosed in parentheses, e.g., (TU(+2), TU(+4)).

tasks: The following can be specified for each task.

a:

The action or title of the selected task. Required.

c:

The context for the task. Select from a drop-down list of existing contexts or specify a new context. Required.

d:

The target date for the task either as an absolute date in YYYY-MM-DD format or as an integer number of days in advance of date. For repeating projects, absolute dates are converted to an equivalent number of days before date. The value of d for the next repetition is then set to the that number of days before the next project target date. Tasks for projects in which both date and d are void become available as soon as the project is created and have the current date as the target date. Fuzzy parsing of dates is supported in the internal yeaGTD project editor - see the discussion under date.

The remaining days displayed for a task shows the difference between the current date and the relevant task target date. When the current date is later than the target date, the difference is preceded by a minus sign to indicate that the task is past due. Remaining days is empty for tasks in which the target date is void since they are always due on the current date and thus never past due. An X is displayed for completed tasks.

e:

The number of days in advance of the target date for the task at which the task should become available (provided that all prior non-concurrent tasks have been completed). Defaults to the project setting for early if left void. Ignored if both date and d are void.

p:

The concurrent character. With mode: CONSECUTIVE, consecutive tasks with the same concurrent character are treated as concurrent and become available simultaneously. With mode: CONCURRENT then this field is ignored and all tasks are treated as concurrent.

f:

The date on which the task was finished in YYYY-MM-DD format. A date corresponding to the current date is created when the project is marked completed in yeaGTD but a date could be entered manually. Clearing the value of f changes the status of the task from finished to unfinished. Fuzzy parsing of dates is supported in the internal yeaGTD project editor - see the discussion under date.

n:

Task notes. These are free-form notes save for the fact that lines that begin with a date in YYYY-MM-DD format format are treated as log entries. See the discussion under notes above.

Illustrative Recurrence Rules

Once every other week:              Monthly on the 2nd and 15th:
   frequency:  WEEKLY                  frequency: MONTHLY
   interval: 2                         monthday: (2,15)

The first Monday in every month:    Monthly on the first and last days:
   frequency: MONTHLY                  frequency: MONTHLY
   interval: 1                         monthday: (1,-1)
   weekday: MO
                                    30 days from the last completion:
The third Monday in every month:       frequency: DAILY
   frequency: MONTHLY                  interval: 30
   interval: 1                         next: RESTART
   weekday: MO(+3)
                                    Every August 13th which is a Friday:
The last Monday in every month:        frequency: YEARLY
   frequency: MONTHLY                  month: 8
   interval: 1                         monthday: 13
   weekday: MO(-1)                     weekday: FR

Weekly on Tu and Th for 5 weeks:    The first Tuesday after a Monday in
   frequency: WEEKLY                November every 4 years
   interval: 1                      (Presidential election day):
   weekday: (TU,TH)                    frequency: YEARLY
   extent: 10                          interval: 4
                                       month: 11
                                       weekday: TU
                                       monthday: (2,3,4,5,6,7,8)

How Repetition Works

When processing an unfinished repetition of a project, finished is void and the target date for the repetition is date. You choose the value of date for the first repetition and, to avoid unpredictable results, the date you choose should satisfy the recurrence rule, e.g., if repetitions are to occur monthly on the first Saturday, then the date you choose for the first repetition should be the first Saturday in some month. After the first repetition, date will be automatically set.

Projects for which next is SKIP are automatically "completed" when late, i.e., if the current date is later than date then finished is automatically set equal to the current date-time. Otherwise, a project is completed when the last action of the project is completed and finished is automatically set to the completion date-time of the last task. A number of automatic actions follow when a project is completed in either way:

Save for some automatic resetting and clearing, repeating projects are exactly like non-repeating ones. The target date for the current repetition is given by date; target dates for tasks are determined by date and the value of d for the task; tasks become available on a date determined by the target date and the values of early and e; and the value of f for a task is either empty for tasks that have not been finished or it contains the datetime that the task was finished for the current repetition.

Log and Project Reports

On the left below is a log report for the project Economics 370 grouped first by month and then by key phrase. On the right is the project report for the same project.

         

Task Reports

A report on the tasks for the next numdays (set in ~/.yeagtdrc) can be generated either from the console or gui version as illustrated below.

           

Tips

Installation

The first time you run either yeagtd, yeagtddata or yeagtdhelp, the following files and directories will be created if they don't already exist:

You can move the project files directory where ever you like provided that you update the path in ~/.yeagtdrc.

Current users. If you are already using yeagtd, you will need to use yeaconvert which is included in the distribution to update the format of your existing gtd files to the new format. Running:

yeaconvert

at the command line will process all the files in the gtddir folder specified in your ~/.yeagtdrc and send the results to standard output. When you are satisfied with the results, backup your existing gtddir folder and then run:

yeaconvert w

to update your files.

License

Copyright (c) 2007-2008 Daniel A. Graham

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 2 of the License, or (at your option) any later version. This program is provided 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.