mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
100 lines
3.3 KiB
Text
100 lines
3.3 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
|
|
import Import JSON data
|
|
export Export JSON data
|
|
help Show help text
|
|
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 exported data on
|
|
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.
|
|
|
|
- Intervals for different tags may overlap. We multitask.
|
|
|
|
- Need syntax to adjust any recorded data.
|
|
|