timewarrior/doc/man/timew.1.in

.TH timew 1 2016-06-20 "${PACKAGE_STRING}" "User Manuals"

.SH NAME
timew \- A command line time tracker.

.SH SYNOPSIS
.B timew <command> [<arg> ...]

.SH DESCRIPTION
Timewarrior is a command line time tracker. It allows you to very easily track
your time spent on projects, and generate summary reports.

.SH SUBCOMMANDS

Timewarrior supports many commands. Alphabetically:

.TP
.B timew
.br
When run with no arguments, the default command is run, which indicates whether
there is any active tracking, and if so, shows a summary, and exits with a code
0. If there is no active time tracking, exit code is 1.

.TP
.B timew cancel
If there is an open interval, closes and abandons it.
See also 'stop'.

.TP
.B timew config [<name> [<value> | '']]
Allows setting and removing configuration values, as an alternative to directly
editing your ~/.timewarrior/timewarrior.cfg file. For example:

  $ timew config verbose yes
  $ timew config verbose ''
  $ timew config verbose

The first command sets 'verbose' to 'yes'. The second sets it to a blank value
which overrides the default value. The third example deletes the 'verbose'
setting.

When modifying configuration in this way, interactive confirmation will be
sought. To override this confirmation, use the ':yes' hint:

  $ timew config verbose '' :yes

If no arguments are provided, all configuration settings are shown:

  $ timew config
  verbose = yes
  ...

See also 'hints', 'show'.

.TP
.B timew continue
Resumes tracking the most recently closed interval. For example:

  $ timew track yesterday 9am - 5pm tag1 tag2
  $ timew continue

The 'continue' command creates a new interval, starting now, and using the
tags 'tag1' and 'tag2'. See also 'start', 'stop'.

.TP
.B timew day [<interval>] [<tag> ...]
The day command shows a chart depicting a single day (today by default), with
colored blocks drawn on a timeline. The chart summarizes the tracked and
untracked time.

Accepts date ranges and tags for filtering, or shortcut hints:

  $ timew day monday - today
  $ timew day :week
  $ timew day :month

The 'reports.day.range' configuration setting overrides the default date range.
The default date range shown is ':day'.

The ':blank' hint causes only the excluded time to be shown, with no tracked
time.

For more details, and precise times, use the 'summary' report.

See also 'week', 'month', 'summary'.

.TP
.B timew diagnostics
This command shows details about your version of Timewarrior, platform, how it
was built, compiler features, configuration, file access, extensions and more.
The purpose of this command is to help diagnose configuration problems, and
provide supplemental information when reporting a problem. See also 'extensions'.

.TP
.B timew export [<interval>] [<tag> ...]
Exports all the tracked time in JSON format. See also 'import'.

.TP
.B timew extensions
Displays the directory containing the extension programs, and a table showing
each extention and its status. See also 'diagnostics'.

.TP
.B timew gaps [<interval>] [<tag> ...]
Displays a summary of time that is neither tracked, nor excluded from tracking.

The 'reports.gaps.range' configuration setting overrides the default date range.
The ':blank' hint causes only the excluded time to be shown, with no tracked
time.
The default date range shown is ':day'.

See also 'summary'.

.TP
.B timew get <DOM> [<DOM> ...]
Validates the DOM reference, then obtains the value and displays it. For example

  $ timew get dom.active
  1

See also 'DOM'.

.TP
.B timew help [<command> | interval | hints | date | duration]
The help command shows detailed descriptions and examples of commands,
interval syntax, supported hints, date and duration formats. For example:

  $ timew help
  $ timew help start
  $ timew help hints
  $ timew help interval
  $ timew help date
  $ timew help duration

.TP
.B timew join @<id> @<id>
Joins two intervals, by using the earlier of the two start times, and the later
of the two end times, and the combined set of tags. Using the 'summary' command,
and specifying the ':ids' hint shows interval IDs. Using the correct IDs, you
can identify an intervals to join. For example, show the IDs:

  $ timew summary :week :ids

Then having selected '@1' and '@2' as the intervals you wish to join:

  $ timew join @1 @2

See also 'split', 'lengthen', 'shorten'.

.TP
.B timew lengthen @<id> [@<id> ...] <duration>
The 'lengthen' command is used to defer the end date of a closed interval.
Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
Using the right ID, you can identify an interval to lengthen. For example, show
the IDs:

  $ timew summary :week :ids

Then having selected '@2' as the interval you wish to lengthen:

  $ timew lengthen @2 10mins

