mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-06-26 10:54:28 +02:00
235 lines
6.7 KiB
Text
235 lines
6.7 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 summarizes tracked time over
|
||
preset periods:
|
||
|
||
$ timew summary :day
|
||
$ timew summary :week
|
||
$ timew summary :month
|
||
$ timew summary :quarter
|
||
$ timew summary :year
|
||
$ timew summary <from> - <to>
|
||
$ timew summary
|
||
|
||
|
||
[4.1] Tags: Non-overlapping
|
||
---------------------------
|
||
With non-overlapping tags, starting an interval closeѕ and existing interval:
|
||
|
||
$ timew start tag1
|
||
...
|
||
$ timew start tag2
|
||
|
||
The second command automatically stops tracking 'tag1'.
|
||
|
||
|
||
[4.2] Tags: Combining
|
||
---------------------
|
||
With non-overlapping tags, intervals can be controlled by adding and removing
|
||
tags:
|
||
|
||
$ timew start tag1 tag2
|
||
...
|
||
$ timew stop tag1
|
||
...
|
||
$ timew stop
|
||
|
||
The 'stop' command subtracts tags, and subtracts all tags if none are specified
|
||
which makes the above equivalent to:
|
||
|
||
$ timew start tag1 tag2
|
||
...
|
||
$ tiemw start tag2
|
||
...
|
||
$ tiemw stop
|
||
|
||
|
||
[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:
|
||
|
||
one:
|
||
two:
|
||
three = four
|
||
five = six
|
||
|
||
The process of converting this 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 ---
|
||
|
||
- 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
|
||
|
||
- Need example and handling for people with exclusions that are not based on a
|
||
seven-day cycle. Example, I have have every other friday off. This should be
|
||
a supported exclusion, not 26 exceptions.
|
||
|