mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
126 lines
4.5 KiB
Text
126 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 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 tools to easily track time spent and generate reports 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.
|
|
- 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.
|
|
- There is no hook system as Timewarrior is a data sink, not a data source.
|
|
- 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, or 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'.
|
|
|
|
|
|
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
|
|
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'
|
|
|
|
|
|
Undo
|
|
----
|
|
All commands than change configuration or data need to be logged as-is in the
|
|
undo.data file, so that an 'undo' command can later rewind the changes.
|
|
|
|
All undo will happen at the command level, not the delta level.
|
|
|
|
|
|
Extensions
|
|
----------
|
|
A simple extension mechanism allows custom reports to be written and shared.
|
|
|
|
---
|
|
|
|
- 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.
|
|
|
|
- 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”.
|
|
|
|
- There is no hook system, but there will be rules that accomplish the same thing, almost.
|
|
|