mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-06-26 10:54:28 +02:00
329 lines
8.9 KiB
Groff
329 lines
8.9 KiB
Groff
.TH timew 1 2015-11-29 "${PACKAGE_STRING}" "User Manuals"
|
|
|
|
.SH NAME
|
|
timew \- A command line time tracker.
|
|
|
|
.SH SYNOPSIS
|
|
.B timew <command>
|
|
|
|
.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.
|
|
|
|
.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
|
|
$ timew config verbose ''
|
|
$ 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 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.
|
|
See also 'summary'.
|
|
|
|
.TP
|
|
.B timew help [<command> | hints | interval]
|
|
The help command shows detailed descriptions and examples of commands,
|
|
supported hints and interval syntax. For example:
|
|
|
|
$ timew help
|
|
$ timew help start
|
|
$ timew help hints
|
|
$ timew help interval
|
|
|
|
.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 show
|
|
Displays the effective configuration, in hierarchical form.
|
|
See also 'config'.
|
|
|
|
.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'
|
|
|
|
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 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.
|
|
|
|
.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
|
|
|
|
: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
|
|
|
|
:fill Expand time to fill surrounding available gap
|
|
Only functions when exclusions are provided
|
|
|
|
.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.
|
|
|
|
.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 reports.day.24hours = off
|
|
.br
|
|
Determines whether the day report shows all 24 hours in a day, or is limited
|
|
to only hours where data is tracked. Default value is 'off'.
|
|
|
|
.TP
|
|
.B reports.day.spacing = 1
|
|
.br
|
|
Specifies how many spaces are inserted between the hours in the day report
|
|
exclusions. A value of '0' give a move compact report. Default value is '1'.
|
|
|
|
.TP
|
|
.B reports.day.style = compact
|
|
.br
|
|
The 'compact' style puts the hour markers inside the exclusion blocks.
|
|
|
|
.TP
|
|
.B reports.month.24hours = off
|
|
.br
|
|
Determines whether the day report shows all 24 hours in a day, or is limited
|
|
to only hours where data is tracked. Default value is 'off'.
|
|
|
|
.TP
|
|
.B reports.month.spacing = 1
|
|
.br
|
|
Specifies how many spaces are inserted between the hours in the day report
|
|
exclusions. A value of '0' give a move compact report. Default value is '1'.
|
|
|
|
.TP
|
|
.B reports.month.lines = 1
|
|
.br
|
|
Determines how many lines are used to render each day on the month report.
|
|
Default value is '1'.
|
|
|
|
.TP
|
|
.B verbose = yes
|
|
Determines whether Timewarrior generates feedbac.
|
|
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
|
|
.BR timewrc(5)
|
|
|
|
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/>
|
|
|