mirror of
https://github.com/GothenburgBitFactory/taskwarrior.git
synced 2025-07-07 20:06:36 +02:00
Documentation
- Corrected man page against reality.
This commit is contained in:
parent
8537ddbb5a
commit
6db7285f70
1 changed files with 89 additions and 52 deletions
|
@ -3,8 +3,6 @@
|
||||||
.SH NAME
|
.SH NAME
|
||||||
task \- A command line todo manager.
|
task \- A command line todo manager.
|
||||||
|
|
||||||
NOTE THAT THIS DOCUMENT HAS NOT BEEN FULLY UPDATED FOR THE 2.0 RELEASE.
|
|
||||||
|
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
.B task <filter> <command> [ <mods> | <args> ]
|
.B task <filter> <command> [ <mods> | <args> ]
|
||||||
|
|
||||||
|
@ -23,18 +21,19 @@ list program when you modify the configuration file to have the output displayed
|
||||||
the way you want to see it.
|
the way you want to see it.
|
||||||
|
|
||||||
.SH FILTER
|
.SH FILTER
|
||||||
The <filter> consists of zero or more search criteria to select. For example,
|
The <filter> consists of zero or more search criteria that select tasks. For
|
||||||
to list all tasks belonging to the 'Home' project:
|
example, to list all tasks belonging to the 'Home' project:
|
||||||
|
|
||||||
task project:Home list
|
task project:Home list
|
||||||
|
|
||||||
You can specify multiple filters, each of which further restrict the results:
|
You can specify multiple filter terms, each of which further restrict the
|
||||||
|
result:
|
||||||
|
|
||||||
task project:Home +weekend garden list
|
task project:Home +weekend garden list
|
||||||
|
|
||||||
This example applies three filters: the 'Home' project, the 'weekend' tag, and
|
This example applies three filters: the 'Home' project, the 'weekend' tag, and
|
||||||
the description or annotations must contain the characters 'garden'. In this
|
the description or annotations must contain the character sequence 'garden'.
|
||||||
example, 'garden' is translated internally to:
|
In this example, 'garden' is translated internally to:
|
||||||
|
|
||||||
description.contains:garden
|
description.contains:garden
|
||||||
|
|
||||||
|
@ -42,6 +41,15 @@ as a convenient shortcut. The 'contains' here is an attribute modifier, which
|
||||||
is used to exert more control over the filter than simply absence or presence.
|
is used to exert more control over the filter than simply absence or presence.
|
||||||
See 'ATTRIBUTE MODIFIERS' for a complete list of modifiers.
|
See 'ATTRIBUTE MODIFIERS' for a complete list of modifiers.
|
||||||
|
|
||||||
|
Note that a filter may have zero terms, which means that all tasks apply to the
|
||||||
|
command. This can be dangerous, and this special case is confirmed, and
|
||||||
|
cannot be overridden. For example, this command:
|
||||||
|
|
||||||
|
task modify +work
|
||||||
|
This command has no filter, and will modify all tasks. Are you sure? (yes/no)
|
||||||
|
|
||||||
|
will add the 'work' tag to all tasks, but only after confirmation.
|
||||||
|
|
||||||
More filter examples:
|
More filter examples:
|
||||||
|
|
||||||
task <command> <mods>
|
task <command> <mods>
|
||||||
|
@ -50,13 +58,13 @@ More filter examples:
|
||||||
task project:Home due.before:today <command> <mods>
|
task project:Home due.before:today <command> <mods>
|
||||||
task ebeeab00-ccf8-464b-8b58-f7f2d606edfb <command> <mods>
|
task ebeeab00-ccf8-464b-8b58-f7f2d606edfb <command> <mods>
|
||||||
|
|
||||||
By default, filter elements are combined with an implicit 'and' operator,
|
By default filter elements are combined with an implicit 'and' operator,
|
||||||
but 'or' and 'xor' may also be used, provided parentheses are included:
|
but 'or' and 'xor' may also be used, provided parentheses are included:
|
||||||
|
|
||||||
task '( /[Cc]at|[Dd]og/ or /[0-9]+/ )' <command> <mods>
|
task '( /[Cc]at|[Dd]og/ or /[0-9]+/ )' <command> <mods>
|
||||||
|
|
||||||
The parentheses isolate the logical term from any default command filter or
|
The parentheses isolate the logical term from any default command filter or
|
||||||
implicit report filter.
|
implicit report filter which would be combined with an implicit 'and'.
|
||||||
|
|
||||||
A filter may target specific tasks using ID or UUID numbers. To specify
|
A filter may target specific tasks using ID or UUID numbers. To specify
|
||||||
multiple tasks use one of these forms:
|
multiple tasks use one of these forms:
|
||||||
|
@ -91,6 +99,10 @@ taskwarrior. The output and sort behavior of these reports can be configured in
|
||||||
the configuration file. See also the man page taskrc(5). There are also other
|
the configuration file. See also the man page taskrc(5). There are also other
|
||||||
read subcommands that are not reports.
|
read subcommands that are not reports.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
.B task <filter>
|
||||||
|
With no command specified, the default command is run, and the filter applied.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task <filter> active
|
.B task <filter> active
|
||||||
Shows all tasks matching the filter that are started but not completed.
|
Shows all tasks matching the filter that are started but not completed.
|
||||||
|
@ -101,7 +113,7 @@ Shows all tasks matching the filter, including parents of recurring tasks.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task <filter> blocked
|
.B task <filter> blocked
|
||||||
Shows all blocked tasks, that are dependent on other tasks, matching the filter.
|
Shows all tasks matching the filter, that have dependencies on other tasks.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task <filter> burndown.daily
|
.B task <filter> burndown.daily
|
||||||
|
@ -117,8 +129,13 @@ Shows a graphical burndown chart, by week.
|
||||||
Shows a graphical burndown chart, by month.
|
Shows a graphical burndown chart, by month.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task calendar [ y | due [y] | month year [y] | year ]
|
.B task calendar [due|<month> <year>|<year>] [y]
|
||||||
Shows a monthly calendar with due tasks marked.
|
Shows a monthly calendar with due tasks marked. Shows one horizontal line of
|
||||||
|
months. If the 'y' argument is provided, will show at least one complete year.
|
||||||
|
If a year is provided, such as '2012', then that full year is shown. If both
|
||||||
|
a month and a year are specified ('6 2012') then the months displayed begin at
|
||||||
|
the specified month and year. If the 'due' argument is provided, will show
|
||||||
|
the starting month of the earliest due task.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task colors [sample | legend]
|
.B task colors [sample | legend]
|
||||||
|
@ -127,7 +144,8 @@ currently defined colors.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task columns
|
.B task columns
|
||||||
Displays all supported columns and formatting styles.
|
Displays all supported columns and formatting styles. Useful when creating
|
||||||
|
custom reports.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task <filter> completed
|
.B task <filter> completed
|
||||||
|
@ -175,7 +193,11 @@ to achieve this:
|
||||||
task $(task project:Home ids) modify priority:H
|
task $(task project:Home ids) modify priority:H
|
||||||
|
|
||||||
This example first gets the IDs for the project:Home filter, then sets
|
This example first gets the IDs for the project:Home filter, then sets
|
||||||
the priority to H for each of those tasks.
|
the priority to H for each of those tasks. This can also be achieved directly:
|
||||||
|
|
||||||
|
task project:Home modify priority:H
|
||||||
|
|
||||||
|
This command is mainly of use to external scripts.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task <filter> uuids
|
.B task <filter> uuids
|
||||||
|
@ -188,9 +210,12 @@ this:
|
||||||
This example first gets the UUIDs for the project:Home and status:completed
|
This example first gets the UUIDs for the project:Home and status:completed
|
||||||
filter, then makes each of those tasks pending again.
|
filter, then makes each of those tasks pending again.
|
||||||
|
|
||||||
|
This command is mainly of use to external scripts.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task <filter> information
|
.B task <filter> information
|
||||||
Shows all data and metadata for the specified tasks.
|
Shows all data and metadata for the specified tasks. This is the only means of
|
||||||
|
displaying all aspects of a given task, including the change history.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task <filter> list
|
.B task <filter> list
|
||||||
|
@ -236,7 +261,7 @@ Shows all recurring tasks matching the filter.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task <filter> unblocked
|
.B task <filter> unblocked
|
||||||
Shows all tasks that are not blocked by dependencies, matching the filter.
|
Shows all tasks that do not have dependencies, matching the filter.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task <filter> waiting
|
.B task <filter> waiting
|
||||||
|
@ -246,7 +271,7 @@ Shows all waiting tasks matching the filter.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task add <mods>
|
.B task add <mods>
|
||||||
Adds a new task to the task list.
|
Adds a new pending task to the task list.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task <filter> annotate <mods>
|
.B task <filter> annotate <mods>
|
||||||
|
@ -282,7 +307,7 @@ In general, this is not the recommended method of modifying tasks, but is
|
||||||
provided for exceptional circumstances. Use carefully.
|
provided for exceptional circumstances. Use carefully.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task import \fIfile
|
.B task import <file> [<file> ...]
|
||||||
Imports tasks in the JSON format. The standard task release comes with a few
|
Imports tasks in the JSON format. The standard task release comes with a few
|
||||||
example scripts, such as import-yaml.pl.
|
example scripts, such as import-yaml.pl.
|
||||||
|
|
||||||
|
@ -369,6 +394,9 @@ It includes compiler, library and software information. It does not include
|
||||||
any personal information, other than the location and size of your task data
|
any personal information, other than the location and size of your task data
|
||||||
files.
|
files.
|
||||||
|
|
||||||
|
This command also performs a diagnostic scan of your data files looking for
|
||||||
|
common problems, such as duplicate UUIDs.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task execute <external command>
|
.B task execute <external command>
|
||||||
Executes the specified command. Not useful by itself, but when used in
|
Executes the specified command. Not useful by itself, but when used in
|
||||||
|
@ -376,7 +404,7 @@ conjunction with aliases and extensions can provide seamless integration.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task logo
|
.B task logo
|
||||||
Displays the taskwarrior logo.
|
Displays the Taskwarrior logo.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task reports
|
.B task reports
|
||||||
|
@ -399,11 +427,7 @@ Shows statistics of the tasks defined by the filter.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task <filter> summary
|
.B task <filter> summary
|
||||||
Shows a report of task status by project.
|
Shows a report of aggregated task status by project.
|
||||||
|
|
||||||
.TP
|
|
||||||
.B task synchronize
|
|
||||||
Synchronizes task data with the task server, if configured.
|
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task <filter> tags
|
.B task <filter> tags
|
||||||
|
@ -468,12 +492,13 @@ Shows the IDs and descriptions of matching tasks.
|
||||||
.TP
|
.TP
|
||||||
.B ID
|
.B ID
|
||||||
Tasks can be specified uniquely by IDs, which are simply the index of the
|
Tasks can be specified uniquely by IDs, which are simply the index of the
|
||||||
task in a report. Be careful, as the IDs of tasks may change after a
|
task in the data file. The ID of a task may therefore change, but only when
|
||||||
modification to the database. Always run a report to check you have the right
|
a command is run that displays IDs. When modifying tasks, it is safe to
|
||||||
ID for a task. IDs can be given to task as a sequences, for example,
|
rely on the last displayed ID. Always run a report to check you have the right
|
||||||
|
ID for a task. IDs can be given to task as a sequence, for example,
|
||||||
.br
|
.br
|
||||||
.B
|
.B
|
||||||
task 1,4-10,19 del
|
task 1,4-10,19 delete
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B +tag|-tag
|
.B +tag|-tag
|
||||||
|
@ -494,7 +519,7 @@ exempt from all color rules. The supported special tags are:
|
||||||
Specifies the project to which a task is related to.
|
Specifies the project to which a task is related to.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B priority:H|M|L or priority:
|
.B priority:H|M|L or priority:
|
||||||
Specifies High, Medium, Low and no priority for a task.
|
Specifies High, Medium, Low and no priority for a task.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
|
@ -664,9 +689,6 @@ You can use the following operators in filter expressions:
|
||||||
|
|
||||||
and or xor Logical operators
|
and or xor Logical operators
|
||||||
< <= = != >= > Relational operators
|
< <= = != >= > Relational operators
|
||||||
+ - Addition, subtraction
|
|
||||||
! Inversion
|
|
||||||
~ !~ Match, no match
|
|
||||||
( ) Precedence
|
( ) Precedence
|
||||||
|
|
||||||
For example:
|
For example:
|
||||||
|
@ -731,6 +753,10 @@ in the taskwarrior configuration file.
|
||||||
Exact specification
|
Exact specification
|
||||||
task ... due:7/14/2008
|
task ... due:7/14/2008
|
||||||
|
|
||||||
|
.TP
|
||||||
|
ISO-8601
|
||||||
|
task ... due:20120314T223000Z
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
Relative wording
|
Relative wording
|
||||||
task ... due:today
|
task ... due:today
|
||||||
|
@ -866,10 +892,9 @@ abbreviation.minimum=3
|
||||||
.RE
|
.RE
|
||||||
|
|
||||||
.SH SPECIFYING DESCRIPTIONS
|
.SH SPECIFYING DESCRIPTIONS
|
||||||
Some task descriptions need to be escaped because of the shell
|
Some task descriptions need to be escaped because of the shell and the special
|
||||||
and the special meaning of some characters to the shell. This can be
|
meaning of some characters to the shell. This can be done either by adding
|
||||||
done either by adding quotes to the description or escaping the special
|
quotes to the description or escaping the special character:
|
||||||
character:
|
|
||||||
|
|
||||||
.RS
|
.RS
|
||||||
$ task add "quoted ' quote"
|
$ task add "quoted ' quote"
|
||||||
|
@ -897,19 +922,35 @@ is broken up into several arguments, which is corrected with quotes:
|
||||||
$ task 123 modify "/from this/to that/"
|
$ task 123 modify "/from this/to that/"
|
||||||
.RE
|
.RE
|
||||||
|
|
||||||
|
It is sometimes necessary to force the shell to pass quotes to Taskwarrior
|
||||||
|
intact, so you can use:
|
||||||
|
|
||||||
|
.RS
|
||||||
|
$ task add project:\\'Three Word Project\\' description
|
||||||
|
.RE
|
||||||
|
|
||||||
.SH CONFIGURATION FILE AND OVERRIDE OPTIONS
|
.SH CONFIGURATION FILE AND OVERRIDE OPTIONS
|
||||||
Taskwarrior stores its configuration in a file in the user's home directory:
|
Taskwarrior stores its configuration in a file in the user's home directory:
|
||||||
~/.taskrc . The default configuration file can be overridden with
|
~/.taskrc. The default configuration file can be overridden with:
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task rc:<path-to-alternate-file>
|
.B task rc:<path-to-alternate-file> ...
|
||||||
Specifies an alternate configuration file.
|
Specifies an alternate configuration file.
|
||||||
|
|
||||||
|
.TP TASKRC=/tmp/.taskrc task ..
|
||||||
|
The environment variable overrides the default and the command line
|
||||||
|
specification of the .taskrc file.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
.B task rc.<name>:<value> ...
|
.B task rc.<name>:<value> ...
|
||||||
.B task rc.<name>=<value> ...
|
.B task rc.<name>=<value> ...
|
||||||
Specifies individual configuration file overrides.
|
Specifies individual configuration file overrides.
|
||||||
|
|
||||||
|
.TP
|
||||||
|
.B TASKDATA=/tmp/.task task ...
|
||||||
|
The environment variable overrides the default, the command line, and
|
||||||
|
the 'data.location' configuration setting of the task data directory.
|
||||||
|
|
||||||
.SH MORE EXAMPLES
|
.SH MORE EXAMPLES
|
||||||
|
|
||||||
For examples please see the task tutorial man page at
|
For examples please see the task tutorial man page at
|
||||||
|
@ -924,16 +965,21 @@ or the online documentation starting at
|
||||||
<http://taskwarrior.org/projects/taskwarrior/wiki>
|
<http://taskwarrior.org/projects/taskwarrior/wiki>
|
||||||
.RE
|
.RE
|
||||||
|
|
||||||
|
Note that the online documentation is more detailed and more current than this
|
||||||
|
man page.
|
||||||
|
|
||||||
.SH FILES
|
.SH FILES
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
~/.taskrc
|
~/.taskrc
|
||||||
User configuration file - see also taskrc(5).
|
User configuration file - see also taskrc(5). Note that this can be
|
||||||
|
overridden on the command line or by the TASKRC environment variable.
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
~/.task
|
~/.task
|
||||||
The default directory where task stores its data files. The location
|
The default directory where task stores its data files. The location
|
||||||
can be configured in the configuration file.
|
can be configured in the configuration variable 'data.location', or
|
||||||
|
overridden with the TASKDATA environment variable..
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
~/.task/pending.data
|
~/.task/pending.data
|
||||||
|
@ -947,16 +993,6 @@ The file that contains the completed "done" tasks.
|
||||||
~/.task/undo.data
|
~/.task/undo.data
|
||||||
The file that contains the information to the "undo" command.
|
The file that contains the information to the "undo" command.
|
||||||
|
|
||||||
.TP
|
|
||||||
~/.task/backlog.data
|
|
||||||
The file that contains un-synched tasks, if the task server
|
|
||||||
is configured.
|
|
||||||
|
|
||||||
.TP
|
|
||||||
~/.task/synch.key
|
|
||||||
The file that contains the synchronization key, if the task
|
|
||||||
server is configured.
|
|
||||||
|
|
||||||
.SH "CREDITS & COPYRIGHTS"
|
.SH "CREDITS & COPYRIGHTS"
|
||||||
Copyright (C) 2006 \- 2012 P. Beckingham, F. Hernandez.
|
Copyright (C) 2006 \- 2012 P. Beckingham, F. Hernandez.
|
||||||
|
|
||||||
|
@ -970,7 +1006,7 @@ http://www.opensource.org/licenses/mit-license.php for more information.
|
||||||
.BR task-color(5),
|
.BR task-color(5),
|
||||||
.BR task-sync(5)
|
.BR task-sync(5)
|
||||||
|
|
||||||
For more information regarding taskwarrior, the following may be referenced:
|
For more information regarding taskwarrior, see the following:
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
The official site at
|
The official site at
|
||||||
|
@ -981,10 +1017,11 @@ The official code repository at
|
||||||
<git://tasktools.org/task.git/>
|
<git://tasktools.org/task.git/>
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
You can contact the project by writing an email to
|
You can contact the project by emailing
|
||||||
<support@taskwarrior.org>
|
<support@taskwarrior.org>
|
||||||
|
|
||||||
.SH REPORTING BUGS
|
.SH REPORTING BUGS
|
||||||
.TP
|
.TP
|
||||||
Bugs in taskwarrior may be reported to the issue-tracker at
|
Bugs in taskwarrior may be reported to the issue-tracker at
|
||||||
<http://taskwarrior.org>
|
<http://taskwarrior.org>
|
||||||
|
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue