mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
225 lines
6.3 KiB
Text
225 lines
6.3 KiB
Text
Use Cases
|
|
=========
|
|
This document contains a set of use cases and expected behavior. This will
|
|
gradually change into a feature spec. The use cases are grouped functionally:
|
|
|
|
[1] Basic Usage
|
|
[2] Reports
|
|
[3] Exclusions
|
|
[4] Tags
|
|
[5] Fill
|
|
[6] Configuration
|
|
|
|
|
|
[1.1] Basic Usage: clock
|
|
------------------------
|
|
Using the 'start' and 'stop' commands without tags just records time intervals:
|
|
|
|
$ timew start
|
|
...
|
|
$ timew stop
|
|
|
|
This results in a recorded interval with the 'default' tag.
|
|
|
|
|
|
[1.2] Basic Usage: clock + tags
|
|
-------------------------------
|
|
Using the 'start' and 'stop' commands with tags just records time intervals:
|
|
|
|
$ timew start tag1
|
|
...
|
|
$ timew start tag2
|
|
...
|
|
$ timew stop
|
|
|
|
This results in the 'tag1' interval being automatically stopped, and the new
|
|
'tag2' interval starting. The 'stop' command stops all tracking. As these tags
|
|
are not defined, there is no additional metadata.
|
|
|
|
|
|
[1.3] Basic Usage: no arguments
|
|
-------------------------------
|
|
Simply running the command with no arguments will show any currently tracking
|
|
interval, with associated tags:
|
|
|
|
$ timew
|
|
2016-02-29 8:00:00 - now, 3:11:24 total, using 'tag1'
|
|
|
|
If 'tag1' has a defined color, it is used here to color the 'tag1' string.
|
|
|
|
|
|
[2.1] Reports: Summaries
|
|
------------------------
|
|
There are several time-based default reports which summaries tracked time over
|
|
preset periods:
|
|
|
|
$ timew report day
|
|
$ timew report week
|
|
$ timew report month
|
|
$ timew report quarter
|
|
$ timew report year
|
|
$ timew report
|
|
|
|
|
|
[3.1] Exclusions: Work Week
|
|
--------------------------
|
|
|
|
$ timew define holidays eng-USA
|
|
$ timew define holidays work 2015-11-26
|
|
$ timew define workweek mon-fri
|
|
$ timew define workday start 8:30am
|
|
$ timew define workday end 1730
|
|
$ timew define workday tue end 3pm
|
|
|
|
|
|
[5.1] Fill: Backfill
|
|
--------------------
|
|
If the time is 12:13pm, the workday starts at 8:00am, and you have already
|
|
tracked a 9am-10am meeting, then this command will automatically backfill
|
|
the 8am-9am interval only:
|
|
|
|
$ timew track 8am "Reading email"
|
|
|
|
Similarly, this command will do the same thing:
|
|
|
|
$ timew track 8:23am "Reading email" :backfill
|
|
|
|
These two examples assume that there is no empty slot at the end of yesterday,
|
|
because it would also be filled.
|
|
|
|
Backfill involves looking backwards from the stated date/time, looking for an
|
|
interval to define the start.
|
|
|
|
Only when a range is bounded can :fill and :backfill determine the interval.
|
|
|
|
|
|
[5.2] Fill: Fill (forwards)
|
|
---------------------------
|
|
If a time range is bounded, then :fill can determine an end point, and fill the
|
|
gap. For example:
|
|
|
|
$ timew track today tag1
|
|
|
|
The 'today' is a bounded range, and this command will use 'tag1' for an interval
|
|
that extends all day today. Similarly 'tomorrow', 'next week' are bounded.
|
|
|
|
|
|
[5.3] Fill: Autofill
|
|
--------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
By using tags, this becomes:
|
|
|
|
$ timew start tag1 # Start tracking now
|
|
$ timew start "Home Improvement Project" # Stop old interval, start new interval now
|
|
$ timew stop # Stop all tracking
|
|
$ timew report month # Run report 'month'
|
|
|
|
If a time is specified, it always means today:
|
|
|
|
$ timew track 8am - 10am tag1
|
|
|
|
If days are specified, they always mean the past:
|
|
|
|
$ timew track mon - wed tag1
|
|
|
|
If today is thursday, the following covers the curent week because the previous
|
|
monday would be after the previous friday, therefore the friday refers to the
|
|
next friday, at EOW:
|
|
|
|
$ timew track mon - fri tag1
|
|
|
|
If overlapping intervals are permitted (configuration: interval.overlap=yes),
|
|
then this creates overlapping intervals:
|
|
|
|
1 $ timew start tag1
|
|
...
|
|
2 $ timew start tag2
|
|
...
|
|
3 $ timew stop tag1
|
|
...
|
|
4 $ timew stop tag2
|
|
|
|
With overlapping intervals:
|
|
o-------o tag1
|
|
o--------o tag2
|
|
1--2----3---4---> time
|
|
|
|
Track time but backfill to the most recent interval end:
|
|
|
|
$ timew track :backfill tag1
|
|
|
|
Record yesterday's time:
|
|
|
|
$ timew track yesterday tag1
|
|
|
|
|
|
|
|
|
|
The above examples simply use ad-hoc tags, which is an undefined tag. They are
|
|
simply used as tags, and have no metadata. Defining a tag allows it to have
|
|
associated metadata:
|
|
|
|
$ timew define tag "tag1"
|
|
$ timew define tag "tag1" description "Description of tag1"
|
|
$ timew define tag "tag1" start 2016-01-01
|
|
$ timew define tag "tag1" end 2016-06-30
|
|
$ timew define tag "tag1" budget 20 hours per week
|
|
$ timew define tag "tag1" budget 400 hours total
|
|
$ timew define tag "tag1" overlap
|
|
|
|
---
|
|
|
|
- Need to break all these out into separate sections, where each is discussed in
|
|
sufficient detail to then generate user docs and code.
|
|
|
|
- Need to differentiate ":fill", ":backfill" and automatic fill.
|
|
|
|
- Outline case for double-tracking, perhaps where a manager tracks the time of
|
|
several employees. This would require that tracked time for a single tag has
|
|
no overlaps, but allowing overlapping intervals might need configuration to
|
|
allow this.
|
|
|
|
- Do we need arbitrary exclusions? Lunch? Dentist Appointment? or are those
|
|
just different inclusions?
|
|
|
|
- Suppose "last week" is 39 hours of nothing, and 1 hour of a meeting. The
|
|
question becomes what do the following do:
|
|
|
|
[1] $ timew track last week "paint the thing"
|
|
[2] $ timew track last week "paint the thing" :fill
|
|
|
|
Our choices are:
|
|
[a] 39 hours of "paint the thing" filled around the 1 hour "meeting".
|
|
[b] 40 hours of "paint the thing" overlapping with 1 hour "meeting"
|
|
[c] 40 hours of "paint the thing", and the meeting is gone
|
|
|
|
Consensus: [b], but configurable.
|
|
|
|
- Given this scenario:
|
|
|
|
Exclusion: ------|
|
|
Exclusion: |----------
|
|
Inclusion: |-|
|
|
Now: |
|
|
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
|
|
|
|
$ timew track this morning :fill tag inc 8am - 9am # tag
|
|
|
|
$ timew track this morning :fill :active tag inc 8am - 9am # tag
|
|
inc 9:30am - # tag
|
|
|
|
$ timew track today tag inc 8am - 9am # tag
|
|
inc 9:30am - # tag
|
|
|
|
$ timew track 8am - 9am tag inc 8am - 9am # tag
|
|
|
|
$ timew start tag1 :fill inc 9:30am - # tag
|
|
|