.TH timew 1 2018-02-03 "${PACKAGE_STRING}" "User Manuals"
.
.SH NAME
timew \- A command line time tracker.
.
.SH SYNOPSIS
.BR "timew " [ --version | --help ]
.br
.B timew
.RI [ "<command> " [ <arg> "...]]"
.
.SH DESCRIPTION
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:
.br
  https://taskwarrior.org/docs/timewarrior
.br
When run without arguments or options, 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.
.
.SH OPTIONS
.TP
.B \-\-version
.RS
Displays TimeWarrior version information
.RE
.TP
.B \-\-help
.RS
Display TimeWarrior usage information
.RE
.
.SH "TIMEWARRIOR COMMANDS"
Timewarrior supports many commands.
Alphabetically:
.
.TP
.BR timew-cancel (1)
.RS
Cancel time tracking
.RE
.TP
.BR timew-config (1)
.RS
Get and set Timewarrior configuration
.RE
.TP
.BR timew-continue (1)
.RS
Resume tracking of existing interval
.RE
.TP
.BR timew-day (1)
.RS
Display day chart
.RE
.TP
.BR timew-delete (1)
.RS
Delete intervals
.RE
.TP
.BR timew-diagnostics (1)
.RS
Show diagnostic information
.RE
.TP
.BR timew-export (1)
.RS
Export tracked time in JSON
.RE
.TP
.BR timew-extensions (1)
.RS
List available extensions
.RE
.TP
.BR timew-get (1)
.RS
Display DOM values
.RE
.TP
.BR timew-help (1)
.RS
Display help
.RE
.TP
.BR timew-join (1)
.RS
Join intervals
.RE
.TP
.BR timew-lengthen (1)
.RS
Lengthen intervals
.RE
.TP
.BR timew-month (1)
.RS
Display month chart
.RE
.TP
.BR timew-move (1)
.RS
Change interval start-time
.RE
.TP
.BR timew-report (1)
.RS
Run an extension report
.RE
.TP
.BR timew-resize (1)
.RS
Set interval duration
.RE
.TP
.BR timew-shorten (1)
.RS
Shorten intervals
.RE
.TP
.BR timew-show (1)
.RS
Display configuration
.RE
.TP
.BR timew-split (1)
.RS
Split intervals
.RE
.TP
.BR timew-start (1)
.RS
Start time tracking
.RE
.TP
.BR timew-stop (1)
.RS
Stop time tracking
.RE
.TP
.BR timew-summary (1)
.RS
Display a time-tracking summary
.RE
.TP
.BR timew-tag (1)
.RS
Add tags to intervals
.RE
.TP
.BR timew-tags (1)
.RS
Display a list of tags
.RE
.TP
.BR timew-track (1)
.RS
Add intervals to the database
.RE
.TP
.BR timew-untag (1)
.RS
Remove tags from intervals
.RE
.TP
.BR timew-week (1)
.RS
Display week chart
.RE
.
.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>
.br
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
.br
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
.br
Hints serve several purposes.
This example is a shortcut for the date range that defines the current week.
.br
Other hints, such as:
.
  :quiet
.br
Are ways to control the behavior of Timewarrior, in this case eliminating all forms of feedback, for purposes of automation.
.br
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
.br
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
.
.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
.br
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
.br
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
.br
Examples:
  8am
  24th
  monday
  august
.br
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
.br
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)
.br
Note that the year and month terms are imprecise, being defined as 365d and 30d respectively.
For precision use the other terms.
.br
In addition to the standard duration formats, the following are supported:
.
  n[.n]<unit>
.br
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
.br
Examples:
  1hour         60 minutes
  1.5h          90 minutes
  3mo           3 months
  10d           10 days
.br
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
  dom.tracked.1.duration    Tracked Nth, elapsed
  dom.tracked.1.json        Tracked Nth, interval as JSON
.
  dom.rc.<name>             Configuration setting
.
.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.
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).
.
.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, ...).
The value must be greater than '0'.
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' yields a more compact report.
Default value is '1'.
Type is one of 'month', 'week', 'day'.
.
.TP
.B reports.<type>.axis = external
.br
The value 'internal' puts the hour markers (time line at the top) inside the exclusion blocks, 'external' puts the hour markers in a separate line; additional values might be defined in the future.
Default is 'internal' for the day report and 'external' for other reports.
.
.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
<https://taskwarrior.org/docs/timewarrior/>
.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 \- 2018 T. Lauf, P. Beckingham, F. Hernandez.
.br
Timewarrior is distributed under the MIT license.
See https://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 <https://timewarrior.net>
.
.TP
The official code repository at <https://github.com/GothenburgBitFactory/timewarrior>
.
.TP
You can contact the project by emailing <support@gothenburgbitfactory.org>
.
.SH REPORTING BUGS
.TP
Bugs in Timewarrior may be reported to the issue-tracker at <https://github.com/GothenburgBitFactory/timewarrior/issues>