Timesheet file format

The goal of this project is to define a file format that allows the user to record the time spent on tasks (a timesheet). The design is inspired by Tim Weber's timesheet.txt.


The motivation behind this project is personal usage. I wanted to be able to track time easily in a system that was durable. This project pretends to specify a file format that is easy to parse (by a machine) and read (by a human).

The requirements to work with such format should only be access to a text editor, although there will be a script that lets the user view and edit such a file from the command line.

Why plain text? Because it is easy to read and write, and you don't need any special program to access your data. On top of that, it is easy to parse, so anyone a bit familiar with programming will be able to create a parser that works exactly how they want. Even if you don't, hopefully my parser is easy to understand, and it should take an interested user less than half an hour to get familiar with the code.


A bit more formally. In a timesheet file, each line fits in one of the following categories:

The definition of the format symbols:

On top of that, any line can start and/or end with any amount of spaces and/or tabs (which should be ignored by the parser). Any line can have comments at the end, which start with a # surrounded by spaces (or end of line characters) and end at the end of the line.

When parsing the description of a task, tags will be substituted by a space in the description, and then any leading or trailing spaces will be deleted. Therefore, any tags appearing at the start or end of the description will be completely deleted, while tags in between description text will be substituted by a space.

All entries must be in chronological order and there must not be two entries starting at the same time. If no second is specified for the start time of a task, the default value is 0.

If no day is specified when continuing a task by start time, then the current day is used (the day specified on last date change).


An example of a file would be:



I hope to end up with a file without any ambiguities. If you have a question that is not answered, please contact me or open an issue.