Note that you can lengthen multiple intervals,:

  $ timew lengthen @2 @10 @23 1hour

See also 'summary', 'tag', 'untag', 'shorten'.

.TP
.B timew month [<interval>] [<tag> ...]
The month command shows a chart depicting a single month (current month by
default), with colored blocks drawn on a timeline. The chart summarizes the
tracked and untracked time.

Accepts date ranges and tags for filtering, or shortcut hints:

  $ timew month 1st - today
  $ timew month :week

The 'reports.month.range' configuration setting overrides the default date range.
The default date range shown is ':month'.

The ':blank' hint causes only the excluded time to be shown, with no tracked
time.

For more details, and precise times, use the 'summary' report.

See also 'day', 'week', 'summary'.

.TP
.B timew move @<id> <date>
The 'move' command is used to relocate an interval intact to a new start time.
Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
Using the right ID, you can identify an interval to move. For example, show
the IDs:

  $ timew summary :week :ids

Then having selected '@2' as the interval you wish to move:

  $ timew move @2 9am

See also 'summary', 'tag', 'untag', 'lengthen', 'shorten'.

.TP
.B timew [report] <report> [<interval>] [<tag> ...]
Runs an extension report, and supports filtering data.
The 'report' command itself is optional, which means that these two commands
are equivalent:

  $ timew report foo :week
  $ timew        foo :week

This does however assume there is a 'foo' extension installed.

.TP
.B timew shorten @<id> [@<id> ...] <duration>
The 'shorten' command is used to advance the end date of a closed interval.
Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
Using the right ID, you can identify an interval to shorten. For example, show
the IDs:

  $ timew summary :week :ids

Then having selected '@2' as the interval you wish to shorten:

  $ timew shorten @2 10mins

Note that you can shorten multiple intervals,:

  $ timew shorten @2 @10 @23 1hour

See also 'summary', 'tag', 'untag', 'lengthen'.

.TP
.B timew show
Displays the effective configuration, in hierarchical form.
See also 'config'.

.TP
.B timew split @<id> [@<id> ...]
Ѕplits an interval into two equally sized, adjacent intervals, with the same
tags. Using the 'summary' command, and specifying the ':ids' hint shows interval
 IDs. Using the right ID, you can identify an interval to split. For example,
show the IDs:

  $ timew summary :week :ids

Then having selected '@2' as the interval you wish to split:

  $ timew split @2

See also 'lengthen', 'shorten'.

.TP
.B timew start [<date>] [<tag> ...]
Begins tracking using the current time, and the specified optional set of tags.
If a tag contains multiple words, and therefore contains spaces, use quotes to
surround the whole tag. For example, this command specifies two tags ('weekend'
and 'Home & Garden'), the second of which requires quotes.

  $ timew start weekend 'Home & Garden'

An optional date may be specified to indicate the intended start of the tracked
time:

  $ timew start 8am weekend 'Home & Garden'

If there is a previous open interval, it will be closed at the given start
time.

Quotes are harmless if used unnecessarily. See also 'continue', 'stop', 'track'.

.TP
.B timew stop [<tag> ...]
Stops tracking time. If tags are specified, then they are no longer tracked.
If no tags are specified, all tracking stops. For example:

  $ timew start tag1 tag2
  ...
  $ timew stop tag1

Initially time is tracked for both 'tag1' and 'tag2', then 'tag1' tracking is
stopped, leaving tag2 active. To stop all tracking:

  $ timew stop

See also 'cancel', 'continue', 'start', 'track'.

.TP
.B timew summary [<interval>] [<tag> ...]
Displays a report summarizing tracked and untracked time for
the current day by default. Accepts date ranges and tags for
filtering, or shortcut hints:

  $ timew summary monday - today
  $ timew summary :week
  $ timew summary :month

The ':ids' hint adds an 'IDS' column to the summary report output, for interval
modification.

See also 'day', 'week', 'month', 'shorten', 'lengthen', 'tag', 'untag'.

.TP
.B timew tag @<id> [@<id> ...] <tag> [<tag> ...]
The 'tag' command is used to add a tag to an interval. Using the 'summary'
command, and specifying the ':ids' hint shows interval IDs. Using the right ID,
you can identify an interval to tag. For example, show the IDs:

  $ timew summary :week :ids

Then having selected '@2' as the interval you wish to tag:

  $ timew tag @2 'New Tag'

Note that you can tag multiple intervals, with multiple tags:

  $ timew tag @2 @10 @23 'Tag One' tag2 tag3

