h1. Task file format

h2. File Format

The task file format (format 4) is a simple one.  It looks like this:

<pre>[attribute1:"value1" attribute2:"value2" .. ]\n</pre>

Each attribute is represented as a name, a colon, then a double-quoted value, with a space before the next attribute.  The whole set of attributes is grouped between square brackets, and is terminated by a newline character.

This simple format is one that be easily searched by another program without the need to use task, if necessary.  For example:

<pre>% grep status:\"pending\" ~/.task/pending.data</pre>

It is not recommended that another program write to this file format, because task requires certain semantics within the file (there must be an "entry" attribute, for example), and those semantics are evolving, and an incorrect entry may cause problems for task.

A programmatically safer way to read tasks is to export them from task into a known, stable format and then read that file.

h2. Previous File Formats

Task has used three previous file formats, since version 0.1.  The first format is no longer supported, and in fact never even made it to version 1.0.  Formats 2 and 3 are still supported by task.  When task reads a file, all three supported formats are read.  When task writes a file, only the latest format is used.  This has the positive effect of upgrading your task files automatically.  There is also a negative effect: once your task files are upgraded, there is no going back.  For this reason, whenever the file format changes, it is recommended that you make a backup of your file before upgrading task, just in case you want to revert to the prior version.

If you do wish to revert to a prior version, it may be for several good reasons.  You may not like the latest version for whatever reason.  Or it may not work correctly, or to your expectations.  In this case, we would like to hear about your experience, so please post to the forums, and let us know what you find unacceptable.  We'll try to accommodate your wishes.

h2. Future File Formats

While there are no plans to change the file format in significant ways, there will be changes to the semantics.  There will also be changes to the way attribute values are formatted, allowing for multi-dimensional attributes.  But not yet.