mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
128 lines
4 KiB
Text
128 lines
4 KiB
Text
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 <version> <category> <message>
|
||
|
||
--- Raw Notes ---
|
||
|