See also 'summary', 'shorten', 'lengthen', 'untag'.

.TP
.B timew tags
Displays all the tags that have been used.

.TP
.B timew track <interval> [<tag> ...]
The track command is used to add tracked time in the past. Perhaps you forgot
to record time, or are just filling in old entries. For example:

  $ timew track :yesterday 'Training Course'
  $ timew track 9am - 11am 'Staff Meeting'

Note that the track command expects a closed interval (start and end time), when
recording. If a closed interval is not provided, the 'track' command behaves the
same as the 'start' command.

.TP
.B timew untag @<id> [@<id> ...] <tag> [<tag> ...]
The 'untag' command is used to remove a tag from an interval. Using the 'summary'
command, and specifying the ':ids' hint shows interval IDs. Using the right ID,
you can identify an interval to untag. For example, show the IDs:

  $ timew summary :week :ids

Then having selected '@2' as the interval you wish to untag:

  $ timew untag @2 'Old Tag'

Note that you can untag multiple intervals, with multiple tags:

  $ timew untag @2 @10 @23 'Old Tag' tag2 tag3

See also 'summary', 'shorten', 'lengthen', 'tag'.

.TP
.B timew week [<interval>] [<tag> ...]
The week command shows a chart depicting a single week (current week by
default), with colored blocks drawn on a timeline. The chart summarizes the
tracked and untracked time.

Accepts date ranges and tags for filtering, or shortcut hints:

  $ timew week
  $ timew week monday - today

The 'reports.week.range' configuration setting overrides the default date range.
The default date range shown is ':week'.

The ':blank' hint causes only the excluded time to be shown, with no tracked
time.

For more details, and precise times, use the 'summary' report.

See also 'day', 'month', 'summary'.

.SH INTERVAL
An interval defines a block of time that is tracked. The syntax for specifying
an interval is flexible, and may be one of:

  [from] <date>
  [from] <date> to/- <date>
  [from] <date> for <duration>
  <duration> before/after <date>
  <duration> ago
  [for] <duration>

Examples are:

  from 9:00
  from 9am - 11am
  from 9:00:00 to 11:00
  from 9:00 for 2h
  2h after 9am
  2h before 11:00
  2h ago
  for 2h

An interval is said to be 'closed' if there is both a start and end, and 'open'
if there is no end date.

.SH HINTS
Timewarrior supports hints, which are single-word command line features that
start with a colon like this:

  :week

Hints serve several purposes. This example is a shortcut for the date range
that defines the current week. Other hints, such as:

  :quiet

Are ways to control the behavior of Timewarrior, in this case eliminating all
forms of feedback, for purposes of automation. The supported hints are:

  :quiet         Turns off all feedback. For automation
  :debug         Runs in debug mode, shows many runtime details
  :yes           Overrides confirmation by answering 'yes' to the questions

  :color         Force color on, even if not connected to a TTY
  :nocolor       Force color off, even if connected to a TTY
  :blank         Leaves tracked time out of a report
  :fill          Expand time to fill surrounding available gap
  :adjust        Automatically correct overlaps
  :ids           Displays interval ID numbers in the summary report

Range hints provide convenient shortcuts to date ranges:

  :yesterday     The 24 hours of the previous day
  :day           The 24 hours of the current day
  :week          This week
  :month         This month
  :quarter       This quarter
  :year          This year
  :lastweek      Last week
  :lastmonth     Last month
  :lastquarter   Last quarter
  :lastyear      Last year

.SH DATES
Timewarrior supports the following date formats based on ISO-8601:

  <extended-date> [T <extended-time>]   Extended date, optional extended time
  <date> [T <time>]                     Date, optional time
  <extended-time>                       Extended time
  <time>                                Time

  extended-date:
    YYYY-MM-DD                          Year, month, day
    YYYY-MM                             Year, month, 1st
    YYYY-DDD                            Year, Julian day 001-366
    YYYY-WwwD                           Year, week number, day number
    YYYY-Www                            Year, week number, day 1

  extended-time:
    hh:mm[:ss]Z                         Hours, minutes, optional seconds, UTC
    hh:mm[:ss][+/-hh:mm]                Hours, minutes, optional seconds, TZ

  date:
    YYYYMMDD                            Year, month, day
    YYYYWww                             Year, week number, day number
    YYYYDDD                             Year, Julian day 001-366

  time:
    hhmm[ss]Z                           Hour, minutes, optional seconds, UTC
    hhmm[ss][+/-hh[mm]]                 Hour, minutes, optional seconds, TZ

