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.