1task-color(5) User Manuals task-color(5)
2
6 task-color - A color tutorial for the Taskwarrior command line todo
7 manager.
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 show | grep '^color '
52 color off
53 it always returns 'off', no matter what the setting, because the output
55 is being sent to a pipe.
56 If you wanted those color codes, you can override this behavior by set‐
58 ting 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 bold red on black
119 And an 'inverse' attribute:
121 inverse red
123 Taskwarrior has a command that helps you visualize these color combina‐
125 tions. Try this:
126 $ task color underline bold red on black
128 You can use this command to see how the various color combinations
130 work. You will also see some sample colors displayed, like the ones
131 above, in addition to the sample requested.
132 Some combinations look very nice, some look terrible. Different termi‐
134 nal programs do implement slightly different versions of 'red', for
135 example, so you may see some unexpected variation across machines. The
136 brightness of your display is also a factor.
137
140 Using 256 colors follows the same form, but the names are different,
141 and some colors can be referenced in different ways. First there is by
142 color ordinal, which is like this:
143 color0
145 color1
146 color2
147 ...
148 color255
149 This gives you access to all 256 colors, but doesn't help you much.
151 This range is a combination of 8 basic colors (color0 - color7), then 8
152 brighter variations (color8 - color15). Then a block of 216 colors
153 (color16 - color231). Then a block of 24 gray colors (color232 -
154 color255).
155 The large block of 216 colors (6x6x6 = 216) represents a color cube,
157 which can be addressed via RGB values from 0 to 5 for each component
158 color. A value of 0 means none of this component color, and a value of
159 5 means the most intense component color. For example, a bright red is
160 specified as:
161 rgb500
163 And a darker red would be:
165 rgb300
167 Note that the three digits represent the three component values, so in
169 this example the 5, 0 and 0 represent red=5, green=0, blue=0. Combin‐
170 ing intense red with no green and no blue yields red. Similarly, blue
171 and green are:
172 rgb005
174 rgb050
175 Another example - bright yellow - is a mix of bright red and bright
177 green, but no blue component, so bright yellow is addressed as:
178 rgb550
180 A soft pink would be addressed as:
182 rgb515
184 See if you agree, by running:
186 $ task color black on rgb515
188 You may notice that the large color block is represented as 6 squares.
190 All colors in the first square have a red value of 0. All colors in
191 the 6th square have a red value of 5. Within each square, blue ranges
192 from 0 to 5 left to right, and within each square green ranges from 0
193 to 5, top to bottom. This scheme takes some getting used to.
194 The block of 24 gray colors can also be accessed as gray0 - gray23, in
196 a continuous ramp from black to white.
197
200 If you specify 16-colors, and view on a 256-color terminal, no problem.
201 If you try the reverse, specifying 256-colors and viewing on a 16-color
202 terminal, you will be disappointed, perhaps even appalled.
203 There is some limited color mapping - for example, if you were to spec‐
205 ify this combination:
206 red on gray3
208 you are mixing a 16-color and 256-color specification. Taskwarrior
210 will map red to color1, and proceed. Note that red and color1 are not
211 quite the same tone.
212 Note also that there is no bold or bright attributes when dealing with
214 256 colors, but there is still underline available.
215
218 Taskwarrior will show examples of all defined colors used in your
219 .taskrc, or theme, if you run this command:
220 $ task color legend
222 This gives you an example of each of the colors, so you can see the
224 effect, without necessarily creating a set of tasks that meet each of
225 the rule criteria.
226
229 Taskwarrior supports colorization rules. These are configuration val‐
230 ues that specify a color, and the conditions under which that color is
231 used. By example, let us add a few tasks:
232 $ task add project:Home priority:H pay the bills (1)
234 $ task add project:Home clean the rug (2)
235 $ task add project:Garden clean out the garage (3)
236 We can add a color rule that uses a blue background for all tasks in
238 the Home project:
239 $ task config color.project.Home 'on blue'
241 We use quotes around 'on blue' because there are two words, but they
243 represent one value in the .taskrc file. Now suppose we wish to use a
244 bold yellow text color for all cleaning work:
245 $ task config color.keyword.clean 'bold yellow'
247 Now what happens to task 2, which belongs to project Home (blue back‐
249 ground), and is also a cleaning task (bold yellow foreground)? The
250 colors are combined, and the task is shown as "bold yellow on blue".
251 Color rules can be applied by project and description keyword, as
253 shown, and also by priority (or lack of priority), by active status, by
254 being due or overdue, by being tagged, or having a specific tag (per‐
255 haps the most useful rule) or by being a recurring task.
256 It is possible to create a very colorful mix of rules. With 256-color
258 support, those colors can be made subtle, and complementary, but with‐
259 out care, this can be a visual mess. Beware!
260 In such cases, consider using the 'rule.color.merge=no' option to dis‐
262 able the color blending.
263 The precedence for the color rules is determined by the configuration
265 variable 'rule.precedence.color', which by default contains:
266 deleted,completed,active,keyword.,tag.,project.,overdue,sched‐
268 uled,due.today,due,blocked,blocking,recurring,tagged,uda.
269 These are just the color rules with the 'color.' prefix removed. The
271 rule 'color.due.today' is the highest precedence, and 'color.deleted'
272 is the lowest.
273 The keyword rule shown here as 'keyword.' corresponds to a wildcard
275 pattern, meaning 'color.keyword.*', or in other words all the keyword
276 rules. Similarly for the 'color.tag.*' and 'color.project.*' rules.
277 There is also 'color.project.none', 'color.tag.none' and
279 'color.pri.none' to specifically represent missing data.
280
283 Taskwarrior supports themes. What this really means is that with the
284 ability to include other files into the .taskrc file, different sets of
285 color rules can be included.
286 To get a good idea of what a color theme looks like, try adding this
288 entry to your .taskrc file (note that your installation may use a
289 slightly different path from the example):
290 include /usr/share/task/dark-256.theme
292 You can use any of the standard Taskwarrior themes:
294 dark-16.theme
296 dark-256.theme
297 dark-blue-256.theme
298 dark-gray-256.theme
299 dark-green-256.theme
300 dark-red-256.theme
301 dark-violets-256.theme
302 dark-yellow-green.theme
303 light-16.theme
304 light-256.theme
305 solarized-dark-256.theme
306 solarized-light-256.theme
307 dark-default-16.theme
308 dark-gray-blue-256.theme
309 no-color.theme
310 Bear in mind that if you are using a terminal with a dark background,
312 you will see better results using a dark theme.
313 You can also see how the theme will color the various tasks with the
315 command:
316 $ task color legend
318 Better yet, create your own, and share it. We will gladly host the
320 theme file on <http://taskwarrior.org>.
321
324 Copyright (C) 2006 - 2016 P. Beckingham, F. Hernandez.
325 Taskwarrior is distributed under the MIT license. See http://www.open‐
327 source.org/licenses/mit-license.php for more information.
328
331 task(1), taskrc(5), task-sync(5)
332 For more information regarding Taskwarrior, the following may be refer‐
334 enced:
335 The official site at
338 <http://taskwarrior.org>
339 The official code repository at
342 <https://git.tasktools.org/scm/tm/task.git>
343 You can contact the project by writing an email to
346 <support@taskwarrior.org>
347
350 Bugs in Taskwarrior may be reported to the issue-tracker at
351 <http://taskwarrior.org>
352task 2.5.1 2016-02-24 task-color(5)