Timelog Format, version 2
The format of this file was strongly influenced by the design of the todo.txt system created by
Gina Trapani. The major idea was to have a format that could be easily read and modified by a human
with a text editor. This format should be a simple as possible, and require no proprietary
technology to read or write.
Some of the data stored in the file and the reporting of the data was influenced by years of use of the TEAK tool on the Palm. I wrote this tool to replace TEAK once it was obvious that the Palm was no more.
Description
Each time entry resides on a line by itself. Each line is made up of an optional marker and two parts separated by a marker character, usually a space: a time/date stamp and a task description. There should be no leading or trailing white space on the lines.
The format also supports comments defined as having a # as the first character on the line.
Time/Date Stamp
The time/date stamp is the first thing on each line and is set in the local timezone. Except where we cross from Daylight Saving Time to Standard Time or vice versa this should cause no problems.
The format of this part of the line is ‘YYYY-MM-DD HH:MM:SS’. This format is relatively easy for a person to read, is easily and unambiguously parsed, and sorts nicely.
Entry
The entry is just text that describes the task or event we are now beginning. To enhance reporting,
there are two forms of metadata. The first string starting with a + is treated as a project. All
events with the same project are reported together. The first string starting with @ is treated as
the name of the task. Any remaining text is treated as further detail on the task.
If no task name is specified, all of the event string except the project is treated as the task name. The task name is optional because not everyone will find it useful to define consistent tasks for reporting.
There is one special case. An entry of stop stops timing the current task without starting a new
task.