mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
153 lines
4.1 KiB
Text
153 lines
4.1 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
|
|
|
|
|
|
[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 two consecutive recorded intervals with the 'tag1' and 'tag2' tags.
|
|
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'
|
|
|
|
|
|
[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
|
|
|
|
|
|
|
|
This uses a 'default' tag. 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
|
|
|
|
|
|
Fill Examples
|
|
-------------
|
|
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 example assume that there is no empty slot at the end of yesterday,
|
|
because it would also be filled.
|
|
|
|
|
|
Defining Exclusions
|
|
-------------------
|
|
|
|
$ 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
|
|
|
|
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.
|
|
|