GothenburgBitFactory/taskwarrior
1
0
Fork 0
mirror of https://github.com/GothenburgBitFactory/taskwarrior.git synced 2025-06-26 10:54:26 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Documentation

Browse source 
- While the man pages were not exactly updated for 2.0, the harmful and
  obsolete stuff was removed.
This commit is contained in:
Paul Beckingham 2011-09-13 18:33:14 -04:00
parent 761def8fb7
commit 6e52194ab0
4 changed files with 107 additions and 131 deletions
Download patch file Download diff file Expand all files Collapse all files

51
doc/man/task-color.5.in
View file

@ -41,14 +41,14 @@ Do we really want all those color control codes in the file? Taskwarrior
assumes that you do not, and temporarily sets color to 'off' while generating
the output. This explains the output from the following command:
$ task config | grep '^color '
$ task show | grep '^color '
color off
it always returns 'off', no matter what the setting.
it always returns 'off', no matter what the setting, because the output is being
sent to a pipe.
The reason is that the taskwarrior output gets piped into grep, and the color is
disabled. If you wanted those color codes, you can override this behavior by
setting the _forcecolor variable to on, like this:
If you wanted those color codes, you can override this behavior by setting the
_forcecolor variable to on, like this:
$ task config _forcecolor on
$ task config | grep '^color '
@ -121,7 +121,7 @@ the sample requested.
Some combinations look very nice, some look terrible. Different terminal
programs do implement slightly different versions of 'red', for example, so you
may see some unwanted variation due to the program. The brightness of your
may see some unexpected variation across machines. The brightness of your
display is also a factor.
.SH 256-COLOR SUPPORT
@ -193,7 +193,7 @@ combination:
red on gray3
you are mixing a 16-color and 256-color specification. Taskwarrior will map red
to color1, and proceed. Note that red and color1 are not quite the same.
to color1, and proceed. Note that red and color1 are not quite the same tone.
Note also that there is no bold or bright attributes when dealing with 256
colors, but there is still underline available.
@ -210,7 +210,7 @@ without necessarily creating a set of tasks that meet each of the rule criteria.
.SH RULES
Taskwarrior supports colorization rules. These are configuration values that
specify a color, and the conditions under which that color is used. By example,
let's add a few tasks:
let us add a few tasks:
$ task add project:Home priority:H pay the bills (1)
$ task add project:Home clean the rug (2)
@ -219,13 +219,13 @@ let's add a few tasks:
We can add a color rule that uses a blue background for all tasks in the Home
project:
$ task config color.project.Home on blue
$ task config color.project.Home 'on blue'
We use quotes around "on blue" because there are two words, but they represent
We use quotes around 'on blue' because there are two words, but they represent
one value in the .taskrc file. Now suppose we which to use a bold yellow text
color for all cleaning work:
$ task config color.keyword.clean bold yellow
$ task config color.keyword.clean 'bold yellow'
Now what happens to task 2, which belongs to project Home (blue background), and
is also a cleaning task (bold yellow foreground)? The colors are combined, and
@ -243,16 +243,17 @@ be a visual mess. Beware!
The precedence for the color rules is determined by the configuration
variable 'rule.precedence.color', which by default contains:
due.today,active,blocked,overdue,due,keyword,project,tag,recurring,pri,tagged
due.today,active,blocked,overdue,due,keyword,project,tag,recurring,pri,tagged,completed,deleted
These are just the color rules with the 'color.' prefix removed. The
rule 'color.due.today' is the highest precedence, and 'color.tagged' is the lowest.
rule 'color.due.today' is the highest precedence, and 'color.deleted' is the lowest.
The keyword rule shown here as 'keyword' corresponds to a wildcard pattern,
meaning 'color.keyword.*', or in other words all the keyword rules. Similarly
for the 'color.tag.*' and 'color.project.*' rules.
There is also 'color.project.none', 'color.tag.none' and 'color.pri.none'.
There is also 'color.project.none', 'color.tag.none' and 'color.pri.none' to
specifically represent missing data.
.SH THEMES
Taskwarrior supports themes. What this really means is that with the ability to
@ -269,19 +270,29 @@ include /usr/local/share/doc/task/rc/dark-256.theme
You can use any of the standard taskwarrior themes:
.RS
light-16.theme
.br
light-256.theme
.br
dark-16.theme
.br
dark-256.theme
.br
dark-red-256.theme
dark-blue-256.theme
.br
dark-gray-256.theme
.br
dark-green-256.theme
.br
dark-blue-256.theme
dark-red-256.theme
.br
dark-violets-256.theme
.br
dark-yellow-green.theme
.br
light-16.theme
.br
light-256.theme
.br
solarized-dark-256.theme
.br
solarized-light-256.theme
.RE
You can also see how the theme will color the various tasks with the command:

8
doc/man/task-faq.5.in
View file

@ -144,8 +144,8 @@ particularly if your .taskrc file was created by an older version.
.TP
.B Q: Do I need to back up my taskwarrior data?
Yes. You should back up your ~/.task directory, and probably your ~/.taskrc
file too.
Yes. You should back up all the files in your ~/.task directory, and probably
your ~/.taskrc file too.
.TP
.B Q: Can I share my tasks between different machines?
@ -253,9 +253,9 @@ When you run a report (such as "list"), the numbers are assigned before display.
For example, you can do this:
$ task list
$ task do 12
$ task 12 done
$ task add Pay the rent
$ task delete 31
$ task 31 delete
Those id numbers are then good until the next report is run. This is because
taskwarrior performs a garbage-collect operation on the pending tasks file when

2
doc/man/task-tutorial.5.in
View file

@ -3,6 +3,8 @@
.SH NAME
task-tutorial \- A tutorial for the task(1) command line todo manager.
NOTE THAT THIS DOCUMENT HAS NOT YET BEEN UPDATED FOR THE 2.0 RELEASE.
.SH DESCRIPTION
This tutorial contains a narrative and a series of commands that lead you
through different scenarios and illustrate the capabilities of taskwarrior.

173
doc/man/task.1.in
View file

