mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
docs: Removed obsolete data.txt
This commit is contained in:
Paul Beckingham
parent
62989d2d1f
commit
957d8cf049
1 changed files with 0 additions and 177 deletions
177
doc/data.txt
177
doc/data.txt
|
|
@ -1,177 +0,0 @@
|
||||||
Timewarrior Data
|
|
||||||
================
|
|
||||||
Timewarrior has a conceptual timeline, which is a continuum onto which the
|
|
||||||
inclusions and exclusions are placed.
|
|
||||||
|
|
||||||
An inclusion is a block of time with associated tags, i.e. data captured or
|
|
||||||
provided that represents ongoing work.
|
|
||||||
|
|
||||||
An exclusion is also a block of time but represents untrackable time, and acts
|
|
||||||
as a mask for the inclusions that envelope it. 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
|
|
||||||
|
|
||||||
While an interval is open, it is simply recorded as a start time, with optional
|
|
||||||
tags. Once that interval is closed, it is flattened against the set of
|
|
||||||
exclusions, using these rules:
|
|
||||||
|
|
||||||
* If an open interval spans and encloses an exclusion, then flattening will
|
|
||||||
subtract that exclusion, effectively breaking the interval into two separate
|
|
||||||
intervals. As an example, support there is a lunch exclusion defined from
|
|
||||||
12:30pm - 1:30pm, and an interval was opened at 9:00am. If the interval is
|
|
||||||
closed at 5:30pm, the lunch exclusion is enclosed (entirely within the
|
|
||||||
interval), and subtracted. This yields two interval parts with the same
|
|
||||||
tags, the first 9:00am - 12:30pm, the second from 1:30pm - 5:30pm.
|
|
||||||
|
|
||||||
Inclusion: [---------------------------------) tag
|
|
||||||
Exclusion: [---) lunch
|
|
||||||
|
|
||||||
Recorded as: [-------------) [---------------) tag
|
|
||||||
|
|
||||||
Timeline: ..:...:...:...:...:...:...:...:...:...:...:...:...
|
|
||||||
8 9 10 11 12 1 2 3 4 5 6 7
|
|
||||||
am pm
|
|
||||||
|
|
||||||
* If an interval is opened during an exclusion period, it is recorded as-is.
|
|
||||||
Any start/stop/track time that comes from the command line is taken as more
|
|
||||||
accurate than configured exclusions.
|
|
||||||
|
|
||||||
Inclusion: [----------------) tag
|
|
||||||
Exclusion: [---) lunch
|
|
||||||
|
|
||||||
Recorded as: [----------------) tag
|
|
||||||
|
|
||||||
Timeline: ..:...:...:...:...:...:...:...:...:...:...:...:...
|
|
||||||
8 9 10 11 12 1 2 3 4 5 6 7
|
|
||||||
am pm
|
|
||||||
|
|
||||||
* If an interval is closed during an exclusion period, it is recorded as-is.
|
|
||||||
Any start/stop/track time that comes from the command line is taken as more
|
|
||||||
accurate than configured exclusions.
|
|
||||||
|
|
||||||
Inclusion: [-------------------) tag
|
|
||||||
Exclusion: [---) lunch
|
|
||||||
|
|
||||||
Recorded as: [-------------------) tag
|
|
||||||
|
|
||||||
Timeline: ..:...:...:...:...:...:...:...:...:...:...:...:...
|
|
||||||
8 9 10 11 12 1 2 3 4 5 6 7
|
|
||||||
am pm
|
|
||||||
|
|
||||||
* Any interval that is enclosed by an exclusion is recorded as-is.
|
|
||||||
|
|
||||||
Inclusion: [--) tag
|
|
||||||
Exclusion: [-------------------------------------) Day off
|
|
||||||
|
|
||||||
Recorded as: [--) tag
|
|
||||||
|
|
||||||
Timeline: ..:...:...:...:...:...:...:...:...:...:...:...:...
|
|
||||||
8 9 10 11 12 1 2 3 4 5 6 7
|
|
||||||
am pm
|
|
||||||
|
|
||||||
* Any interval that spans a month boundary, and therefore a data file boundary
|
|
||||||
will be split and written to both files.
|
|
||||||
|
|
||||||
If an open interval is shown in a report or exported, it is also flattened.
|
|
||||||
Flattening open intervals saves a lot of effort for the reports.
|
|
||||||
|
|
||||||
|
|
||||||
Exclusions
|
|
||||||
----------
|
|
||||||
Exclusions are stored only as configuration data.
|
|
||||||
|
|
||||||
|
|
||||||
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 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 in:
|
|
||||||
|
|
||||||
~/.timewarrior/undo.data
|
|
||||||
|
|
||||||
The level of granularity for undo operations is the command. One undo command
|
|
||||||
will reverse the effects of one command. This may involved multiple changes,
|
|
||||||
for example with an open interval, 'timew start' will close one interval and
|
|
||||||
open another, and those two changes are considered one transaction.
|
|
||||||
|
|
||||||
--- Raw Notes ---
|
|
||||||
|
|
||||||
- Recurring inclusions: meetings
|
|
||||||
- Define undo format
|
|
||||||
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue