mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
Docs: Removed obsolete examples.txt
This commit is contained in:
Paul Beckingham
parent
18fabf11ab
commit
62be29f2eb
1 changed files with 0 additions and 235 deletions
235
doc/examples.txt
235
doc/examples.txt
|
|
@ -1,235 +0,0 @@
|
|||
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.
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue