mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
128 lines
3 KiB
Text
128 lines
3 KiB
Text
CLI Syntax
|
|
----------
|
|
The CLI shall have a well-defined and unambiguous grammar.
|
|
|
|
timew start|stop [<tagset>]
|
|
timew track <interval> [<tagset>]
|
|
timew clear <tagset>|<interval>
|
|
timew continue
|
|
timew
|
|
|
|
timew [<filter>] report <report>
|
|
|
|
timew define day <day> <start> - <end> [, <start> - <end> ...]
|
|
timew define day on|off <date>
|
|
|
|
timew define tag <tag> description <string>
|
|
timew define tag <tag> start|end <date>
|
|
timew define tag <tag> budget <number> <units> per <unit>
|
|
timew define tag <tag> budget <number> <units> total
|
|
timew define tag <tag> overlap
|
|
timew define tag <tag> color <color>
|
|
|
|
timew undo
|
|
|
|
timew tags [<filter>]
|
|
timew gaps [<interval>]
|
|
timew extensions
|
|
|
|
timew export [<interval>] [<tagset>]
|
|
timew import <file>|- ...
|
|
|
|
timew help [<command>|<keyword>|examples]
|
|
timew diagnostics
|
|
|
|
|
|
CLI Grammar
|
|
-----------
|
|
Assumed built-in types:
|
|
<datetime>
|
|
<duration>
|
|
<time>
|
|
<string>
|
|
|
|
interval: <timestamp> "-" <timestamp>
|
|
<timestamp> "to" <timestamp>
|
|
<timestamp> "for" <duration>
|
|
"from" <timestamp> "to" <timestamp>
|
|
"until" <timestamp>
|
|
"from" <timestamp>
|
|
|
|
timestamp: <day> <time>
|
|
|
|
tagset: <tag>+
|
|
|
|
tag: string
|
|
|
|
|
|
Intervals
|
|
---------
|
|
An interval defines a block of time, either using precise values, or vague
|
|
values that are interpreted according to context, yielding precise values. The
|
|
general form is:
|
|
|
|
Precise:
|
|
YYYY-MM-DDTHH:MM:SS[Z|±HH:MM]
|
|
now
|
|
8:23:00
|
|
9am
|
|
|
|
Vague (and precise interpretation):
|
|
today :backfill - now :active
|
|
this morning :backfill - 12:00:00
|
|
last tuesday YYYY-MM-DD :fill
|
|
yesterday YYYY-MM-DD :fill
|
|
|
|
An interval may be open ended:
|
|
|
|
- B
|
|
A - B
|
|
A -
|
|
A
|
|
|
|
When resolving an interval, vague terms are influenced by configured exclusions
|
|
and rules. Precise terms _always_ override rules.
|
|
|
|
|
|
Tagset
|
|
------
|
|
A tagset is a set of unique UTF-8 strings, each indentifying some trackable
|
|
entity, for example:
|
|
|
|
$ timew start Home Garden "Sprint 2016"
|
|
---- ------ -------------
|
|
tag tag tag
|
|
|
|
-------------------------
|
|
tagset
|
|
|
|
Tags must be quoted if they contains spaces.
|
|
|
|
|
|
Hints
|
|
-----
|
|
There are built-in and custom hints, that look like this:
|
|
|
|
:fill
|
|
|
|
They begin with a colon, and are heuristics for Timewarrior. They can override
|
|
feedback (:quiet) or offer guidance on how to create an interval (:fill). The
|
|
supported hints are:
|
|
|
|
:fill Fill in gap
|
|
:backfill Fill in gap, backwards only
|
|
:interrupt Identify the interval as a temporary interruption
|
|
:noreport Prevent the interval being reported
|
|
:quiet No feedback
|
|
:week Macro that means 'this week'
|
|
:debug Turns on debugging mode
|
|
:x User defined
|
|
|
|
|
|
--- Raw Notes ---
|
|
|
|
- 'timew import <file>' will merge data.
|
|
|
|
- A command for a daily and weekly view of exclusions is needed. To verify that
|
|
it is correctly defined. A text-based list should accompany it.
|
|
|