mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
124 lines
2.9 KiB
Text
124 lines
2.9 KiB
Text
CLI Syntax
|
|
----------
|
|
The CLI shall have a well-defined and unambiguous grammar.
|
|
|
|
timew
|
|
timew start|stop [<tagset>]
|
|
timew track <interval> [<tagset>]
|
|
| timew clear <tagset>|<interval>
|
|
timew continue
|
|
|
|
timew [report] <report> [<filter>]
|
|
|
|
timew config [<name> [<value>]]
|
|
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 contain 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
|
|
:color Force use of color on
|
|
:nocolor Force use of color off
|
|
|
|
It is not an error to specify extra hints, because they will be simply ignored.
|
|
Unrecognized hints yiled warnings.
|
|
|
|
|
|
--- Raw Notes ---
|
|
|
|
- 'timew import <file>' will merge data.
|
|
|
|
- A command for a daily and weekly view of exclusions is needed. To verify that
|
|
they are correctly defined. A text-based list should accompany it.
|
|
|