GothenburgBitFactory/timewarrior
1
0
Fork 0
mirror of https://github.com/GothenburgBitFactory/timewarrior.git synced 2025-06-26 10:54:28 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
timewarrior/doc/rfc_command_definition.md
Thomas Lauf f0a6fd1ec3 doc: Update command definition document 
- add `now` as example for a date
- reformat: One line per sentence (more or less)
- refine behaviour of command `stop` in case of active time tracking
- add definition for command `annotate`
2017-05-03 20:23:47 +02:00

6.8 KiB
Raw Blame History

RFC: TimeWarrior command definition

TimeWarrior can be used like this:

timew [--version | --help | <command> [<args>]]

Arguments

  • command is one of the commands listed below.
  • args is an optional list of command arguments.

Behavior

  • timew prints the current time tracking status and exits.
  • timew --version prints version information and exits.
  • timew --help prints general help, references other help, and exits. timew --help is converted internally to timew help.
  • timew <command> [<args>] calls the specified command with the given arguments args.

Command line elements

A basic view on the command line:

timew <words>

Word

A word is the basic element of the command line. Words are separated by whitespace (except when quoted).

Command

A command is first element on the command line. The CLI identifies the command, and categorizes all words. further interpretation of those words is delegated to teh command. The commands parse the command arguments to execute their functionality.

Subcommand

Analog to commands, subcommands are the first element of the command arguments. Subcommands are used to specify command behavior. For example

timew tag list
timew tag remove @3 foo bar

(PB: Probably need better examples)

Date

A date specifies a certain point in time. Examples are

  • 1pm
  • 10:33
  • 2017-04-11T17:12:23
  • now
  • ...

Duration

A duration can be specified by

  • one day, two weeks
  • today, yesterday
  • ...

Range

A range is a time interval. It can be specified as the difference between two dates or as a combination of a date and a duration. E.g.

  • 09:45 - 11:15
  • two hours before 10:45 which means 8:45 - 10:45
  • 30mins until 2017-03-23T13:13 which means 2017-03-23T12:43 - 2017-03-23T13:13
  • one hour ago which means -1hr - now

Tag

A tag is a lexical token that is at least one non-whitespace character, and could be a quoted phrase. It is treated as one word. It is used to label an interval.

Filter

Commands can use filters to limit the list of intervals they operate on. Filters can be

  • tags
  • ranges

Hints

Hints are words that begin wіth the : character, for example :quiet. A hint is a request that behavior be modified in a specific way. The example of the :quiet hint requests that no extraneous output is generated, making the command more useful for scripting.

There is a supported set of hints (timew help hints), and commands will respond to hints that make sense in context, and ignore those that do not.

It is not an error to specify unrelated (but supported) hints. Commands may implicitly behave as though a hint were specified. For this reason hints are so named, they are not necessarily obeyed, not necessarily relevant.

Commands

Sorting the command line zoo.

Basic commands

Basic commands provide the minimal TimewWarrior functionality. All arguments are optional.

  • start
  • stop
  • cancel

Modifying commands

These commands modify existing intervals. They require an id to know on which interval(s) to operate on.

  • tag
  • delete
  • shorten/lengthen/resize
  • move
  • fill
  • split
  • join

Listing commands

Listing and reporting on the database...

  • export
  • summary
  • chart (day, week, month)
  • gaps
  • tags
  • report

Shortcut commands

Shortcut commands combine functionality of basic commands.

  • track (combines start & stop)
  • continue (combines tags & start)

Administrative commands

These are not typical user-level commands, but provide support and diagnostic features.

  • help
  • show
  • config
  • get
  • diagnostics
  • extensions

Command definitions

Command start

Synopsis

timew start [<date>] [<tags>]

Arguments

  • date is an optional argument. If no date is given, the current date is used.
  • tags is an optional list of one or more tags.

Behavior

  • If there is no active time tracking, start creates a new open interval at the given date and with the given tags.
  • In case of active time tracking, start closes the current open interval at the given date and creates a new open interval only if the given tag list differs from the tag list of the current open interval.

Command stop

Synopsis

timew stop [<date>] [<tags>]

Arguments

  • date is an optional argument. If no date is given, the current date is used.
  • tags is an optional list of one or more tags.

Behavior

  • If there is no active time tracking stop has no effect.
  • In case of active time tracking, stop closes the current open interval at the specified date.
  • If a tag list is given, a new open interval is created with all tags which are part of the current interval's tag list but not part of the given tag list. Tags which are part of the given tag list but not part of the current interval's tag list are ignored.

Synopsis

Command cancel

timew cancel

Arguments

  • cancel has no arguments.

Behavior

  • If there is no active time tracking cancel has no effect.
  • In case of active time tracking, cancel deletes the current open interval.

Command track

Synopsis

timew track <range> [<tags>]

Arguments

  • range is a date range: <start-date> - <stop-date>.
  • tags is an optional list of one or more tags.

Behavior

timew track <start-date> - <stop-date> <tags> acts as a shortcut for

timew start <start-date> <tags>
timew stop <stop-date>

and thus behaves the same way.

Command continue

Synopsis

timew continue [<id>]

Arguments

  • id is an optional argument. If no id is given, @1 is used.

Behavior

timew continue <id> acts as a shortcut for

timew start <tag-list-of-interval-with-given-id>

and thus behaves the same way.

Command tag

Synopsis

timew tag [remove] [<id>] <tags>
timew tag list [<ids>]

Arguments

  • remove is an optional subcommand. If given, the specified tags are removed and not added.
  • id is an optional argument. If no id is given, @1 is used.
  • tags is a list of one or more tags.
  • list is an optional subcommand.
  • ids is an optional list of one or more ids.

Behavior

  • Tags which are not in the tag list of the specified interval are ignored.
  • If no id is given, tag list lists all available tags.

Command annotate

Synopsis

timew annotate [<id>] [:append] <annotation>

Arguments

  • id is an optional argument. If no id is given, @1 is used.
  • annotation is everything after the id.

Behavior

This command can be used to add additional information to intervals.

  • There can be only one or no annotation for an interval.
  • A new annotation overwrites an existing one unless the :append hint was given.
  • To delete an annotation overwrite it with an empty string.
  • Annotations can be displayed using the summary command.