Documentation
- Updated the task-faq.5.in man page, various edits. - Now confrms to new syntax. - Includes new questions on multiple simultaneous installations. - Corrected answer to the xterm title question.
This commit is contained in:
Paul Beckingham
@@ -3,26 +3,26 @@
|
||||
.SH NAME
|
||||
task-faq \- A FAQ for the task(1) command line todo manager.
|
||||
|
||||
.SH DESCRIPTION
|
||||
Taskwarrior is a command line TODO list manager. It maintains a list of tasks
|
||||
that you want to do, allowing you to add/remove, and otherwise manipulate them.
|
||||
Taskwarrior has a rich list of commands that allow you to do various things with it.
|
||||
|
||||
.SH WELCOME
|
||||
Welcome to the taskwarrior FAQ. If you have would like to see a question answered
|
||||
here, please send us a note at <support@taskwarrior.org>.
|
||||
|
||||
.TP
|
||||
.B Q: When I redirect the output to a file, I lose all the colors. How do I fix this?
|
||||
A: Taskwarrior knows (or thinks it knows) when the output is not going directly
|
||||
to a terminal, and strips out all the color control characters. This is based
|
||||
on the assumption that the color control codes are not wanted in the file.
|
||||
Prevent this with the following entry in your .taskrc file:
|
||||
Taskwarrior knows when the output is not going directly to a terminal, and
|
||||
strips out all the color control characters. This is based on the assumption
|
||||
that the color control codes are not wanted in the file. Prevent this with the
|
||||
following entry in your .taskrc file:
|
||||
|
||||
_forcecolor=on
|
||||
_forcecolor=on
|
||||
|
||||
There is an additional problem with using pagers such as 'less' and 'more'.
|
||||
When using less, these options will preserve the color codes:
|
||||
or by temporarily overriding the value on the command line:
|
||||
|
||||
task ... rc._forcecolor=on
|
||||
|
||||
There is an additional problem using pagers such as 'less' and 'more', because
|
||||
color control codes are stripped. When using less, these options will preserve
|
||||
the color codes:
|
||||
|
||||
task ... | less -FrX
|
||||
|
||||
@@ -30,23 +30,23 @@ There have been problems reported with the Linux 'more' pager, which inserts
|
||||
newline characters.
|
||||
|
||||
.TP
|
||||
.B Q: How do I backup my taskwarrior data files? Where are they?
|
||||
A: Taskwarrior writes all pending tasks to the file
|
||||
.B Q: How do I backup my taskwarrior data files? Where are they?
|
||||
Taskwarrior writes all data to files in this location:
|
||||
|
||||
~/.task/pending.data
|
||||
~/.task/
|
||||
|
||||
and all completed and deleted tasks to
|
||||
You may have overridden this location with the 'data.location' configuration
|
||||
setting, in which case backup that instead. All files in this location should
|
||||
be backed up. Making sure all the files in this location are backed up, and not
|
||||
just a named subset will ensure that you properly backup future versions of
|
||||
taskwarrior, which will likely introduce more files in this location.
|
||||
|
||||
~/.task/completed.data
|
||||
|
||||
They are text files, so they can just be copied to another location for
|
||||
safekeeping. Don't forget there is also the ~/.taskrc file that contains your
|
||||
taskwarrior configuration data. To be sure, and to future-proof your backup,
|
||||
consider backing up all the files in the ~/.task directory.
|
||||
Don't forget there is also the ~/.taskrc file that contains your taskwarrior
|
||||
configuration data.
|
||||
|
||||
.TP
|
||||
.B Q: How can I separate my work tasks from my home tasks? Specifically, can I keep them completely separate?
|
||||
A: You can do this by creating an alternate .taskrc file, then using shell
|
||||
You can do this by creating an alternate .taskrc file, then using shell
|
||||
aliases. Here are example Bash commands to achieve this:
|
||||
|
||||
% cp ~/.taskrc ~/.taskrc_home
|
||||
@@ -55,11 +55,11 @@ aliases. Here are example Bash commands to achieve this:
|
||||
% alias htask="task rc:~/.taskrc_home"
|
||||
|
||||
This gives you two commands, 'wtask' and 'htask' that operate using two
|
||||
different sets of task data files.
|
||||
different sets of task data files. Bash shell functions are a good alternative.
|
||||
|
||||
.TP
|
||||
.B Q: Can I revert to a previous version of taskwarrior? How?
|
||||
A: Yes, you can revert to a previous version of task, simply by downloading an
|
||||
Yes, you can revert to a previous version of task, simply by downloading an
|
||||
older version and installing it. If you find a bug in task, then this may be the
|
||||
only way to work around the bug, until a patch release is made.
|
||||
|
||||
@@ -69,9 +69,26 @@ automatically upgrade the file but if you need to revert to a previous version
|
||||
of taskwarrior, there is the file format to consider. This is yet another good
|
||||
reason to back up your task data files!
|
||||
|
||||
.TP
|
||||
.B Q: Can I have two separate versions of taskwarrior installed? How?
|
||||
Yes, and here is one simple way to do that. Install the older version of
|
||||
taskwarrior, and then rename the 'task' binary to something like 't194' to
|
||||
reflect the version number. Then install the newer version, which will be
|
||||
named 'task'. Now you have 't194' and 'task' both installed, both using the
|
||||
same configuration and data.
|
||||
|
||||
Note that the older version will not be aware of any new configuration settings
|
||||
and so will complain about them in the 'show' command. This can be ignored.
|
||||
Likewise the newer version may complain about obsolete entries in the
|
||||
configuration.
|
||||
|
||||
Note also that the man pages will overwrite, which is why it is suggested that
|
||||
the older version be installed first, so that you benefit from improved
|
||||
documentation.
|
||||
|
||||
.TP
|
||||
.B Q: How do I build a Darwin 32bit version of task
|
||||
A: The taskwarrior packages will not work on a 32-bit OSX installation on Core
|
||||
The taskwarrior packages will not work on a 32-bit OSX installation on Core
|
||||
Duo hardware. You will need to build Taskwarrior from source, and use this
|
||||
configure command:
|
||||
|
||||
@@ -82,7 +99,7 @@ See: http://taskwarrior.org/issues/817
|
||||
|
||||
.TP
|
||||
.B Q: How do I build taskwarrior under Cygwin?
|
||||
A: Take a look at the README.build file, where the latest information on build
|
||||
Take a look at the README.build file, where the latest information on build
|
||||
issues is kept. Taskwarrior is built the same way everywhere. But under Cygwin,
|
||||
you'll need to make sure you have the following packages available first:
|
||||
|
||||
@@ -94,7 +111,7 @@ required.
|
||||
|
||||
.TP
|
||||
.B Q: Do colors work under Cygwin?
|
||||
A: They do, but only in a limited way. You can use regular foreground colors
|
||||
They do, but only in a limited way. You can use regular foreground colors
|
||||
(black, red, green ...) and you can regular background colors (on_black, on_red,
|
||||
on_green ...), but underline and bold are not supported.
|
||||
|
||||
@@ -108,7 +125,7 @@ you can use.
|
||||
Note that if you install the 'mintty' shell in Cygwin, then you can use 256
|
||||
colors.
|
||||
|
||||
See the 'man task-color' for more details on which colors can be used.
|
||||
See the 'man task-color' page for more details on which colors can be used.
|
||||
|
||||
.TP
|
||||
.B Q: Where does taskwarrior store the data?
|
||||
@@ -128,24 +145,24 @@ for you, so it is probably best to leave those files alone.
|
||||
If you delete (or rename) your .taskrc file, taskwarrior will offer to create a
|
||||
default one for you. Another way to do this is with the command:
|
||||
|
||||
$ task rc:new-file version
|
||||
task rc:new-file version
|
||||
|
||||
Taskwarrior will create 'new-file' if it doesn't already exist. There will not
|
||||
be much in it though - taskwarrior relies heavily on default values, which can
|
||||
be seen with this command:
|
||||
|
||||
$ task show
|
||||
task show
|
||||
|
||||
which lists all the currently known settings. If you have just created
|
||||
new-file, then this command lists only the defaults.
|
||||
This lists all the currently known settings. If you have just created a
|
||||
new file, then this command lists only the defaults.
|
||||
|
||||
Note that this is a good way to learn about new configuration settings,
|
||||
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 all the files in your ~/.task directory, and probably
|
||||
your ~/.taskrc file too.
|
||||
Yes you do, like all your other files. You should back up all the files in your
|
||||
~/.task directory, and your ~/.taskrc file too.
|
||||
|
||||
.TP
|
||||
.B Q: Can I share my tasks between different machines?
|
||||
@@ -158,7 +175,7 @@ folder, by modifying the:
|
||||
configuration variable. Check out DropBox at http://www.dropbox.com.
|
||||
|
||||
.TP
|
||||
.B Q: I don't like dropbox. Is there another way to synchronize my tasks?
|
||||
.B Q: I don't want to use dropbox. Is there another way to synchronize my tasks?
|
||||
Of course. Especially if you want to modify tasks offline on both machines and
|
||||
synchronize them later on. For this purpose there is a 'merge' command which is
|
||||
is able to insert the modifications you made to one of your task databases into
|
||||
@@ -166,8 +183,8 @@ a second database.
|
||||
|
||||
Here is a basic example of the procedure:
|
||||
|
||||
$ task merge ssh://user@myremotehost/~/.task/
|
||||
$ task push ssh://user@myremotehost/~/.task/
|
||||
task merge ssh://user@myremotehost/.task/
|
||||
task push ssh://user@myremotehost/.task/
|
||||
|
||||
The first command fetches the undo.data file from the remote system, reads the
|
||||
changes made and updates the local database. When this merge command completes,
|
||||
@@ -184,13 +201,15 @@ separator '---'. The simplest way is to simply delete the undo.data file. Note
|
||||
that it does not slow down taskwarrior, because it is never read until you want
|
||||
to undo. Otherwise taskwarrior only appends to the file.
|
||||
|
||||
It is not recommended that you delete the undo.data file.
|
||||
|
||||
.TP
|
||||
.B Q: How do I know whether my terminal support 256 colors?
|
||||
You will need to make sure your TERM environment variable is set to xterm-color,
|
||||
otherwise the easiest way is to just try it! With version 1.9 or later, you
|
||||
simply run
|
||||
|
||||
$ task color
|
||||
task color
|
||||
|
||||
and a full color palette is displayed. If you see only 8 or 16 colors, perhaps
|
||||
with those colors repeated, then your terminal does not support 256 colors.
|
||||
@@ -206,22 +225,9 @@ See the task-color(5) man page for an in-depth explanation of the color rules.
|
||||
|
||||
.TP
|
||||
.B Q: How can I make taskwarrior put the command in the terminal window title?
|
||||
You cannot. But you can make the shell do it, and you can make the shell
|
||||
call the task program. Here is a Bash script that does this:
|
||||
Just set the following value in your .taskrc file:
|
||||
|
||||
#! /bin/bash
|
||||
|
||||
printf "\\033]0;task $*\a"
|
||||
/usr/local/bin/task $*
|
||||
|
||||
You just need to run the script, and let the script run task. Here is a Bash
|
||||
function that does the same thing:
|
||||
|
||||
t ()
|
||||
{
|
||||
printf "\\033]0;task $*\a"
|
||||
/usr/local/bin/task $*
|
||||
}
|
||||
xterm.title=on
|
||||
|
||||
.TP
|
||||
.B Q: Taskwarrior searches in a case-sensitive fashion - can I change that?
|
||||
@@ -231,13 +237,13 @@ You can. Just set the following value in your .taskrc file:
|
||||
|
||||
This will affect searching for keywords:
|
||||
|
||||
$ task list Document
|
||||
task Document list
|
||||
|
||||
taskwarrior will perform a caseless search in the description and any
|
||||
annotations for the keyword 'Document'. It also affects description and
|
||||
annotation substitutions:
|
||||
|
||||
$ task 1 /teh/the/
|
||||
task 1 modify /teh/the/
|
||||
|
||||
The pattern on the left will now be a caseless search term.
|
||||
|
||||
@@ -252,10 +258,10 @@ incorrectly, because there are more digits.
|
||||
When you run a report (such as "list"), the numbers are assigned before display.
|
||||
For example, you can do this:
|
||||
|
||||
$ task list
|
||||
$ task 12 done
|
||||
$ task add Pay the rent
|
||||
$ task 31 delete
|
||||
task list
|
||||
task 12 done
|
||||
task add Pay the rent
|
||||
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
|
||||
@@ -268,16 +274,21 @@ efficiency.
|
||||
|
||||
.TP
|
||||
.B Q: How do I list tasks that are either priority 'H' or 'M', but not 'L'?
|
||||
Taskwarrior's filters are all combined with and implicit logical AND operator, so
|
||||
if you were to try this:
|
||||
Taskwarrior's filters are all by default combined with and implicit logical AND
|
||||
operator, so if you were to try this:
|
||||
|
||||
$ task list priority:H priority:M
|
||||
task priority:H priority:M list
|
||||
|
||||
There would be no results, because the priority could not simultaneously be 'H'
|
||||
AND 'M'. What is required is some way to use OR instead of an AND operator. The
|
||||
solution is to invert the filter in this way:
|
||||
AND 'M'. Instead, you have a choice. You can do this:
|
||||
|
||||
$ task list priority.not:L priority.any:
|
||||
task '(priority:H or priority:M)' list
|
||||
|
||||
Note that the quotes are one way of escaping the ( ) characters that are
|
||||
otherwise interpreted by the shell before taskwarrior sees them. You can also
|
||||
do this:
|
||||
|
||||
task priority.not:L priority.any: list
|
||||
|
||||
This filter states that the priority must not be 'L', AND there must be a
|
||||
priority assigned. This filter then properly lists tasks that are 'H' or 'M',
|
||||
@@ -293,21 +304,21 @@ to construct task filters.
|
||||
Taskwarrior now has a 'denotate' command to remove annotations. Here is an
|
||||
example:
|
||||
|
||||
$ task add Original task
|
||||
$ task 1 annotate foo
|
||||
$ task 1 annotate bar
|
||||
$ task 1 annotate foo bar
|
||||
task add Original task
|
||||
task 1 annotate foo
|
||||
task 1 annotate bar
|
||||
task 1 annotate foo bar
|
||||
|
||||
Now to delete the first annotation, use:
|
||||
|
||||
$ task 1 denotate foo
|
||||
task 1 denotate foo
|
||||
|
||||
This takes the fragment 'foo' and compares it to each of the annotations. In
|
||||
this example, it will remove the first annotation, not the third, because it is
|
||||
an exact match. If there are no exact matches, it will remove the first
|
||||
non-exact match:
|
||||
|
||||
$ task 1 denotate ar
|
||||
task 1 denotate ar
|
||||
|
||||
This will remove the second annotation - the first non-exact match.
|
||||
|
||||
@@ -333,14 +344,11 @@ There are lots of ways. Here are some:
|
||||
- Contribute to our Wiki
|
||||
- Suggest features
|
||||
- Write unit tests
|
||||
- Write add-on scripts, and share them
|
||||
- Fix bugs
|
||||
|
||||
.SH "CREDITS & COPYRIGHTS"
|
||||
Taskwarrior was written by P. Beckingham <paul@beckingham.net>.
|
||||
.br
|
||||
Copyright (C) 2006 \- 2011 P. Beckingham
|
||||
|
||||
This man page was originally written by P. Beckingham.
|
||||
Copyright (C) 2006 \- 2011 P. Beckingham, F. Hernandez.
|
||||
|
||||
Taskwarrior is distributed under the GNU General Public License. See
|
||||
http://www.gnu.org/licenses/gpl-2.0.txt for more information.
|
||||
|
||||
Reference in New Issue
Block a user