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 exlcusions. 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 holidays eng-USA exc work 2015-11-26 exc workweek mon,tue,wed,thu,fri exc workday start 8:30am exc workday end 1730 exc workday tue end 3pm inc 2016-02-28T08:00 - 2016-02-28T12:00 # Upgrade Planning inc 2016-02-28T13:00 # Upgrade Presentation "ABCD Inc" White space is ignored. Here we see a sect of exlcusions 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 exlcusions prevent an excess time buildup of the 63 hours that compries the weekend (Friday 5:30pm until Monday 8:30am). Data File Names --------------- The data file names will have the year and month embedded, which acts as a heuristic for filtering, keeps the data files small and therefore quicker to manipulate, and eliminates 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 Logging ------- Timewarrior will log many messages, but the logging will be configurable. The configuration will be: define configuration: logging: file /path/to/log/file categories a,b,c,!d This indicates that categories 'a', 'b', and 'c' are desired, and 'd' is explicitly not desired. The categories are: command (distinguishes tty and non-tty commands) performance rules io parsing warnings errors info A log entry will have this form: YYYY-MM-DDTHH:MM:SS ---