DOKK / manpages / debian 10 / timewarrior / timew.1.en
timew(1) User Manuals timew(1)

timew - A command line time tracker.

timew <command> [<arg> ...]

Timewarrior is a command line time tracker. It allows you to easily track your time and generate summary reports.

This is a reference, not a tutorial. If you are looking for a tutorial, check the online documentation here:


https://taskwarrior.org/docs/timewarrior

Timewarrior supports many commands. Alphabetically:


When run without arguments, the default command is run, which indicates whether there is any active tracking, and if so, shows a summary, then exits with a code 0. If there is no active time tracking, exit code is 1. See also 'get'.

timew cancel
If there is an open interval, it is abandoned. See also 'stop'.

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, which means you intend to answer 'yes' to the confirmation questions:


$ timew config verbose '' :yes

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


$ timew config
verbose = yes
...

See also 'hints', 'show'.

timew continue
Resumes tracking of closed intervals. For example:


$ timew track 9am - 10am tag1 tag2
$ timew track 11am - 1pm tag3
$ timew continue @2

The 'continue' command creates a new interval, starting now, and using the tags 'tag1' and 'tag2'. Using the 'summary' command and specifying the ':ids' hint shows interval IDs. This command is a convenient way to resume work without re-entering the tags.

See also 'start', 'stop'.

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.

Charts accept 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. This can be used to see the exclusions.

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

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

timew delete @<id> [@<id> ...]
Deletes an interval. Using the 'summary' command, and specifying the ':ids' hint shows interval IDs. Using the right ID, you can identify an interval to delete. For example, show the IDs:


$ timew summary :week :ids

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


$ timew delete @2

See also 'cancel'.

timew diagnostics
This command shows details about your version of Timewarrior, your 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'.

timew export [<interval>] [<tag> ...]
Exports all the tracked time in JSON format. Supports filtering. For example:


$ timew export from 2016-01-01 for 3wks tag1

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

timew fill @<id> [@<id> ...]

The 'fill' command is used to adjust any interval to fill in surrounding gaps. Using the 'summary' command, and specifying the ':ids' hint shows interval IDs. Using the right ID, you can identify an interval to fill. For example, show the IDs:


$ timew summary :week :ids

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


$ timew fill @2

Note that you can fill multiple intervals:


$ timew fill @2 @10 @23

See also 'hints'.

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'.

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

See also 'summary'.

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


$ timew get dom.active
1

It is an error to reference an interval or tag that does not exist. See also 'DOM'.

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 and DOM references. For example:


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

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', 'resize'.

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', 'resize'.

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'.

timew move @<id> <date>
The 'move' command is used to reposition an interval at 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', 'resize'.

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.

timew resize @<id> [@<id> ...] <duration>
The 'resize' command is used to change the duration 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 resize. For example, show the IDs:


$ timew summary :week :ids

Then having selected '@3' as the interval you wish to resize:


$ timew resize @3 15mins

Note that you can resize multiple intervals,:


$ timew resize @3 @1 @13 1hour

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

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', 'resize'.

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

timew split @<id> [@<id> ...]
Ѕplits an interval into two equally sized adjacent intervals, having 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 'join', 'lengthen', 'shorten'.

timew start [<date>] [<tag> ...]
Begins tracking using the current time with any specified set of tags. If a tag contains multiple words, therefore containing 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'.

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'.

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 'ID' column to the summary report output for interval modification.

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

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'.

timew tags [<interval>] [<tag> ...]
Displays all the tags that have been used by default. When a filter is specified, shows only the tags that were used during that time.

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.

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'.

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'.

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.

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
:monday Previous monday
:tuesday Previous tuesday
:wednesday Previous wednesday
:thursday Previous thursday
:friday Previous friday
:saturday Previous saturday
:sunday Previous sunday

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
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)
sopd, eopd Start/end of previous day
sod, eod Start/end of current day
sond, eond Start/end of next day
sopw, eopw Start/end of previous week
sow, eow Start/end of current week
sonw, eonw Start/end of next week
sopww, eopww Start/end of previous work week (mon - fri)
soww, eoww Start/end of current work week (mon - fri)
sonww, eonww Start/end of next work week (mon - fri)
sopm, eopm Start/end of previous month
som, eom Start/end of current month
sonm, eonm Start/end of next month
sopq, eopq Start/end of previous quarter
soq, eoq Start/end of current quarter
sonq, eonq Start/end of next quarter
sopy, eopy Start/end of previous year
soy, eoy Start/end of current year
sony, eony Start/end of next year
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'.

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.

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
dom.tracked.1.duration Tracked Nth, elapsed
dom.tracked.1.json Tracked Nth, interval as JSON


dom.rc.<name> Configuration setting

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. Note that the environment variable $TIMEWARRIORDB can be set to override this location.

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 overridden 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).

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

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

The debug output prefix string. Default value is '>>'.


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, ...). The value must be greater than '0'. Default value is '15'. Type is one of 'month', 'week', 'day'.


Determines whether the current day of the month is shown at left margin. Default value is 'yes'. Type is one of 'month', 'week', 'day'.


Determines whether relevant holidays are shown beneath the report. Default value is 'yes'. Type is one of 'month', 'week', 'day', 'summary'.


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'.


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'.


Determines whether the current month is shown at left margin. Default value is 'yes'. Type is one of 'month', 'week', 'day'.


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'.


Specifies how many spaces are inserted between the hours in the <type> report exclusions. A value of '0' yields a more compact report. Default value is '1'. Type is one of 'month', 'week', 'day'.


The value 'internal' puts the hour markers inside the exclusion blocks. Default is <no value>.


Determines whether the hours summary is shown. Default value is 'on'. Type is one of 'month', 'week', 'day'.


Determines whether the time totals are shown for each day on the report. Default value is 'on'. Type is one of 'month', 'week', 'day'.


Determines whether the current week number is shown at left margin. Default value is 'yes'. Type is one of 'month', 'week', 'day'.


Determines whether the current weekday is shown at left margin. Default value is 'yes'. Type is one of 'month', 'week', 'day'.

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

For examples please see the online documentation starting at:

<http://taskwarrior.org/docs/timewarrior/>

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

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

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

Copyright (C) 2015 - 2018 P. Beckingham, F. Hernandez.

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

For more information regarding Timewarrior, see the following:

<http://taskwarrior.org>

<https://git.tasktools.org/scm/tm/timew.git>

<support@taskwarrior.org>

<https://bug.tasktools.org/>

2018-02-03 timew 1.1.1