Timewarrior Data
================
Timewarrior has a conceptual timeline, which is a continuum onto which the
inclusions and exclusions are mapped.

An inclusion is a block of time with associated tags, i.e. data captured or
provided by the user representing ongoing work.

An exclusion is also a block of time but represents untrackable time, and acts
as a mask for the inclusions. Here is a visual example:

  Inclusion:           |-----------------------------------| tag1
  Exclusion:                           |---| lunch
  Exclusion                                                    |---| dinner

  Timeline:     >--o---o---o---o---o---o---o---o---o---o---o---o---o-->
                   7   8   9   10  11  12  1   2   3   4   5   6   7 
                   am                  pm

In the example, there is one incluѕion, a block of time from 8am - 5pm, tagged
with 'tag1'. That was data captured from the command line, perhaps with this
command:

  $ timew track 8am - 5pm tag1

There are several ways to track time that result in the same inclusion, for
example, if these commands were run at 8am and 5pm respectively:

  [at 8am] $ timew start tag1
  [at 5pm] $ timew stop

It can be seen that some combination of all the incluѕions and exclusions will
yield a complete record of tracked time.


Exclusions
----------
Exclusions are stored as configuration, and there are several commands that
allow easy manipulation of this. Whenever an exclusion changes, the set of all
exclusions are written to the data file. This is because all subsequent
inclusions are to be resolved against the active set of exclusions.


Inclusions
----------
Inclusions are captured from the command line in many different ways, but all
results in an incluѕion record being written to the data file.

If there is an open-ended inclusion at the time an exclusion is changed, then
the open-ended inclusion is closed, the exclusions written, and a new open-ended
inclusion is added.


Data Files
==========
The data file is a text file, which grows in length. It begins with a set of
exclusions, followed by a set of inclusion records that utilize the prior set of
exclusions.

An example file looks like this:

  exc monday 8:00:00-12:00:00 12:45:00-17:30:00
  exc tuesday 8:00:00-12:00:00 12:45:00-18:30:00
  exc wednesday 8:00:00-12:00:00 13:30:00-17:30:00
  exc thursday 8:00:00-12:00:00 12:45:00-17:30:00
  exc friday 8:00:00-12:00:00 12:45:00-17:30:00
  exc day on 2016-01-01
  exc day off 2016-01-02

  inc 2016-02-28T08:00:00 - 2016-02-28T12:00:00 # Upgrade Planning
  inc 2016-02-28T13:00:00                       # Upgrade Presentation "ABCD Inc"

White space is ignored. Here we see a sect of exclusions that define a work week
and a two inclusions, the first of which represents a four hour block of time
with two tags 'Upgrade' and 'Planning'. The second inclusion is open ended,
having only a start time (1pm), but three tags 'Upgrade', 'Presentation' and
'ABCD Inc'. The third tag is a quoted string because of the embedded space.

An open-ended inclusion like this means that the tracking continues, but the
exclusions prevent an excess time buildup of the 63 hours that comprise the
weekend (Friday 5:30pm until Monday 8:30am).


Data File Names
---------------
The data file names will have the year and month numbers, which keeps the data
files small and therefore quicker to manipulate, eliminating the need for any
sophisticated archiving. For example:

  ~/.timewarrior/data/2016-02.data
  ~/.timewarrior/data/2016-03.data


Undo Data
---------
The undo stack will be stored as:

  ~/.timewarrior/undo.data


--- Raw Notes ---

- Recurring inclusions: meetings