1task-color(5) User Manuals task-color(5)
2
6 task-color - A color tutorial for the task(1) command line todo man‐
7 ager.
8
11 The first thing you need is a terminal program that supports color.
12 All terminal programs support color, but only a few support lots of
13 colors. First tell your terminal program to use color by specifying
14 the TERM environment variable like this:
15 TERM=xterm-color
17 In this example, xterm-color is used - a common value, and one that
19 doesn't require that you use xterm. This works for most setups. This
20 setting belongs in your shell profile (~/.bash_profile, ~/.bashrc,
21 ~/.cshrc etc, depending on which shell you use). If this is a new set‐
22 ting, you will need to either run that profile script, or close and
23 reopen the terminal window (which does the same thing).
24 Now tell taskwarrior that you want to use color. This is the default
26 for taskwarrior, so the following step may be unnecessary.
27 $ task config color on
29 This command will make sure there is an entry in your ~/.taskrc file
31 that looks like:
32 color=on
34 Now taskwarrior is ready.
36
39 It should be mentioned that taskwarrior is aware of whether its output
40 is going to a terminal, or to a file or through a pipe. When taskwar‐
41 rior output goes to a terminal, color is desirable, but consider the
42 following command:
43 $ task list > file.txt
45 Do we really want all those color control codes in the file? Taskwar‐
47 rior assumes that you do not, and temporarily sets color to 'off' while
48 generating the output. This explains the output from the following
49 command:
50 $ task config | grep '^color '
52 color off
53 it always returns 'off', no matter what the setting.
55 The reason is that the taskwarrior output gets piped into grep, and the
57 color is disabled. If you wanted those color codes, you can override
58 this behavior by setting the _forcecolor variable to on, like this:
59 $ task config _forcecolor on
61 $ task config | grep '^color '
62 color on
63 or by temporarily overriding it like this:
65 $ task rc._forcecolor=on config | grep '^color '
67 color on
68
71 Taskwarrior has a 'color' command that will show all the colors it is
72 capable of displaying. Try this:
73 $ task color
75 The output cannot be replicated here in a man page, but you should see
77 a set of color samples. How many you see depends on your terminal pro‐
78 gram's ability to render them.
79 You should at least see the Basic colors and Effects - if you do, then
81 you have 16-color support. If your terminal supports 256 colors,
82 you'll know it!
83
86 The basic color support is provided through named colors:
87 black, red, blue, green, magenta, cyan, yellow, white
89 Foreground color (for text) is simply specified as one of the above
91 colors, or not specified at all to use the default terminal text color.
92 Background color is specified by using the word 'on', and one of the
94 above colors. Some examples:
95 green # green text, default background color
97 green on yellow # green text, yellow background
98 on yellow # default text color, yellow background
99 These colors can be modified further, by making the foreground bold, or
101 by making the background bright. Some examples:
102 bold green
104 bold white on bright red
105 on bright cyan
106 The order of the words is not important, so the following are equiva‐
108 lent:
109 bold green
111 green bold
112 But the 'on' is important - colors before the 'on' are foreground, and
114 colors after 'on' are background.
115 There is an additional 'underline' attribute that may be used:
117 underline bright red on black
119 Taskwarrior has a command that helps you visualize these color combina‐
121 tions. Try this:
122 $ task color underline bright red on black
124 You can use this command to see how the various color combinations
126 work. You will also see some sample colors displayed, like the ones
127 above, in addition to the sample requested.
128 Some combinations look very nice, some look terrible. Different termi‐
130 nal programs do implement slightly different versions of 'red', for
131 example, so you may see some unwanted variation due to the program.
132 The brightness of your display is also a factor.
133
136 Using 256 colors follows the same form, but the names are different,
137 and some colors can be referenced in different ways. First there is by
138 color ordinal, which is like this:
139 color0
141 color1
142 color2
143 ...
144 color255
145 This gives you access to all 256 colors, but doesn't help you much.
147 This range is a combination of 8 basic colors (color0 - color7), then 8
148 brighter variations (color8 - color15). Then a block of 216 colors
149 (color16 - color231). Then a block of 24 gray colors (color232 -
150 color255).
151 The large block of 216 colors (6x6x6 = 216) represents a color cube,
153 which can be addressed via RGB values from 0 to 5 for each component
154 color. A value of 0 means none of this component color, and a value of
155 5 means the most intense component color. For example, a bright red is
156 specified as:
157 rgb500
159 And a darker red would be:
161 rgb300
163 Note that the three digits represent the three component values, so in
165 this example the 5, 0 and 0 represent red=5, green=0, blue=0. Combin‐
166 ing intense red with no green and no blue yields red. Similarly, blue
167 and green are:
168 rgb005
170 rgb050
171 Another example - bright yellow - is a mix of bright red and bright
173 green, but no blue component, so bright yellow is addressed as:
174 rgb550
176 A soft pink would be addressed as:
178 rgb515
180 See if you agree, by running:
182 $ task color black on rgb515
184 You may notice that the large color block is represented as 6 squares.
186 All colors in the first square have a red value of 0. All colors in
187 the 6th square have a red value of 5. Within each square, blue ranges
188 from 0 to 5 left to right, and within each square green ranges from 0
189 to 5, top to bottom. This scheme takes some getting used to.
190 The block of 24 gray colors can also be accessed as gray0 - gray23, in
192 a continuous ramp from black to white.
193
196 If you specify 16-colors, and view on a 256-color terminal, no problem.
197 If you try the reverse, specifying 256-colors and viewing on a 16-color
198 terminal, you will be disappointed, perhaps even appalled.
199 There is some limited color mapping - for example, if you were to spec‐
201 ify this combination:
202 red on gray3
204 you are mixing a 16-color and 256-color specification. Taskwarrior
206 will map red to color1, and proceed. Note that red and color1 are not
207 quite the same.
208 Note also that there is no bold or bright attributes when dealing with
210 256 colors, but there is still underline available.
211
214 Taskwarrior will show examples of all defined colors used in your
215 .taskrc, or theme, if you run this command:
216 $ task color legend
218 This gives you an example of each of the colors, so you can see the
220 effect, without necessarily creating a set of tasks that meet each of
221 the rule criteria.
222
225 Taskwarrior supports colorization rules. These are configuration val‐
226 ues that specify a color, and the conditions under which that color is
227 used. By example, let's add a few tasks:
228 $ task add project:Home priority:H pay the bills (1)
230 $ task add project:Home clean the rug (2)
231 $ task add project:Garden clean out the garage (3)
232 We can add a color rule that uses a blue background for all tasks in
234 the Home project:
235 $ task config color.project.Home on blue
237 We use quotes around "on blue" because there are two words, but they
239 represent one value in the .taskrc file. Now suppose we which to use a
240 bold yellow text color for all cleaning work:
241 $ task config color.keyword.clean bold yellow
243 Now what happens to task 2, which belongs to project Home (blue back‐
245 ground), and is also a cleaning task (bold yellow foreground)? The
246 colors are combined, and the task is shown as "bold yellow on blue".
247 Color rules can be applied by project and description keyword, as
249 shown, and also by priority (or lack of priority), by active status, by
250 being due or overdue, by being tagged, or having a specific tag (per‐
251 haps the most useful rule) or by being a recurring task.
252 It is possible to create a very colorful mix of rules. With 256-color
254 support, those colors can be made subtle, and complementary, but with‐
255 out care, this can be a visual mess. Beware!
256 The precedence for the color rules is determined by the configuration
258 variable 'rule.precedence.color', which by default contains:
259 due.today,active,blocked,overdue,due,keyword,project,tag,recur‐
261 ring,pri,tagged
262 These are just the color rules with the 'color.' prefix removed. The
264 rule 'color.due.today' is the highest precedence, and 'color.tagged' is
265 the lowest.
266 The keyword rule shown here as 'keyword' corresponds to a wildcard pat‐
268 tern, meaning 'color.keyword.*', or in other words all the keyword
269 rules. Similarly for the 'color.tag.*' and 'color.project.*' rules.
270 There is also 'color.project.none', 'color.tag.none' and
272 'color.pri.none'.
273
276 Taskwarrior supports themes. What this really means is that with the
277 ability to include other files into the .taskrc file, different sets of
278 color rules can be included.
279 To get a good idea of what a color theme looks like, try adding this
281 entry to your .taskrc file:
282 include /usr/local/share/doc/task/rc/dark-256.theme
284 You can use any of the standard taskwarrior themes:
286 light-16.theme
288 light-256.theme
289 dark-16.theme
290 dark-256.theme
291 dark-red-256.theme
292 dark-green-256.theme
293 dark-blue-256.theme
294 You can also see how the theme will color the various tasks with the
296 command:
297 $ task color legend
299 Better yet, create your own, and share it. We will gladly host the
301 theme file on <http://taskwarrior.org>.
302
305 Taskwarrior was written by P. Beckingham <paul@beckingham.net>.
306 Copyright (C) 2006 - 2011 P. Beckingham
307 This man page was originally written by Paul Beckingham.
309 Taskwarrior is distributed under the GNU General Public License. See
311 http://www.gnu.org/licenses/gpl-2.0.txt for more information.
312
315 task(1), taskrc(5), task-faq(5), task-tutorial(5), task-sync(5)
316 For more information regarding taskwarrior, the following may be refer‐
318 enced:
319 The official site at
322 <http://taskwarrior.org>
323 The official code repository at
326 <git://tasktools.org/task.git/>
327 You can contact the project by writing an email to
330 <support@taskwarrior.org>
331
334 Bugs in taskwarrior may be reported to the issue-tracker at
335 <http://taskwarrior.org>
336task 1.9.4 2011-03-03 task-color(5)