mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
279 lines
8.2 KiB
Text
279 lines
8.2 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 day monday 8am - 12pm, 12:45pm - 5:30pm
|
|
$ timew define day tuesday 8am - 12pm, 12:45pm - 6:30pm
|
|
$ timew define day wednesday 8am - 12pm, 1:30pm - 5:30pm
|
|
$ timew define day thursday 8am - 12pm, 12:45pm - 5:30pm
|
|
$ timew define day friday 8am - 12pm, 12:45pm - 5:30pm
|
|
$ timew define day on 2016-01-02
|
|
$ timew define day off 2016-01-01
|
|
|
|
|
|
[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
|
|
--------------------
|
|
Given an exclusion that ends at 8am, and another that begins at 5pm (defining a
|
|
work day), then the following commands need to be explained:
|
|
|
|
$ timew track today ...
|
|
|
|
This will create an open tracking interval starting at 8am, because of the lack
|
|
of a specific start time, and the presence of configured exclusions.
|
|
|
|
$ timew track 7:45am ...
|
|
|
|
This will create an open tracking interval starting at 7:45am, because of the
|
|
specific start time, which always overrides exclusions. This means is possible
|
|
to track time that exists entirely within an exclusion, provided there is a
|
|
specific start and stop time.
|
|
|
|
|
|
[6.1] Configuration: Storing/accessing settings
|
|
-----------------------------------------------
|
|
With a 'config' command, all configuration data will be accessible. The command:
|
|
|
|
$ timew config name value
|
|
|
|
Will result in an update to the configuration file:
|
|
|
|
name = value
|
|
|
|
Using the '.' character allows the rule to reflect hierarchical configuration
|
|
data:
|
|
|
|
$ timew config one.two.three four
|
|
$ timew config one.two.five six
|
|
|
|
Will construct the rule like this:
|
|
|
|
define configuration:
|
|
one:
|
|
two:
|
|
three = four
|
|
five = six
|
|
|
|
The process of converting this rule structure to 'one.two.three four' is called
|
|
normalizing.
|
|
|
|
|
|
[6.2] Configuration: Running in debug mode
|
|
------------------------------------------
|
|
Running in debug mode reveals internal details that aid troubleshooting. To run
|
|
in debug mode, add the ':debug' hint to the command line:
|
|
|
|
$ timew ... :debug
|
|
|
|
|
|
[6.3] Configuration: Running without generating output
|
|
------------------------------------------------------
|
|
Running in quiet mode prevents all feedback. This is useful for automation
|
|
scripts. To run un quiet mode, add the ':quiet' hint to the command line:
|
|
|
|
$ timew ... :quiet
|
|
|
|
|
|
--- Raw Notes ---
|
|
|
|
- Incorporate the following old notes into the above doc:
|
|
|
|
|
|
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.
|
|
|
|
- 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
|
|
|