Examples:
  2016-06-09T08:12:00Z
  2016-06T08:12:00+01:00
  2016-06T08:12Z
  2016-161
  2016-W244
  2016-W24
  20160609T081200Z
  2016W24
  8:12:00Z
  0812-0500

In addition to the standard date formats, the following are supported:

  now                                   Current date and time
  today                                 Current date at 0:00:00
  sod, eod                              Current date at 0:00:00 and 23:59:59
  yesterday                             Yesterday at 0:00:00
  tomorrow                              Tomorrow at 0:00:00 (midnight tonight)
  <day-of-week>                         Previous named day at 0:00:00
  <month-of-year>                       Previous 1st of the  month at 0:00:00
  hh:mm[:ss][am|a|pm|p]                 Short time format
  Nst, Nnd, Nrd, Nth                    Previous 1st, 2nd, 3rd ...
  <epoch>                               POSIX time
  later                                 2038-01-18T0:00:00 (Y2K38)
  someday                               2038-01-18T0:00:00 (Y2K38)
  soy, eoy                              Previous start/end of year
  socy, eocy                            Start/end of current year
  soq, eoq                              Previous start/end of quarter
  socq, eocq                            Start/end of current quarter
  som, eom                              Previous start/end of month
  socm, eocm                            Start/end of current month
  sow, eow                              Previous start/end of week
  socw, eocw                            Start/end of current week
  soww, eoww                            Start/end of current work week (mon - fri)
  easter                                Easter Sunday
  eastermonday                          Easter Monday
  ascension                             Ascension
  pentecost                             Pentecost
  goodfriday                            Good Friday
  midsommar                             midnight, 1st Saturday after 20th June
  midsommarafton                        midnight, 1st Friday after 19th June
  juhannus                              midnight, 1st Friday after 19th June

Examples:
  8am
  24th
  monday
  august

See also 'duration', 'hints'.

.SH DURATIONS
Timewarrior supports the following duration formats based on ISO-8601:

  'P' [nn 'Y'] [nn 'M'] [nn 'D'] ['T' [nn 'H'] [nn 'M'] [nn 'S']]
  PnnW

Examples:
  P1Y           1 year
  P1.5M         1.5 months
  PT1S          1 second
  PT4.5H        4.5 hours
  PT4H30M       4.5 hours
  P600D         600 days
  P3W           3 weeks
  P1Y1DT1H1M1S  1 year and 25 hours, 61 seconds (imprecise term)

  Note that the year and month terms are imprecise, being defined as 365d and
  30d respectively. For precision use the other terms.

In addition to the standard duration formats, the following are supported:

  n[.n]<unit>

Where the <unit> is one of:

  annual
  biannual
  bimonthly
  biweekly
  biyearly
  daily
  days, day, d
  fortnight
  hours, hour, hrs, hr, h
  minutes, minute, mins, min
  monthly, months, month, mnths, mths, mth, mos, mo, m
  quarterly, quarters, quarter, qrtrs, qtr, q
  semiannual
  sennight
  seconds, second, secs, sec, s
  weekdays
  weekly, weeks, week, wks, wk, w
  yearly, years, year, yrs, yr, y

Examples:
  1hour         60 minutes
  1.5h          90 minutes
  3mo           3 months
  10d           10 days

  Note that the year, quarter and month terms are imprecise, being defined as
  365d, 91d and 30d respectively. For precision use the other terms.

.SH DOM
Supported DOM references are:

  dom.tag.count             Count of all tags
  dom.tag.1                 Nth tag used

  dom.active                '1' if there is active tracking, otherwise '0'
  dom.active.tag.count      Count of active tags
  dom.active.tag.1          Active Nth tag
  dom.active.start          Active start timestamp (ISO Extended local date)
  dom.active.duration       Active elapsed (ISO Period)
  dom.active.json           Active interval as JSON

  dom.tracked.count         Count of tracked intervals
  dom.tracked.1.tag.count   Count of active tags
  dom.tracked.1.tag.1       Tracked Nth, Nth tag
  dom.tracked.1.start       Tracked Nth, start time
  dom.tracked.1.end         Tracked Nth, end time, blank if closed

.SH CONFIGURATION FILE AND OVERRIDE OPTIONS
Timewarrior stores its configuration in a file in the user's home directory:
~/.timewarrior/timewarrior.cfg.

This file contains a mix of rules and configuration settings.

