taskwarrior/doc/man/task-faq.5

.TH task-faq 5 2010-11-08 "task 1.9.4" "User Manuals"

.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:

   _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:

    task ... | less -FrX

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

    ~/.task/pending.data

and all completed and deleted tasks to

    ~/.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.

.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
aliases. Here are example Bash commands to achieve this:

    % cp ~/.taskrc ~/.taskrc_home
    % (now edit .taskrc_home to change the value of data.location)
    % alias wtask="task" 
    % alias htask="task rc:~/.taskrc_home" 

This gives you two commands, 'wtask' and 'htask' that operate using two
different sets of task data files.

.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
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.

Note that it is possible that the taskwarrior file format will change. For
example, the format changed between versions 1.5.0 and 1.6.0. Taskwarrior will
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: How do I build taskwarrior under Cygwin?
A: 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:

    gcc
    make

The gcc and make packages allow you to compile the code, and are therefore
required.

.TP
.B Q: Do colors work under Cygwin?
A: 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.

If you run the command:

    % task colors

Taskwarrior will display all the colors it can use, and you will see which ones
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.

.TP
.B Q: Where does taskwarrior store the data?
By default, taskwarrior creates a .taskrc file in your home directory and
populates it with defaults.  Taskwarrior also creates a .task directory in your
home directory and puts data files there.

.TP
.B Q: Can I edit that data?
Of course you can.  It is a simple text file, and looks somewhat like the JSON
format, and if you are careful not to break the format, there is no reason not
to edit it.  But taskwarrior provides a rich command set to do that manipulation
for you, so it is probably best to leave those files alone.

.TP
.B Q: How do I restore my .taskrc file to defaults?
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

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

which lists all the currently known settings.  If you have just created
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 your ~/.task directory, and probably your ~/.taskrc
file too.

.TP
.B Q: Can I share my tasks between different machines?
Yes, you can.  Most people have success with a DropBox - a free and secure file
synching tool.  Simply configure taskwarrior to store it's data in a dropbox
folder, by modifying the:

    data.location=...

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?
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
a second database.

Here is a basic example of the procedure:

    $ 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,
you should copy all the local .data files to the remote system either by using
the push command explicitly or by activating the merge.autopush feature in the 
~/.taskrc file. This way you ensure that both systems are fully synchronized.

.TP
.B Q: The undo.data file gets very large - do I need it?
You need it if you want the undo capability, or the merge capability mentioned
above.  But if it gets large, you can certainly truncate it to save space, just
be careful to delete lines from the top of the file, up to and including a
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.

.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

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.

See the task-color(5) man page for more details.

.TP
.B Q: How do I make use of all these colors?
Use one of our provided color themes, or create your own - after all, they are
just collections of color settings.

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:

    #! /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 $*
    }

.TP
.B Q: Taskwarrior searches in a case-sensitive fashion - can I change that?
You can.  Just set the following value in your .taskrc file:

    search.case.sensitive=no

This will affect searching for keywords:

    $ task list Document

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/

The pattern on the left will now be a caseless search term.

.TP
.B Q: Why do the ID numbers change?
Taskwarrior does this to always show you the smallest numbers it can.  The idea
is that if your tasks are numbered 1 - 33, for example, those are easy to type
in.  If instead task kept a rolling sequence number, after a while your tasks
might be numbered 481 - 513, which makes it more likely to enter one
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 do 12
    $ task add Pay the rent
    $ task delete 31

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
a report is run, which moves the deleted and completed tasks from the
pending.data file to the completed.data file.  This keeps the pending tasks file
small, and therefore keeps taskwarrior fast.  The completed data file is the one
that grows unbounded with use, but that one isn't accessed as much, so it
doesn't matter as much.  So in all, the ID number resequencing is about
efficiency.

.TP
.B Q: How do I list tasks that are either priority 'H' or 'M', but not 'L'?
Taskwarriors filters are all combined with and implicit logical AND operator, so
if you were to try this:

    $ task list priority:H priority:M

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:

    $ task list priority.not:L priority.any:

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',
because the two logical restrictions are not mutually exclusive as in the
original filter.

Some of you may be familiar with DeMorgan's laws of formal logic that relate
the AND and OR operators in terms of each other via negation, which can be used
to construct task filters.

.TP
.B Q: How do I delete an annotation?
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

Now to delete the first annotation, use:

    $ 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

This will remove the second annotation - the first non-exact match.

.TP
.B Q: Does task support searching using regular expressions?
Yes, taskwarrior supports IEEE Std 1003.2 (POSIX.2) regular expressions, but not
by default.  You must enable this feature with the following command:

    $ task config regex on

Once enabled, all searches are considered regular expressions, for example:

    $ task list ^the

will list all tasks whose description or annotations start with "the".
Substitutions also support regular expressions:

    $ task 1 /^the/The/

Note that regular expressions work in conjunction with the
.B search.case.sensitive
configuration setting.

.TP
.B Q: Why Lua as an extension language?
Lua has many positive attributes:

- Lua is written using tight, fast, standard C
- Lua is a breeze to integrate into any product
- The Lua source code is beautifully written
- Lua is a small language

Guile, Scheme and Neko were also considered.

.TP
.B Q: How can I help?
There are lots of ways.  Here are some:

 - Provide feedback on what works, what does not
 - Tell us how task does or does not fit your workflow
 - Tell people about task
 - Report bugs when you see them
 - Contribute to our Wiki
 - Suggest features
 - Write unit tests
 - 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.

Taskwarrior is distributed under the GNU General Public License.  See
http://www.gnu.org/licenses/gpl-2.0.txt for more information.

.SH SEE ALSO
.BR task(1),
.BR taskrc(5),
.BR task-tutorial(5),
.BR task-color(5),
.BR task-sync(5)

For more information regarding task, the following may be referenced:

.TP
The official site at
<http://taskwarrior.org>

.TP
The official code repository at
<git://tasktools.org/task.git/>

.TP
You can contact the project by writing an email to
<support@taskwarrior.org>

.SH REPORTING BUGS
.TP
Bugs in taskwarrior may be reported to the issue-tracker at
<http://taskwarrior.org>