mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-06-26 10:54:28 +02:00
132 lines
4.5 KiB
Text
132 lines
4.5 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 show how that 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 simply 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 and report time spent, with low
|
||
friction.
|
||
- Support all workflows.
|
||
- Provide an extension-friendly tool.
|
||
- Support policies via the rules system.
|
||
- Integrate with Taskwarrior, Tasksh.
|
||
- Store data in plain UTF-8 text.
|
||
|
||
|
||
Non-Goals
|
||
---------
|
||
- Completely independent from Taskwarrior, Taskserver, Tasksh.
|
||
- Time tracking is about recording the past, not planning the future.
|
||
- No cloud support, no sync support, all data is local. Tracked time is
|
||
sensitive personal data and will not be transmitted.
|
||
- No explicit multi-user support, although using tags to track individuals is
|
||
possible.
|
||
- There is no hook system as Timewarrior is a data sink, not a data source.
|
||
That said, there will be rules that can act as hooks, but will be more
|
||
flexible.
|
||
- No features without a compelling use case.
|
||
|
||
|
||
Tags
|
||
----
|
||
Tags represent tracking categories. Tags are arbitrary UTF8 strings. A tag may
|
||
be a single unquoted word, or a quoted string if it includes spaces.
|
||
|
||
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, and an end date, when it expires. A tag may have a budget,
|
||
which is the maximum trackable time for a period.
|
||
|
||
An interval may have multiple tags associated with it, but the tags apply to the
|
||
whole interval only. In this example, there are overlapping tags:
|
||
|
||
$ timew start tag1
|
||
...
|
||
$ timew start tag2
|
||
...
|
||
$ timew stop tag1
|
||
...
|
||
$ timew stop
|
||
|
||
By default, when the interval for 'tag2' starts, the interval for 'tag1' is
|
||
automatically stopped, because tags do not overlap. This then makes the next
|
||
command ('timew stop tag1') yield an error, because 'tag1' was not active. If
|
||
however, both 'tag1' and 'tag2' are defined with the 'overlap' metadata, then
|
||
there will not be an automatic stop for 'tag1'.
|
||
|
||
|
||
Hints
|
||
-----
|
||
There are built-in hints, that influence processing. For example, ':debug' puts
|
||
the program in debug mode, and ':fill' indicates to a 'track' command that you
|
||
wish to fill in the available time. Another hint, ':week' means that a command
|
||
should only affect the last week.
|
||
|
||
There are user-defined hints, that can act as macros⁄aliases, for example the
|
||
':staff' hint could mean a 'Staff Meeting' and 'Admin' tag set.
|
||
|
||
|
||
Commands
|
||
--------
|
||
The command set will include:
|
||
|
||
config Modify configuration
|
||
track Record tracked time
|
||
report Run a report
|
||
undo Undo a change
|
||
tags Show all tags
|
||
gaps Show untracked gaps in the schedule
|
||
import Import JSON data
|
||
export Export JSON data
|
||
help Show help text
|
||
x Run extension 'x'
|
||
|
||
There will be built-in commands, and an extensions mechanism that allows reports
|
||
to be added as extensions, while being handled as though they were built-ins.
|
||
|
||
|
||
Undo
|
||
----
|
||
All commands that change configuration or data need to be recorded as-is in the
|
||
undo.data file, so that an 'undo' command can later rewind the changes properly.
|
||
|
||
All undo will happen at the command level, not the delta level. That means if
|
||
one command results in three changes, a single 'undo' command will revert the
|
||
three changes associated with the one command.
|
||
|
||
|
||
Extensions
|
||
----------
|
||
A simple extension mechanism allows custom reports to be written and shared.
|
||
Most reports will be external scripts that use the extension API.
|
||
|
||
|
||
DOM Access
|
||
----------
|
||
Timewarrior will support a DOM, allowing rules and extensions to access internal
|
||
data.
|
||
|
||
[TBD]
|
||
|
||
|
||
--- Raw Notes ---
|
||
|
||
- Need syntax to adjust any recorded data.
|
||
|
||
- It should be forgiving when you forgot to stop a task. Maybe a specific
|
||
command, instead of "stop" use "forgot" or directly "edit". Then I would
|
||
like to express either "stopped 30min ago" or "it lasted only 1hour”.
|
||
|