Provided by: task_2.2.0-3_amd64 bug

NAME

       task-color - A color tutorial for the taskwarrior 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 taskwarrior that you want to use color.  This is the default for taskwarrior, 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 taskwarrior is ready.

AUTOMATIC MONOCHROME

       It should be mentioned that taskwarrior is aware of whether  its  output  is  going  to  a
       terminal,  or  to  a  file or through a pipe.  When taskwarrior 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?  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 show | grep '^color '
           color                        off

       it always returns 'off', no matter what the setting, because the output is being sent to a
       pipe.

       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

       Taskwarrior 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

       And an 'inverse' attribute:

           inverse red

       Taskwarrior 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
       unexpected variation across machines.  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.   Taskwarrior  will  map  red  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.

LEGEND

       Taskwarrior will show examples of all defined colors used in your .taskrc,  or  theme,  if
       you run this command:

           $ task color legend

       This  gives  you  an  example  of  each  of the colors, so you can see the effect, without
       necessarily creating a set of tasks that meet each of the rule criteria.

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 us 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 wish 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!

       The   precedence  for  the  color  rules  is  determined  by  the  configuration  variable
       'rule.precedence.color', which by default contains:

           due.today,active,blocking,blocked,overdue,due,scheduled,keyword.,project.,tag.,uda.,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.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' to  specifically
       represent missing data.

THEMES

       Taskwarrior  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 (note that your installation may use a slightly different path from the example):

              include /usr/share/task/dark-256.theme

       You can use any of the standard taskwarrior themes:

              dark-16.theme
              dark-256.theme
              dark-blue-256.theme
              dark-gray-256.theme
              dark-green-256.theme
              dark-red-256.theme
              dark-violets-256.theme
              dark-yellow-green.theme
              light-16.theme
              light-256.theme
              solarized-dark-256.theme
              solarized-light-256.theme

       You can also see how the theme will color the various tasks with the command:

           $ task color legend

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

CREDITS & COPYRIGHTS

       Copyright (C) 2006 - 2013 P. Beckingham, F. Hernandez.

       Taskwarrior      is      distributed      under      the      MIT       license.       See
       http://www.opensource.org/licenses/mit-license.php for more information.

SEE ALSO

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

       For more information regarding taskwarrior, 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 taskwarrior may be reported to the issue-tracker at
              <http://taskwarrior.org>