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 sequentially, 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. |
|---|
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: end: 2007-05-18
- a: Remove old halogen bulb
c: Home repeat:
byweekday: FR
- a: Buy similar bulb frequency: WEEKLY
c: Errands interval: 2
next: restart
- a: Install new bulb
c: Home tasks:
- a: Get a haircut
c: Errands
Simple, aren't they?
Project files are text files with the extension .yaml that belong to
your projects directory and its sub-directories. Each project file
should have the following format:
agenda: agenda or project title. Required.
begin: beginning date at which tasks are listed as available in date-time
format, i.e., either YYYY-MM-DD or YYYY-MM-DD HH:MM:SS.
days: non-negative number of days in advance of end at which the
project's tasks become available.
end: ending date for completing all tasks in date-time format. For
repeating projects, the ending date for the first repetition -
details below.
At most two of {begin, days, end} should be provided. When two are
provided then the third is deduced, i.e., begin = end - days; end
= begin + days; days = end - begin. If only begin is given then
end = begin and days = 0. If only end is given then begin = end
and days = 0. If only days is given then begin = today and end =
today + days. Otherwise begin = today, end = today and days = 0.
notes: project notes. Default = None.
series: True/False. Default = True.
If true, treat project tasks as series by default. If
false, treat project tasks as parallel by default.
numbered: True/False. Default = True
If true, show task number / total number of tasks in project
in output.
tasks: A list of the tasks required to complete the project. Each
action has the following possible fields.
a: action title. Required.
n: notes. Default = None.
c: user specified context. Default = '???'. Other possibilities
include 'Office', 'Home', 'Errands', et cetera. Tasks with the
default category, "???", are combined with tasks belonging to the
Inbox project and listed first in all reports as a reminder to set
contexts for all your tasks and to "empty your inbox".
b: date-time action becomes available.
d: non-negative number of days in advance of e at which the action
is listed as available.
e: date-time action should be completed.
At most two of {b, d, e} should be provided. When
two are provided then the third is deduced, i.e., b =
e - d; e = b + d; d = e - b.
If only one of {b, d, e} is specified then
if either begin, end or days is specified:
b given: e = b + days and d = days
e given: b = e - days and d = days
d given: b = end - d and e = end
else if neither begin, end nor days is specified:
b given: e = b and d = 0
e given: b = e and d = 0
d given: b = today and e = today + d
If none of {b, d, e} is specified then
if either begin, end or days is specified then b = begin, e
= end and d = days
else if neither begin, end nor days is specified then b = e =
today and d = 0.
f: date action was (last) finished in date-time format. Default
= None.
p: alphabetic parallel character or None. Default = None.
Only the agenda and action titles are required - there are defaults
for everything else.
Line-breaks and indentations matter and tab characters should not be
used but other white space does not matter. E.g., there could be more
than one blank line between the entries or no blank lines at all.
The order in which actions are listed is significant - see Available
Actions below - but the order in which fields are listed is not. E.g.
begin could be listed above end or c before a.
yeaGTD distinguishes among completed, remaining and available
actions for relevant projects, i.e., all non-repetitive projects and
current copies of repetitive projects.
Unfinished actions are those for which either f is None or
finished is not None and f is no later than finished,
i.e., either the action has never been completed or it was completed
in a previously finished copy of the project.
Available actions at a given time are those actions for which all of
the following are true.
- The action is unfinished.
- Today is as late as b, i.e., the date at which the action should be made available has been reached.
- All prior actions in the same project have been completed.
A prior action is an action from the same project which is listed
ahead of the given action and either has a different p value from
the given action or, if series is true, has the same value of
p and that value is None. Suppose, for example, that series
is true and that there are 5 actions with the 1st, 2nd and 5th having
p's equal to None and the 3rd and 4th both having p's equal to 'z'.
Only the 1st will be available until it is finished, then only the
2nd until it is finished, then the 3rd and 4th until both are
finished and, finally, the 5th when both the 3rd and 4th are finished.
For projects that repeat, the project file can also include:
repeat: Optional. When included the following parameters can be
specified.
frequency: DAILY, WEEKLY, MONTHLY OR YEARLY. Required.
interval: the number of periods between repetitions, e.g., a project
with frequency = 'WEEKLY' and interval = 2 would repeat every other
week. Default = 1.
byweekday: the weekday or sequence of weekdays on which the project
should repeat. Default = (MO, TU, WE, TH, FR, SA, SU), i.e., any day
of the week. Alternatively, weekdays can be specified using integers
with MO = 1.
bymonthday: an integer or sequence of integer month days on which the
project should repeat. Default = (1, ..., 31), i.e., any day of the
month.
byweek: an integer, or a sequence of integer weeks on which the
project should repeat where the first week of the year is that
containing at least four days of the new year. Default = (1,...,53),
i.e., any week of the year.
bymonth: an integer or sequence of integer months on which the
project should repeat. Default = (1, ..., 12), i.e., any month of the
year.
count: the number of repetitions. The default is to repeat
indefinitely.
until: repetitions end after this date in date-time format. The
default is to repeat indefinitely.
next: 'keep', 'skip' or 'restart'. Default = 'keep'. When recurrent
projects are finished on time, the value of next has no effect. When
the project is finished after the end date, the value of next has the
following consequences.
next = 'keep'. The next date from the recurrence rule becomes the
end date for the next copy just as if the current copy had been
completed on time.
next = 'skip'. The next date from the recurrence rule that falls
after the actual completion date becomes the next end date.
next = 'restart'. The starting date for the recurrence rule is
reset to the actual completion date and the next date from the
recurrence rule becomes the next end date.
For repeating projects, 'end' must be specified. Additionally, 'days' can
be specified for the project and/or 'd' for individual tasks to have
them listed as available 'days' or 'd' days before the relevant end date.
For repeating events 'begin', 'b' and 'e' should NOT be specified.
Repetition details depends upon two internally set values: lastend
and lastdone. When initially processing a project, both
lastend and lastdone are set equal to one day before end
and saved to the project file. The effect is to pretend that a
fictitious first repetition was both due and completed one day
before end and thus that the first actual repetition will be due
at the next value of the recurrence rule that falls on or after
end. end should thus be a date that satisfies the recurrence
rule and corresponds to the first date at which the project should
actually be due. E.g., if repetitions are to occur monthly on the
first Saturday and the first repetition should actually be due on
Saturday, June 2, 2007, then end should be 2007-06-02.
When the last action of a project is completed, lastdone is set
to this completion date-time, lastend is set to the date-time that
the repetition was actually due and both lastend and lastdone
are saved to the project file.
The actual end date for the next repetition will then be determined by
the recurrence rule and the values of lastdone, lastend and
next. If the next end date is None either because count has
been exceeded or until has passed, then there are no more
repetitions to process. Otherwise, the value of begin and days are determined relative to end in the same way they would be for a non-repetitive project. The relevant begin for subsequent repetitions then falls days days before the relevant end date. Similarly, for individual actions b, d and e are determined relative to end in the same way they would be for non-repetitive projects. The relevant b for actions from subsequent repetitions then falls d days before the relevant end date.
Here are some illustrative recurrence rules:
Once every other week: Monthly on the 2nd and 15th:
frequency: WEEKLY frequency: MONTHLY
interval: 2 bymonthday: (2,15)
The first Monday in every month: Monthly on the first and last days:
frequency: MONTHLY frequency: MONTHLY
interval: 1 bymonthday: (1,-1)
byweekday: MO
30 days from the last completion:
The third Monday in every month: frequency: DAILY
frequency: MONTHLY interval: 30
interval: 1 next: restart
byweekday: MO(+3)
Every August 13th which is a Friday:
The last Monday in every month: frequency: YEARLY
frequency: MONTHLY bymonth: 8
interval: 1 bymonthday: 13
byweekday: MO(-1) byweekday: FR
Weekly on Tu and Th for 5 weeks: The first Tuesday after a Monday in
frequency: WEEKLY November every 4 years:
interval: 1 frequency: YEARLY
byweekday: (TU,TH) interval: 4
count: 10 bymonth: 11
byweekday: TU
bymonthday: (2,3,4,5,6,7,8)
yeaGTD internally uses the python module dateutils to support
repetition. Excellent documentation and numerous examples are
available from the website.
Create a convenient one-keystroke alias for yeagtddata by adding
the following to your ~./bash_profile (replacing 't' with whatever
you like):
alias t='yeagtddata'
Download examples.tgz and unpack it in your GTD directory. These files
will show you what's possible and you can copy and/or modify them for
your own uses.
Need to delegate an action to someone else? Use two actions, one for
delegating the task and another for following up and assign the
latter the b date at which you want to be reminded.
Are separate projects really necessary for simple, one-step tasks?
No. Create a single "Tasks" project, omitting end, begin
and days but setting series = False and then include your
one-step tasks as actions with their own b values.
Create a "Someday" project for ideas you would like to think about
later omitting end, begin and days but setting
series = False and then enter each idea as an action with an
appropriate review date for the associated b.
Want a recurrent project that repeats on the last day of each month
in which you can begin a subsequent copy before the current copy is
completed? Create two similar project files, one for the odd months
and one for the even months.:
Odd Months Even Months
----------------------- -------------------------
frequency: YEARLY frequency: YEARLY
bymonth: (1,3,5,7,9,11) bymonth: (2,4,6,8,10,12)
bymonthday: (-1) bymonthday: (-1)
Either the command line appliction, yeagtddata, or the gui application,
yeagtd, is all you need to convert the information in your project files into
a variety of useful views. You can, for example, choose to see a report of your
actions sorted by context, or sorted by project or by date. You can also
choose to see all, completed, remaining, next or available actions.
You can also choose whether to see the resulting report in a terminal window,
display it on your desktop (using geektool under OS X, for example), print it or
even save it to a file in a variety of formats.
Here's the usage information:
Usage: yeagtddata.py [options]
Manage projects using simple GTD project files. Any action that modifies the
file <dir>/<project>.yaml will be logged to <dir>/.log/<project>.log.
Options:
--version show program's version number and exit
-h, --help show this help message and exit
-s SORT, --sort=SORT Sort tasks by [c]ontext, [p]roject or [d]ue date.
Defaults to 'd'. Adding a space separated list of
words when sorting by context or project limits
results to those whose title is a close match for one
of the words.
-f FILTER, --filer=FILTER
Show a[l]l tasks or those which are [c]ompleted,
[r]emaining, [n]ext, or [a]vailable. Defaults to
[a]vailable.
-x EXPORT, --export=EXPORT
Export tasks using sort and filter settings to
[p]rinter or to standard output in [c]omma delimited
or [t]ab delimited format. Defaults to [t]ab.
-b, --backup Backup all project files. Existing backups will be
rotated and the file <dir>/<project>.yaml will be
saved as <dir>/.backup/<project>.bk1.
-d, --done Choose task(s) to mark completed. Tasks must listed
under either the 'available' or the 'next' filter.
-e, --edit Choose project(s) to open for editing.
-m, --move Choose tasks to move and a project into which to move
them.
-r REPORT, --report=REPORT
Choose file(s) to include in an [h]tml, [l]atex or
[r]estructured text project report.
-t, --task Ignore other switches and create a task using the
provided argument as the title. One-word arguments
preceded with p:, c:, b:, e: and d:, respectively,
give the project, context, begin date, end date and
days for the task. Project and context are required.
Begin date, end date and days are all optional and no
more than two should be provided. Fuzzy parsing
applies to all such arguments so that, for example,
'-a Get a haircut e:sat p:task c:errand' could be
used to add a task to the 'Tasks' project with context
'Errands' and an an end date corresponding to the
first Saturday on or after today.
-T, --task-noconfirmation
Similar to -t (--task) but avoids requests for
confirmation if both project and context have unique
matches. The new task will be appended to the end of
the existing task list in the specified project.
-p, --project Ignore other switches and create a new project using
the provided arguments as the agenda (project title)
and, optionally, the argument preceded by f: as the
project file name (with '.yaml' automatically
appended). You will be prompted for additional
details. E.g., '-p My new project f:personal/new',
would prompt for details and then create the project
file 'personal/new.yaml' (relative to the GTD
directory) with the project title 'My new project' and
the other details provided in response to the prompts.
-H, --Help Ignore other switches and show a yeaGTD 'CheatSheet'.
The default context for actions which have not been categorized is "???". These
are combined with actions belonging to the Inbox project and listed first in
all reports as a reminder to set contexts for all your actions and to "empty
your inbox".
Here's a sample of the default output:
================== available actions by context ==================
Voting Mac Jun 12 1/2 Check shareholder voting rules
yeaGTD Mac Jul 01 18 4/10 Finish rst documentation
ECO105 Office Jun 30 17 1/5 Get Tom's selections
where the columns are as follows.
- Agenda title
- Action Context
- Action due date (or completion date if already completed)
- Number of days remaining until due date (negative when past due or 'X' if already completed)
- Action number / total number of actions in project
- Action title
Put yeagtd and yeagtddata somewhere in your path, say ~/bin, and make them executable.
Create a directory in a convenient location to hold your project
files.
Create a configuration file, ~/.yeagtdrc, based on the included file 'yeagtdrc'.
Make sure that you have installed the python modules (py)yaml, dateutil, docutils (for html and latex project reports) and wxPython (for the graphical interface). They are not included in the standard python installation but are easily added.
Command line usage
- Run "yeagtddata -t foo" to create a file for project foo and open it for editing.
- Add project information using the files in "examples.tgz" and as examples.
- Run "yeagtddata -d" to mark tasks completed.
- Run "yeagtddata -h" for complete usage information.
- Run "yeagtddata -H | less" for project file details.
- Run "yeagtddata -a Get haircut p:Tasks c:Errands e:sat" to create a task in the project "Tasks" with context "Errands" and the first Saturday on or after today as end (due) date.
GUI usage
- Run yeagtd to open the gui interface and press '?' to see a list of available commands.
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.
Name Last modified Size Description![[DIR]](/icons/back.gif){kind=icon}
Parent Directory -
![[TXT]](/icons/text.gif){kind=icon}
CHANGES 28-Mar-2008 08:40 5.6K
![[ ]](/icons/compressed.gif){kind=icon}
examples.tgz 29-Dec-2007 11:05 775
![[DIR]](/icons/folder.gif){kind=icon}
images/ 31-Dec-2007 12:43 -
![[ ]](/icons/layout.gif){kind=icon}
yeaGTD.pdf 28-Mar-2008 08:40 91K