The values 'true', '1', 'y', 'yes' and 'on' are all equivalent and enable a
setting. Any other value means disable the setting.

Default values may be overridden by timewarrior.cfg values, which may in turn be
overriden on the command line using:

  rc.<name>=<value>

For example, to turn off verbose mode:

  rc.verbose=0

Note that hints can also do this (:quiet).

.TP
.B confirmation = yes
Determines whether harmful operations require interactive confirmation.
May be overridden by the ':yes' hint.
Default value is 'yes'.

.TP
.B debug = off
Determines whether diagnostic debugging information is shown.
Useful for troubleshooting, but not for general use.
Default value is 'off'.

.TP
.B debug.indicator = >>
The debug output prefix string.
Default value is '>>'.

.TP
.B reports.<type>.cell = 15
.br
Determines how many minutes are represented by a single character cell, for the
charts.
A value of '15' means that an hour is represented by 60/15, or 4 character cells.
Suitable values are the divisors of 60 (30, 20, 15, 12, ...).
Default value is '15'.
Type is one of 'month', 'week', 'day'.

.TP
.B reports.<type>.day = yes
.br
Determines whether the current day of the month is shown at left margin.
Default value is 'yes'.
Type is one of 'month', 'week', 'day'.

.TP
.B reports.<type>.holidays = yes
.br
Determines whether relevant holidays are shown beneath the report.
Default value is 'yes'.
Type is one of 'month', 'week', 'day', 'summary'.

.TP
.B reports.<type>.hours = all
.br
Determines how the <type> report shows all the hours in a day ('all'), or is
limited to only hours where data is tracked ('auto'). Default value is 'all'.
Type is one of 'month', 'week', 'day'.

.TP
.B reports.<type>.lines = 1
.br
Determines how many lines are used to render each day on the <type> report.
Default value is '1'.
Type is one of 'month', 'week', 'day'.

.TP
.B reports.<type>.month = yes
.br
Determines whether the current month is shown at left margin.
Default value is 'yes'.
Type is one of 'month', 'week', 'day'.

.TP
.B reports.<type>.range = <range hint>
.br
For reports that show a range of data, this setting will override the default
value. The value should be a range hint, see 'hints'
Type is one of 'gaps', 'day', 'week', 'month'.

.TP
.B reports.<type>.spacing = 1
.br
Specifies how many spaces are inserted between the hours in the <type> report
exclusions. A value of '0' give a move compact report. Default value is '1'.
Type is one of 'month', 'week', 'day'.

.TP
.B reports.<type>.style = compact
.br
The 'compact' style puts the hour markers inside the exclusion blocks.
Type is one of 'month', 'week', 'day'.

.TP
.B reports.<type>.summary = on
.br
Determines whether the hours summary is shown. Default value is 'on'.
Type is one of 'month', 'week', 'day'.

.TP
.B reports.<type>.totals = on
.br
Determines whether the time totals are shown for each day on the report.
Default value is 'on'.
Type is one of 'month', 'week', 'day'.

.TP
.B reports.<type>.week = yes
.br
Determines whether the current week number is shown at left margin.
Default value is 'yes'.
Type is one of 'month', 'week', 'day'.

.TP
.B reports.<type>.weekday = yes
.br
Determines whether the current weekday is shown at left margin.
Default value is 'yes'.
Type is one of 'month', 'week', 'day'.

.TP
.B verbose = yes
Determines whether Timewarrior generates feedback.
May be overridden by the ':quiet' hint.
Default value is 'yes'.

.SH MORE EXAMPLES

For examples please see the online documentation starting at:

.RS
<http://taskwarrior.org/???>
.RE

Note that the online documentation can be more detailed and more current than
this man page.

.SH FILES

.TP
~/.timewarrior/timewarrior.cfg
User configuration file.

.TP
~/.timewarrior/data/YYYY-MM.data
Time tracking data files.

.SH "CREDITS & COPYRIGHTS"
Copyright (C) 2015 \- 2016 P. Beckingham, F. Hernandez.

Timewarrior is distributed under the MIT license. See
http://www.opensource.org/licenses/mit-license.php for more information.

.SH SEE ALSO
For more information regarding Timewarrior, see the following:

.TP
The official site at
<http://taskwarrior.org>

.TP
The official code repository at
<https://git.tasktools.org/scm/tm/timew.git>

.TP
You can contact the project by emailing
<support@taskwarrior.org>

.SH REPORTING BUGS
.TP
Bugs in Timewarrior may be reported to the issue-tracker at
<https://bug.tasktools.org/>