mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-06-26 10:54:28 +02:00
588 lines
No EOL
16 KiB
Groff
588 lines
No EOL
16 KiB
Groff
.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> |