@ -3,6 +3,8 @@
.SH NAME
task \- A command line todo manager.
NOTE THAT THIS DOCUMENT HAS NOT BEEN FULLY UPDATED FOR THE 2.0 RELEASE.
.SH SYNOPSIS
.B task [subcommand] [args]
@ -22,32 +24,28 @@ the way you want to see it.
.SH SUBCOMMANDS
.TP
.B add [tags] [attrs] description
.B add <modifications>
Adds a new task to the task list.
.TP
.B log [tags] [attrs] description
.B log <modifications>
Adds a new task that is already completed, to the task list.
.TP
.B annotate ID description
.B <filter> annotate <modifications>
Adds an annotation to an existing task.
.TP
.B denotate ID description
.B <filter> denotate <modifications>
Deletes an annotation for the specified task. If the provided description
matches an annotation exactly, the corresponding annotation is deleted. If the
provided description matches annotations partly, the first partly matched
annotation is deleted.
.TP
.B information ID
.B <filter> information
Shows all data and metadata for the specified task.
.TP
.B ID
With an ID but no specific command, taskwarrior runs the "information" command.
.TP
.B undo
Reverts the most recent action. Obeys the confirmation setting.
@ -57,38 +55,38 @@ Reverts the most recent action. Obeys the confirmation setting.
Launches an interactive shell with all the task commands available.
.TP
.B duplicate ID [tags] [attrs] [description]
.B <filter> duplicate <modifications>
Duplicates the specified task and allows modifications.
.TP
.B delete ID
.B <filter> delete <modifications>
Deletes the specified task from task list.
.TP
.B start ID
.B <filter> start <modifications>
Marks the specified task as started.
.TP
.B stop ID
.B <filter> stop <modifications>
Removes the
.I start
time from the specified task.
.TP
.B done ID [tags] [attrs] [description]
.B <filter> done <modifications>
Marks the specified task as done.
.TP
.B projects
.B <filter> projects
Lists all project names that are currently used by pending tasks, and the
number of tasks for each.
.TP
.B tags
.B <filter> tags
Show a list of all tags used. Any special tags used are highlighted.
.TP
.B summary
.B <filter> summary
Shows a report of task status by project.
.TP
@ -96,31 +94,31 @@ Shows a report of task status by project.
Shows a weekly report of tasks completed and started.
.TP
.B history
.B <filter> history
Shows a report of task history by month. Alias to history.monthly.
.TP
.B history.annual
.B <filter> history.annual
Shows a report of task history by year.
.TP
.B ghistory
.B <filter> ghistory
Shows a graphical report of task status by month. Alias to ghistory.monthly.
.TP
.B ghistory.annual
.B <filter> ghistory.annual
Shows a graphical report of task status by year.
.TP
.B burndown.daily
.B <filter> burndown.daily
Shows a graphical burndown chart, by day.
.TP
.B burndown.weekly
.B <filter> burndown.weekly
Shows a graphical burndown chart, by week.
.TP
.B burndown.monthly
.B <filter> burndown.monthly
Shows a graphical burndown chart, by month.
.TP
@ -128,7 +126,7 @@ Shows a graphical burndown chart, by month.
Shows a monthly calendar with due tasks marked.
.TP
.B stats
.B <filter> stats
Shows task database statistics.
.TP
@ -137,30 +135,11 @@ Imports tasks in a variety of formats, from file or URL.
.TP
.B export
Exports all tasks in the default format. This is an alias to the command
export.yaml. Redirect the output to a file, if you wish to save it, or pipe it
to another command.
Exports all tasks in the JSON format. export.yaml. Redirect the output to a
file, if you wish to save it, or pipe it to another command.
.TP
.B export.csv
Exports all tasks in CSV format.
Redirect the output to a file, if you wish to save it, or pipe it to another
command.
.TP
.B export.ical
Exports all tasks in iCalendar format.
Redirect the output to a file, if you wish to save it, or pipe it to another
command.
.TP
.B export.yaml
Exports all tasks in YAML 1.1 format.
Redirect the output to a file, if you wish to save it, or pipe it to another
command.
.TP
.B merge URL
.B merge <URL>
Merges two task databases by comparing the modifications that are stored in the
undo.data files. The location of the second undo.data file must be passed on as
argument. URL may have the following syntaxes:
@ -177,14 +156,14 @@ You can set aliases for frequently used URLs in the .taskrc. Further documentati
can be found in task-sync(5) manpage.
.TP
.B push URL
.B push <URL>
Pushes the task database to a remote another location for distributing the
changes made by the merge command.
(See annotations above for valid URL syntaxes.)
.TP
.B pull URL
.B pull <URL>
Overwrites the task database with those files found at the URL.
(See annotations above for valid URL syntaxes.)
@ -195,16 +174,16 @@ Displays all possible colors, a named sample, or a legend containing all
currently defined colors.
.TP
.B count [filter]
.B <filter> count
Displays only a count of tasks matching the filter.
.TP
.B ids [filter]
.B <filter> ids
Applies the filter then extracts only the task IDs and presents them as
a range, for example: 1-4,12. This is useful as input to a task command,
to achieve this:
task priority:H $(task ids project:Home)
task modify priority:H $(task project:Home ids)
This example first gets the IDs for the project:Home filter, then sets
the priority to H for each of those tasks.
@ -249,37 +228,21 @@ Finally, this command removes any 'name=...' entry from the .taskrc file:
.SH MODIFYING SUBCOMMANDS
.TP
.B ID [tags] [attrs] [description]
.B <filter> modify <modifications>
Modifies the existing task with provided information.
.TP
.B ID /from/to/
Performs one substitution on task description and annotation for fixing
mistakes.
If either 'from' or 'to' contain spaces, you will need to put quotes around
the whole thing.
.TP
.B ID /from/to/g
Performs all substitutions on task description and annotation for fixing
mistakes.
If either 'from' or 'to' contain spaces, you will need to put quotes around
the whole thing.
.TP
.B edit ID
.B <filter> edit
Launches an editor to let you modify all aspects of a task directly.
In general, this is not the recommended method of modifying tasks, but is
provided for exceptional circumstances. Use carefully.
.TP
.B append [tags] [attrs] description
.B <filter> append <modifications>
Appends information to an existing task.
.TP
.B prepend [tags] [attrs] description
.B <filter> prepend <modifications>
Prepends information to an existing task.
.SH REPORT SUBCOMMANDS
@ -290,76 +253,76 @@ these reports can be configured in the configuration file. See also the man page
taskrc(5).
.TP
.B active [filter]
.B <filter> active
Shows all tasks matching the filter that are started but not completed.
.TP
.B all [filter]
.B <filter> all
Shows all tasks matching the filter, including parents of recurring tasks.
.TP
.B completed [filter]
.B <filter> completed
Shows all tasks matching the filter that are completed.
.TP
.B minimal [filter]
.B <filter> minimal
Provides a minimal listing of tasks matching the filter.
.TP
.B ls [filter]
.B <filter> ls
Provides a short listing of tasks matching the filter.
.TP
.B list [filter]
.B <filter> list
Provides a more detailed listing of tasks matching the filter.
.TP
.B long [filter]
.B <filter> long
Provides the most detailed listing of tasks with filter.
.TP
.B newest [filter]
.B <filter> newest
Shows the newest tasks with filter.
.TP
.B oldest [filter]
.B <filter> oldest
Shows the oldest tasks with filter
.TP
.B overdue [filter]
.B <filter> overdue
Shows all incomplete tasks matching the filter
that are beyond their due date.
.TP
.B recurring [filter]
.B <filter> recurring
Shows all recurring tasks matching the filter.
.TP
.B waiting [filter]
.B <filter> waiting
Shows all waiting tasks matching the filter.
.TP
.B blocked [filter]
.B <filter> blocked
Shows all blocked tasks, that are dependent on other tasks, matching the filter.
.TP
.B unblocked [filter]
.B <filter> unblocked
Shows all tasks that are not blocked by dependencies, matching the filter.
.TP
.B next [filter]
Shows all tasks with upcoming due dates matching the filter.
.B <filter> next
Shows a page of the most urgent tasks. Urgency is a calculated value.
.SH FILTERS
A filter is a set of search criteria that the report applies before displaying
the results. For example, to list all tasks belonging to the 'Home' project:
task list project:Home
task project:Home list
You can specify multiple filters, each of which further restrict the results:
task list project:Home +weekend garden
task project:Home +weekend garden list
This example applies three filters: the 'Home' project, the 'weekend' tag, and
the description or annotations must contain the characters 'garden'. In this
@ -381,7 +344,7 @@ modification to the database. Always run a report to check you have the right
ID for a task. IDs can be given to task as a sequences, for example,
.br
.B
task del 1,4-10,19
task 1,4-10,19 del
.TP
.B +tag|-tag
@ -418,11 +381,11 @@ Specifies the Recurrence end-date of a task.
.TP
.B fg:<color-spec>
Specifies foreground color.
Specifies foreground color. Deprecated.
.TP
.B bg:<color-spec>
Specifies background color.
Specifies background color. Deprecated.
.TP
.B limit:<number-of-rows>
@ -480,7 +443,7 @@ the complementary set of items. Supported modifiers are:
For example:
.RS
task list due.before:eom priority.not:L
task due.before:eom priority.not:L list
.RE
The
@ -500,8 +463,8 @@ The
.I none
modifier requires that the attribute does not have a value. For example:
task list priority:
task list priority.none:
task priority: list
task priority.none: list
are equivalent, and list tasks that do not have a priority.
@ -523,8 +486,8 @@ The
.I has
modifier is used to search for a substring, such as:
task list description.has:foo
task list foo
task description.has:foo list
task foo list
which are equivalent and will return any task that has 'foo' in the description
or annotations.
@ -539,14 +502,14 @@ The
.I startswith
modifier matches against the left, or beginning of an attribute, such that:
task list project.startswith:H
task list project:H
task project.startswith:H list
task project:H list
are equivalent and will match any project starting with 'H'. Matching all
projects not starting with 'H' is done with:
task list project.~startswith:H
task list project.not:H
task project.~startswith:H list
task project.not:H list
The
.I endswith
@ -557,7 +520,7 @@ The
modifier requires that the attribute contain the whole word specified, such
that this:
task list description.word:bar
task description.word:bar list
will match the description 'foo bar baz' but does not match 'dog food'.
@ -728,13 +691,13 @@ In other situations, the shell sees spaces and breaks up arguments. For
example, this command:
.RS
$ task 123 /from this/to that/
$ task 123 modify /from this/to that/
.RE
is broken up into several arguments, which is corrected with quotes:
.RS
$ task 123 "/from this/to that/"
$ task 123 modify "/from this/to that/"
.RE
.SH CONFIGURATION FILE AND OVERRIDE OPTIONS