Provided by: task_1.9.2-1_i386 bug

NAME

       task-color  -  A  color  tutorial  for  the  task(1)  command line todo
       manager.

SETUP

       The first thing you need is a terminal  program  that  supports  color.
       All  terminal  programs  support  color, but only a few support lots of
       colors.  First tell your terminal program to use  color  by  specifying
       the TERM environment variable like this:

           TERM=xterm-color

       In  this  example,  xterm-color  is used - a common value, and one that
       doesn't require that you use xterm.  This works for most setups.   This
       setting  belongs  in  your  shell  profile (~/.bash_profile, ~/.bashrc,
       ~/.cshrc etc, depending on which shell you use).   If  this  is  a  new
       setting,  you will need to either run that profile script, or close and
       reopen the terminal window (which does the same thing).

       Now tell task that you want to use color.   This  is  the  default  for
       task, so the following step may be unnecessary.

           $ task config color on

       This  command  will  make sure there is an entry in your ~/.taskrc file
       that looks like:

           color=on

       Now task is ready.

AUTOMATIC MONOCHROME

       It should be mentioned that task is aware of  whether  it's  output  is
       going  to a terminal, or to a file or through a pipe.  When task output
       goes to a terminal, color is  desirable,  but  consider  the  following
       command:

           $ task list > file.txt

       Do  we  really  want  all  those color control codes in the file?  Task
       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 '
           color                        off

       it always returns 'off', no matter what the setting.

       The reason is that the task 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:

           $ task config _forcecolor on
           $ task config | grep '^color '
           color                        on

       or by temporarily overriding it like this:

           $ task rc._forcecolor=on config | grep '^color '
           color                        on

AVAILABLE COLORS

       Task has a 'color' command that will show all the colors it is  capable
       of displaying.  Try this:

           $ task color

       The  output cannot be replicated here in a man page, but you should see
       a set of color samples.  How many you  see  depends  on  your  terminal
       program's ability to render them.

       You  should at least see the Basic colors and Effects - if you do, then
       you have 16-color support.   If  your  terminal  supports  256  colors,
       you'll know it!

16-COLOR SUPPORT

       The basic color support is provided through named colors:

           black, red, blue, green, magenta, cyan, yellow, white

       Foreground  color  (for  text)  is simply specified as one of the above
       colors, or not specified at all to use the default terminal text color.

       Background  color  is  specified by using the word 'on', and one of the
       above colors.  Some examples:

           green                 # green text, default background color
           green on yellow       # green text, yellow background
           on yellow             # default text color, yellow background

       These colors can be modified further, by making the foreground bold, or
       by making the background bright.  Some examples:

           bold green
           bold white on bright red
           on bright cyan

       The  order  of  the  words  is  not  important,  so  the  following are
       equivalent:

           bold green
           green bold

       But the 'on' is important - colors before the 'on' are foreground,  and
       colors after 'on' are background.

       There is an additional 'underline' attribute that may be used:

           underline bright red on black

       Task  has  a command that helps you visualize these color combinations.
       Try this:

           $ task color underline bright red on black

       You can use this command to see  how  the  various  color  combinations
       work.   You  will  also see some sample colors displayed, like the ones
       above, in addition to 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 display is also a factor.

256-COLOR SUPPORT

       Using  256  colors  follows the same form, but the names are different,
       and some colors can be referenced in different ways.  First there is by
       color ordinal, which is like this:

           color0
           color1
           color2
           ...
           color255

       This  gives  you  access  to all 256 colors, but doesn't help you much.
       This range is a combination of 8 basic colors (color0 - color7), then 8
       brighter  variations  (color8  -  color15).  Then a block of 216 colors
       (color16 - color231).  Then a block  of  24  gray  colors  (color232  -
       color255).

       The  large  block  of 216 colors (6x6x6 = 216) represents a color cube,
       which can be addressed via RGB values from 0 to 5  for  each  component
       color.  A value of 0 means none of this component color, and a value of
       5 means the most intense component color.  For example, a bright red is
       specified as:

           rgb500

       And a darker red would be:

           rgb300

       Note  that the three digits represent the three component values, so in
       this  example  the  5,  0  and  0  represent  red=5,  green=0,  blue=0.
       Combining intense red with no green and no blue yields red.  Similarly,
       blue and green are:

           rgb005
           rgb050

       Another example - bright yellow - is a mix of  bright  red  and  bright
       green, but no blue component, so bright yellow is addressed as:

           rgb550

       A soft pink would be addressed as:

           rgb515

       See if you agree, by running:

           $ task color black on rgb515

       You  may notice that the large color block is represented as 6 squares.
       All colors in the first square have a red value of 0.   All  colors  in
       the  6th square have a red value of 5.  Within each square, blue ranges
       from 0 to 5 left to right, and within each square green ranges  from  0
       to 5, top to bottom.  This scheme takes some getting used to.

       The  block of 24 gray colors can also be accessed as gray0 - gray23, in
       a continuous ramp from black to white.

MIXING 16- AND 256-COLORS

       If you specify 16-colors, and view on a 256-color terminal, no problem.
       If you try the reverse, specifying 256-colors and viewing on a 16-color
       terminal, you will be disappointed, perhaps even appalled.

       There is some limited color mapping -  for  example,  if  you  were  to
       specify this combination:

           red on gray3

       you  are  mixing a 16-color and 256-color specification.  Task will map
       red to color1, and proceed.  Note that red and color1 are not quite the
       same.

       Note  also that there is no bold or bright attributes when dealing with
       256 colors, but there is still underline available.

RULES

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

           $ task add project:Home priority:H pay the bills               (1)
           $ task add project:Home            clean the rug               (2)
           $ task add project:Garden          clean out the garage        (3)

       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

       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

       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 the task is shown as "bold yellow on blue".

       Color  rules  can  be  applied  by  project and description keyword, as
       shown, and also by priority (or lack of priority), by active status, by
       being  due  or  overdue,  by  being  tagged,  or  having a specific tag
       (perhaps the most useful rule) or by being a recurring task.

       It is possible to create a very colorful mix of rules.  With  256-color
       support,  those  colors  can  be  made  subtle,  and complementary, but
       without care, this can be a visual mess.  Beware!

THEMES

       Task supports themes.  What this really means is that with the  ability
       to  include  other files into the .taskrc file, different sets of color
       rules can be included.

       To get a good idea of what a color theme looks like,  try  adding  this
       entry to your .taskrc file:

              include /usr/local/share/doc/task/rc/dark-256.theme

       You can use any of the standard task themes:

              light-16.theme
              light-256.theme
              dark-16.theme
              dark-256.theme
              dark-red-256.theme
              dark-green-256.theme
              dark-blue-256.theme

       Better  yet,  create  your  own, and share it.  We will gladly host the
       theme file on <http://taskwarrior.org>.

CREDITS & COPYRIGHTS

       task was written by P. Beckingham <paul@beckingham.net>.
       Copyright (C) 2006 - 2010 P. Beckingham

       This man page was originally written by Paul Beckingham.

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

SEE ALSO

       task(1), taskrc(5), task-faq(5) task-tutorial(5)

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

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

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

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

REPORTING BUGS

       Bugs in task may be reported to the issue-tracker at
              <http://taskwarrior.org>