mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
108 lines
3.5 KiB
Text
108 lines
3.5 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: ..:...:...:...:...:...:...:...:...:...:...:...:...:...
|
||
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
|
||
|
||
|
||
Exclusions
|
||
----------
|
||
Exclusions are stored only as configuration.
|
||
|
||
|
||
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, and a new open-ended inclusion is added.
|
||
Starting a new inclusion closes existing inclusions.
|
||
|
||
|
||
Data Files
|
||
==========
|
||
The data file is a text file, which grows in length. It contains a set of
|
||
inclusion records.
|
||
|
||
An example file looks like this:
|
||
|
||
inc 20160228T080000Z - 20160228T120000Z # Upgrade Planning
|
||
inc 20160228T130000Z # Upgrade Presentation "ABCD Inc"
|
||
|
||
Blank lines are ignored. The first inclusion 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 UTC), 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 62½ hours that comprise the
|
||
weekend (Friday 5:30pm until Monday 8:00am).
|
||
|
||
|
||
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
|
||
|
||
To archive old data, simply move any subset of files out of this directory.
|
||
|
||
|
||
Long Inclusions
|
||
---------------
|
||
If an inclusion spans multiple data files, it is broken into adjacent inclusions
|
||
for each data file. For example, with an empty database, an inclusion of:
|
||
|
||
inc 20160101T000000Z - 20160415T000000Z # tag1
|
||
|
||
Will be broken into separate inclusions, each in a separate file:
|
||
|
||
2016-01.data: inc 20160101T000000Z - 20160131T000000Z # tag1
|
||
2016-02.data: inc 20160201T000000Z - 20160229T000000Z # tag1
|
||
2016-03.data: inc 20160301T000000Z - 20160331T000000Z # tag1
|
||
2016-04.data: inc 20160401T000000Z - 20160415T000000Z # tag1
|
||
|
||
If the database is not empty, then checks for overlapping tags may prevent the
|
||
above records being written.
|
||
|
||
|
||
Undo Data
|
||
---------
|
||
The undo stack will be stored as:
|
||
|
||
~/.timewarrior/undo.data
|
||
|
||
|
||
--- Raw Notes ---
|
||
|
||
- Recurring inclusions: meetings
|
||
|