mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
122 lines
5.1 KiB
Text
122 lines
5.1 KiB
Text
Timewarrior Project
|
||
===================
|
||
Timewarrior is a program that records tagged time blocks that represent tracked
|
||
time. This data is then used to create reports that shwo how time was spent.
|
||
|
||
To make this task easier, and more useful, Timewarrior can access holidays, a
|
||
pre-defined working schedule, and support flexible time/date specifications,
|
||
implement a simple stop-watch tracking feature, generate custom reports, and
|
||
apply a set of rules to impose constraints and check the data.
|
||
|
||
Using a hook scripts, Timewarrior can be used as a backend time-tracking
|
||
feature for Taskwarrior, any other program, or as a standalone utility.
|
||
|
||
Timewarrior aims to be the tool of choice if you need to track time and generate
|
||
timesheets.
|
||
|
||
|
||
Goals
|
||
-----
|
||
Provide a personal tool to easily track time spent and generate reports in
|
||
multiple formats and styles. The tool will "do the right thing" as much as
|
||
possible, to make detailed time tracking easy, and low friction.
|
||
|
||
Data will be stored as plain UTF8 text.
|
||
|
||
Open Source.
|
||
|
||
|
||
Non-Goals
|
||
---------
|
||
- No cloud support, no sync support, all data is local. Tracked time is
|
||
sensitive personal data and wll not be transmitted.
|
||
- No explicit multi-user support, although using tags to track individuals is
|
||
possible.
|
||
- No precision higher than a minute.
|
||
|
||
|
||
Tags
|
||
----
|
||
Tags represent tracking categories. Tags are arbitrary UTF8 strings. A tag may
|
||
be a single unquoted word, or a quoted phrase.
|
||
|
||
A tag may be used without being defined, but if a tag is defined, then it may
|
||
have associated metadata, such as a start date representing the first date on
|
||
which it may be used, or an end date, when it expires. A tag may have a budget,
|
||
which is the maximum trackable time for a period.
|
||
|
||
|
||
Macros
|
||
------
|
||
A macro is a keyword that can take arguments, and expands to a set of one or
|
||
more other timew commands, with some dynamic aspect. For example, the macro
|
||
named 'staff meeting' could be an interval that is on Wednesdays at 10:00, and
|
||
has a set of associated tags. This would then create an appropriately tagged
|
||
interval.
|
||
|
||
|
||
Commands
|
||
--------
|
||
The command set may include:
|
||
|
||
define Modify configuration
|
||
track Record tracked time
|
||
report Run a report
|
||
tags Show all tags
|
||
query Extract an interval set
|
||
import Import JSON data
|
||
export Export JSON data
|
||
x Run extension 'x'
|
||
|
||
|
||
Extensions
|
||
----------
|
||
A simple extension mechanism would require an executable script found in a
|
||
defined location with a conformant name, which then is fed queried raw data as
|
||
stdin.
|
||
|
||
For example, this script clearly defines that it is a 'report' extension named
|
||
'abc'.
|
||
|
||
~/.timewarrior/extensions/report_abc
|
||
|
||
---
|
||
|
||
- Given this:
|
||
$ timew track yesterday 9am - 5pm tag1
|
||
What does this do:
|
||
$ timew track yesterday 10am - 11am tag2
|
||
Does it yield:
|
||
a) yesterday 540-1020 tag, 600-660 tag2 # overlap
|
||
b) yesterday 540-600 tag1, 600-660 tag2, 660-1020 tag1 # no overlap
|
||
c) yesterday 540-600 tag1, 600-660 tag1 tag2, 660-1020 tag1 # explicit overlap
|
||
Stating 'track yesterday 10am - 11am tag2' sounds imperative, thus overriding any existing tags in that interval. Perhaps a 'merge' keyword could be added to combined the results (track yesterday 10am - 11am tag2 merge)?
|
||
|
||
- Need an undo feature.
|
||
|
||
- Need a log file, controlled by a logging rule.
|
||
|
||
- start (frontfill) and backfill (end) could be considered orthogonal to each other. They just operate into different directions. but I think they behave the same, more or less.
|
||
|
||
- Intervals for different tags may overlap. We multitask.
|
||
|
||
- Need syntax to adjust any unarchived recorded data.
|
||
|
||
P: There is no open-ended fill though. The future is infinite, so we don’t want to actually record much. Anything bounded, yes (“until eod”), but anything unbounded (“track ‘do this’”) just leaves it open.
|
||
F: it fills from the last good point, goes backwards in time until it hits a stop/interval limit.
|
||
P: Yes, unless you bound it. ie “timew track last week ‘this thing’” can back fill within the “last week”, but exclude any otherwise tracked intervals.
|
||
Then we can support a “merge” keyword to overlap any tracked intervals.
|
||
F: If you add fill to this I would expect it to start at the end of last week, find the empty intervall and fill it until it hits a limit or another already filled interval.
|
||
So it only does one thing.
|
||
while the command without fill would operate on the entire week instead.
|
||
but this would just be me.
|
||
P: Let’s explore that. Suppose “last week” is 39 hours of nothing, and 1 hour of a meeting. Suppose we indicate (for clarity here) keywords as “:keyword”. The question then becomes what do the following do:
|
||
$ timew track last week “paint the thing”
|
||
$ timew track last week “paint the thing” :fill
|
||
Our choices are:
|
||
39 hours of “paint the thing” filled around the 1 hour “meeting”.
|
||
Or 40 hours of “paint the thing” overlapping with 1 hour “meeting”
|
||
Or 40 hours of “paint the thing”, and the meeting is gone
|
||
F: hm, b would be first choice.
|
||
“a" would be second or third.
|
||
|