GothenburgBitFactory/timewarrior
1
0
Fork 0
mirror of https://github.com/GothenburgBitFactory/timewarrior.git synced 2025-07-07 20:06:39 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

One sentence, one line. Replace empty lines with null requests

Browse source
This commit is contained in:
Thomas Lauf 2018-06-29 18:53:03 +02:00
parent a03de8c348
commit 98efcef2df
1 changed files with 135 additions and 144 deletions
Download patch file Download diff file Expand all files Collapse all files

279
doc/man/timew.1.in
View file

@ -1,45 +1,45 @@
.TH timew 1 2018-02-03 "${PACKAGE_STRING}" "User Manuals" .TH timew 1 2018-02-03 "${PACKAGE_STRING}" "User Manuals"
.
.SH NAME .SH NAME
timew \- A command line time tracker. timew \- A command line time tracker.
.
.SH SYNOPSIS .SH SYNOPSIS
.B timew <command> [<arg> ...] .B timew <command> [<arg> ...]
.
.SH DESCRIPTION .SH DESCRIPTION
Timewarrior is a command line time tracker. It allows you to easily track your Timewarrior is a command line time tracker.
time and generate summary reports. 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 This is a reference, not a tutorial.
the online documentation here: If you are looking for a tutorial, check the online documentation here:
.
https://taskwarrior.org/docs/timewarrior https://taskwarrior.org/docs/timewarrior
.
.SH SUBCOMMANDS .SH SUBCOMMANDS
.
Timewarrior supports many commands. Alphabetically: Timewarrior supports many commands.
Alphabetically:
.
.TP .TP
.B timew .B timew
.br .br
When run without arguments, the default command is run, which indicates whether 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.
there is any active tracking, and if so, shows a summary, then exits with a code If there is no active time tracking, exit code is 1.
0. If there is no active time tracking, exit code is 1.
See also 'get'. See also 'get'.
.
.SH INTERVAL .SH INTERVAL
An interval defines a block of time that is tracked. The syntax for specifying An interval defines a block of time that is tracked.
an interval is flexible, and may be one of: The syntax for specifying an interval is flexible, and may be one of:
.
[from] <date> [from] <date>
[from] <date> to/- <date> [from] <date> to/- <date>
[from] <date> for <duration> [from] <date> for <duration>
<duration> before/after <date> <duration> before/after <date>
<duration> ago <duration> ago
[for] <duration> [for] <duration>
.
Examples are: Examples are:
.
from 9:00 from 9:00
from 9am - 11am from 9am - 11am
from 9:00:00 to 11:00 from 9:00:00 to 11:00
@ -48,37 +48,36 @@ Examples are:
2h before 11:00 2h before 11:00
2h ago 2h ago
for 2h for 2h
.
An interval is said to be 'closed' if there is both a start and end, and 'open' An interval is said to be 'closed' if there is both a start and end, and 'open' if there is no end date.
if there is no end date. .
.SH HINTS .SH HINTS
Timewarrior supports hints, which are single-word command line features that Timewarrior supports hints, which are single-word command line features that start with a colon like this:
start with a colon like this: .
:week :week
.
Hints serve several purposes. This example is a shortcut for the date range Hints serve several purposes.
that defines the current week. Other hints, such as: This example is a shortcut for the date range that defines the current week.
Other hints, such as:
.
:quiet :quiet
.
Are ways to control the behavior of Timewarrior, in this case eliminating all Are ways to control the behavior of Timewarrior, in this case eliminating all forms of feedback, for purposes of automation.
forms of feedback, for purposes of automation. The supported hints are: The supported hints are:
.
:quiet Turns off all feedback. For automation :quiet Turns off all feedback. For automation
:debug Runs in debug mode, shows many runtime details :debug Runs in debug mode, shows many runtime details
:yes Overrides confirmation by answering 'yes' to the questions :yes Overrides confirmation by answering 'yes' to the questions
.
:color Force color on, even if not connected to a TTY :color Force color on, even if not connected to a TTY
:nocolor Force color off, even if connected to a TTY :nocolor Force color off, even if connected to a TTY
:blank Leaves tracked time out of a report :blank Leaves tracked time out of a report
:fill Expand time to fill surrounding available gap :fill Expand time to fill surrounding available gap
:adjust Automatically correct overlaps :adjust Automatically correct overlaps
:ids Displays interval ID numbers in the summary report :ids Displays interval ID numbers in the summary report
.
Range hints provide convenient shortcuts to date ranges: Range hints provide convenient shortcuts to date ranges:
.
:yesterday The 24 hours of the previous day :yesterday The 24 hours of the previous day
:day The 24 hours of the current day :day The 24 hours of the current day
:week This week :week This week
@ -96,35 +95,35 @@ Range hints provide convenient shortcuts to date ranges:
:friday Previous friday :friday Previous friday
:saturday Previous saturday :saturday Previous saturday
:sunday Previous sunday :sunday Previous sunday
.
.SH DATES .SH DATES
Timewarrior supports the following date formats based on ISO-8601: Timewarrior supports the following date formats based on ISO-8601:
.
<extended-date> [T <extended-time>] Extended date, optional extended time <extended-date> [T <extended-time>] Extended date, optional extended time
<date> [T <time>] Date, optional time <date> [T <time>] Date, optional time
<extended-time> Extended time <extended-time> Extended time
<time> Time <time> Time
.
extended-date: extended-date:
YYYY-MM-DD Year, month, day YYYY-MM-DD Year, month, day
YYYY-MM Year, month, 1st YYYY-MM Year, month, 1st
YYYY-DDD Year, Julian day 001-366 YYYY-DDD Year, Julian day 001-366
YYYY-WwwD Year, week number, day number YYYY-WwwD Year, week number, day number
YYYY-Www Year, week number, day 1 YYYY-Www Year, week number, day 1
.
extended-time: extended-time:
hh:mm[:ss]Z Hours, minutes, optional seconds, UTC hh:mm[:ss]Z Hours, minutes, optional seconds, UTC
hh:mm[:ss][+/-hh:mm] Hours, minutes, optional seconds, TZ hh:mm[:ss][+/-hh:mm] Hours, minutes, optional seconds, TZ
.
date: date:
YYYYMMDD Year, month, day YYYYMMDD Year, month, day
YYYYWww Year, week number, day number YYYYWww Year, week number, day number
YYYYDDD Year, Julian day 001-366 YYYYDDD Year, Julian day 001-366
.
time: time:
hhmm[ss]Z Hour, minutes, optional seconds, UTC hhmm[ss]Z Hour, minutes, optional seconds, UTC
hhmm[ss][+/-hh[mm]] Hour, minutes, optional seconds, TZ hhmm[ss][+/-hh[mm]] Hour, minutes, optional seconds, TZ
.
Examples: Examples:
2016-06-09T08:12:00Z 2016-06-09T08:12:00Z
2016-06T08:12:00+01:00 2016-06T08:12:00+01:00
@ -136,9 +135,9 @@ Examples:
2016W24 2016W24
8:12:00Z 8:12:00Z
0812-0500 0812-0500
.
In addition to the standard date formats, the following are supported: In addition to the standard date formats, the following are supported:
.
now Current date and time now Current date and time
today Current date at 0:00:00 today Current date at 0:00:00
yesterday Yesterday at 0:00:00 yesterday Yesterday at 0:00:00
@ -176,21 +175,21 @@ In addition to the standard date formats, the following are supported:
midsommar midnight, 1st Saturday after 20th June midsommar midnight, 1st Saturday after 20th June
midsommarafton midnight, 1st Friday after 19th June midsommarafton midnight, 1st Friday after 19th June
juhannus midnight, 1st Friday after 19th June juhannus midnight, 1st Friday after 19th June
.
Examples: Examples:
8am 8am
24th 24th
monday monday
august august
.
See also 'duration', 'hints'. See also 'duration', 'hints'.
.
.SH DURATIONS .SH DURATIONS
Timewarrior supports the following duration formats based on ISO-8601: Timewarrior supports the following duration formats based on ISO-8601:
.
'P' [nn 'Y'] [nn 'M'] [nn 'D'] ['T' [nn 'H'] [nn 'M'] [nn 'S']] 'P' [nn 'Y'] [nn 'M'] [nn 'D'] ['T' [nn 'H'] [nn 'M'] [nn 'S']]
PnnW PnnW
.
Examples: Examples:
P1Y 1 year P1Y 1 year
P1.5M 1.5 months P1.5M 1.5 months
@ -200,16 +199,16 @@ Examples:
P600D 600 days P600D 600 days
P3W 3 weeks P3W 3 weeks
P1Y1DT1H1M1S 1 year and 25 hours, 61 seconds (imprecise term) P1Y1DT1H1M1S 1 year and 25 hours, 61 seconds (imprecise term)
.
Note that the year and month terms are imprecise, being defined as 365d and Note that the year and month terms are imprecise, being defined as 365d and 30d respectively.
30d respectively. For precision use the other terms. For precision use the other terms.
.
In addition to the standard duration formats, the following are supported: In addition to the standard duration formats, the following are supported:
.
n[.n]<unit> n[.n]<unit>
.
Where the <unit> is one of: Where the <unit> is one of:
.
annual annual
biannual biannual
bimonthly bimonthly
@ -228,29 +227,29 @@ Where the <unit> is one of:
weekdays weekdays
weekly, weeks, week, wks, wk, w weekly, weeks, week, wks, wk, w
yearly, years, year, yrs, yr, y yearly, years, year, yrs, yr, y
.
Examples: Examples:
1hour 60 minutes 1hour 60 minutes
1.5h 90 minutes 1.5h 90 minutes
3mo 3 months 3mo 3 months
10d 10 days 10d 10 days
.
Note that the year, quarter and month terms are imprecise, being defined as Note that the year, quarter and month terms are imprecise, being defined as 365d, 91d and 30d respectively.
365d, 91d and 30d respectively. For precision use the other terms. For precision use the other terms.
.
.SH DOM .SH DOM
Supported DOM references are: Supported DOM references are:
.
dom.tag.count Count of all tags dom.tag.count Count of all tags
dom.tag.1 Nth tag used dom.tag.1 Nth tag used
.
dom.active '1' if there is active tracking, otherwise '0' dom.active '1' if there is active tracking, otherwise '0'
dom.active.tag.count Count of active tags dom.active.tag.count Count of active tags
dom.active.tag.1 Active Nth tag dom.active.tag.1 Active Nth tag
dom.active.start Active start timestamp (ISO Extended local date) dom.active.start Active start timestamp (ISO Extended local date)
dom.active.duration Active elapsed (ISO Period) dom.active.duration Active elapsed (ISO Period)
dom.active.json Active interval as JSON dom.active.json Active interval as JSON
.
dom.tracked.count Count of tracked intervals dom.tracked.count Count of tracked intervals
dom.tracked.1.tag.count Count of active tags dom.tracked.1.tag.count Count of active tags
dom.tracked.1.tag.1 Tracked Nth, Nth tag dom.tracked.1.tag.1 Tracked Nth, Nth tag
@ -258,192 +257,184 @@ Supported DOM references are:
dom.tracked.1.end Tracked Nth, end time, blank if closed dom.tracked.1.end Tracked Nth, end time, blank if closed
dom.tracked.1.duration Tracked Nth, elapsed dom.tracked.1.duration Tracked Nth, elapsed
dom.tracked.1.json Tracked Nth, interval as JSON dom.tracked.1.json Tracked Nth, interval as JSON
.
dom.rc.<name> Configuration setting dom.rc.<name> Configuration setting
.
.SH CONFIGURATION FILE AND OVERRIDE OPTIONS .SH CONFIGURATION FILE AND OVERRIDE OPTIONS
Timewarrior stores its configuration in a file in the user's home directory: Timewarrior stores its configuration in a file in the user's home directory:
~/.timewarrior/timewarrior.cfg. ~/.timewarrior/timewarrior.cfg.
.
This file contains a mix of rules and configuration settings. Note that the This file contains a mix of rules and configuration settings.
environment variable $TIMEWARRIORDB can be set to override this location. 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 The values 'true', '1', 'y', 'yes' and 'on' are all equivalent and enable a setting.
setting. Any other value means disable the setting. Any other value means disable the setting.
.
Default values may be overridden by timewarrior.cfg values, which may in turn be Default values may be overridden by timewarrior.cfg values, which may in turn be overridden on the command line using:
overridden on the command line using: .
rc.<name>=<value> rc.<name>=<value>
.
For example, to turn off verbose mode: For example, to turn off verbose mode:
.
rc.verbose=0 rc.verbose=0
.
Note that hints can also do this (:quiet). Note that hints can also do this (:quiet).
.
.TP .TP
.B confirmation = yes .B confirmation = yes
Determines whether harmful operations require interactive confirmation. Determines whether harmful operations require interactive confirmation.
May be overridden by the ':yes' hint. May be overridden by the ':yes' hint.
Default value is 'yes'. Default value is 'yes'.
.
.TP .TP
.B debug = off .B debug = off
Determines whether diagnostic debugging information is shown. Determines whether diagnostic debugging information is shown.
Useful for troubleshooting, but not for general use. Useful for troubleshooting, but not for general use.
Default value is 'off'. Default value is 'off'.
.
.TP .TP
.B debug.indicator = >> .B debug.indicator = >>
The debug output prefix string. The debug output prefix string.
Default value is '>>'. Default value is '>>'.
.
.TP .TP
.B reports.<type>.cell = 15 .B reports.<type>.cell = 15
.br .br
Determines how many minutes are represented by a single character cell, for the Determines how many minutes are represented by a single character cell, for the charts.
charts.
A value of '15' means that an hour is represented by 60/15, or 4 character cells. 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, ...). Suitable values are the divisors of 60 (30, 20, 15, 12, ...).
The value must be greater than '0'. The value must be greater than '0'.
Default value is '15'. Default value is '15'.
Type is one of 'month', 'week', 'day'. Type is one of 'month', 'week', 'day'.
.
.TP .TP
.B reports.<type>.day = yes .B reports.<type>.day = yes
.br .br
Determines whether the current day of the month is shown at left margin. Determines whether the current day of the month is shown at left margin.
Default value is 'yes'. Default value is 'yes'.
Type is one of 'month', 'week', 'day'. Type is one of 'month', 'week', 'day'.
.
.TP .TP
.B reports.<type>.holidays = yes .B reports.<type>.holidays = yes
.br .br
Determines whether relevant holidays are shown beneath the report. Determines whether relevant holidays are shown beneath the report.
Default value is 'yes'. Default value is 'yes'.
Type is one of 'month', 'week', 'day', 'summary'. Type is one of 'month', 'week', 'day', 'summary'.
.
.TP .TP
.B reports.<type>.hours = all .B reports.<type>.hours = all
.br .br
Determines how the <type> report shows all the hours in a day ('all'), or is Determines how the <type> report shows all the hours in a day ('all'), or is limited to only hours where data is tracked ('auto').
limited to only hours where data is tracked ('auto'). Default value is 'all'. Default value is 'all'.
Type is one of 'month', 'week', 'day'. Type is one of 'month', 'week', 'day'.
.
.TP .TP
.B reports.<type>.lines = 1 .B reports.<type>.lines = 1
.br .br
Determines how many lines are used to render each day on the <type> report. Determines how many lines are used to render each day on the <type> report.
Default value is '1'. Default value is '1'.
Type is one of 'month', 'week', 'day'. Type is one of 'month', 'week', 'day'.
.
.TP .TP
.B reports.<type>.month = yes .B reports.<type>.month = yes
.br .br
Determines whether the current month is shown at left margin. Determines whether the current month is shown at left margin.
Default value is 'yes'. Default value is 'yes'.
Type is one of 'month', 'week', 'day'. Type is one of 'month', 'week', 'day'.
.
.TP .TP
.B reports.<type>.range = <range hint> .B reports.<type>.range = <range hint>
.br .br
For reports that show a range of data, this setting will override the default For reports that show a range of data, this setting will override the default value.
value. The value should be a range hint, see 'hints' The value should be a range hint, see 'hints'
Type is one of 'gaps', 'day', 'week', 'month'. Type is one of 'gaps', 'day', 'week', 'month'.
.
.TP .TP
.B reports.<type>.spacing = 1 .B reports.<type>.spacing = 1
.br .br
Specifies how many spaces are inserted between the hours in the <type> report Specifies how many spaces are inserted between the hours in the <type> report exclusions.
exclusions. A value of '0' yields a more compact report. Default value is '1'. A value of '0' yields a more compact report.
Default value is '1'.
Type is one of 'month', 'week', 'day'. Type is one of 'month', 'week', 'day'.
.
.TP .TP
.B reports.<type>.axis = external .B reports.<type>.axis = external
.br .br
The value 'internal' puts the hour markers (time line at the top) inside the 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.
exclusion blocks, 'external' puts the hour markers in a separate line; Default is 'internal' for the day report and 'external' for other reports.
additional values might be defined in the future. Default is 'internal' for .
the day report and 'external' for other reports.
.TP .TP
.B reports.<type>.summary = on .B reports.<type>.summary = on
.br .br
Determines whether the hours summary is shown. Default value is 'on'. Determines whether the hours summary is shown.
Default value is 'on'.
Type is one of 'month', 'week', 'day'. Type is one of 'month', 'week', 'day'.
.
.TP .TP
.B reports.<type>.totals = on .B reports.<type>.totals = on
.br .br
Determines whether the time totals are shown for each day on the report. Determines whether the time totals are shown for each day on the report.
Default value is 'on'. Default value is 'on'.
Type is one of 'month', 'week', 'day'. Type is one of 'month', 'week', 'day'.
.
.TP .TP
.B reports.<type>.week = yes .B reports.<type>.week = yes
.br .br
Determines whether the current week number is shown at left margin. Determines whether the current week number is shown at left margin.
Default value is 'yes'. Default value is 'yes'.
Type is one of 'month', 'week', 'day'. Type is one of 'month', 'week', 'day'.
.
.TP .TP
.B reports.<type>.weekday = yes .B reports.<type>.weekday = yes
.br .br
Determines whether the current weekday is shown at left margin. Determines whether the current weekday is shown at left margin.
Default value is 'yes'. Default value is 'yes'.
Type is one of 'month', 'week', 'day'. Type is one of 'month', 'week', 'day'.
.
.TP .TP
.B verbose = yes .B verbose = yes
Determines whether Timewarrior generates feedback. Determines whether Timewarrior generates feedback.
May be overridden by the ':quiet' hint. May be overridden by the ':quiet' hint.
Default value is 'yes'. Default value is 'yes'.
.
.SH MORE EXAMPLES .SH "MORE EXAMPLES"
.
For examples please see the online documentation starting at: For examples please see the online documentation starting at:
.
.RS .RS
<https://taskwarrior.org/docs/timewarrior/> <https://taskwarrior.org/docs/timewarrior/>
.RE .RE
.
Note that the online documentation can be more detailed and more current than Note that the online documentation can be more detailed and more current than this man page.
this man page. .
.SH FILES .SH FILES
.
.TP .TP
~/.timewarrior/timewarrior.cfg ~/.timewarrior/timewarrior.cfg
User configuration file. User configuration file.
.
.TP .TP
~/.timewarrior/data/YYYY-MM.data ~/.timewarrior/data/YYYY-MM.data
Time tracking data files. Time tracking data files.
.
.SH "CREDITS & COPYRIGHTS" .SH "CREDITS & COPYRIGHTS"
Copyright (C) 2015 \- 2018 P. Beckingham, F. Hernandez. Copyright (C) 2015 \- 2018 T.Lauf, P. Beckingham, F. Hernandez.
.
Timewarrior is distributed under the MIT license. See Timewarrior is distributed under the MIT license.
https://www.opensource.org/licenses/mit-license.php for more information. See https://www.opensource.org/licenses/mit-license.php for more information.
.
.SH SEE ALSO .SH "SEE ALSO"
For more information regarding Timewarrior, see the following: For more information regarding Timewarrior, see the following:
.
.TP .TP
The official site at The official site at <https://timewarrior.net>
<https://timewarrior.net> .
.TP .TP
The official code repository at The official code repository at <https://github.com/GothenburgBitFactory/timewarrior>
<https://github.com/GothenburgBitFactory/timewarrior> .
.TP .TP
You can contact the project by emailing You can contact the project by emailing <support@gothenburgbitfactory.org>
<support@gothenburgbitfactory.org> .
.SH REPORTING BUGS .SH REPORTING BUGS
.TP .TP
Bugs in Timewarrior may be reported to the issue-tracker at Bugs in Timewarrior may be reported to the issue-tracker at <https://github.com/GothenburgBitFactory/timewarrior/issues>
<https://github.com/GothenburgBitFactory/timewarrior/issues>