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 It should be mentioned that Taskwarrior is aware of whether its output
12 is going to a terminal, or to a file or through a pipe. When Taskwar‐
13 rior output goes to a terminal, color is desirable, but consider the
14 following command:
15 $ task list > file.txt
17 Do we really want all those color control codes in the file? Taskwar‐
19 rior assumes that you do not, and temporarily sets color to 'off' while
20 generating the output. This explains the output from the following
21 command:
22 $ task show | grep '^color '
24 color off
25 it always returns 'off', no matter what the setting, because the output
27 is being sent to a pipe.
28 If you wanted those color codes, you can override this behavior by set‐
30 ting the _forcecolor variable to on, like this:
31 $ task config _forcecolor on
33 $ task config | grep '^color '
34 color on
35 or by temporarily overriding it like this:
37 $ task rc._forcecolor=on config | grep '^color '
39 color on
40
43 Taskwarrior has a 'color' command that will show all the colors it is
44 capable of displaying. Try this:
45 $ task color
47 The output cannot be replicated here in a man page, but you should see
49 a set of color samples. How many you see depends on your terminal pro‐
50 gram's ability to render them.
51 You should at least see the Basic colors and Effects - if you do, then
53 you have 16-color support. If your terminal supports 256 colors,
54 you'll know it!
55
58 The basic color support is provided through named colors:
59 black, red, blue, green, magenta, cyan, yellow, white
61 Foreground color (for text) is simply specified as one of the above
63 colors, or not specified at all to use the default terminal text color.
64 Background color is specified by using the word 'on', and one of the
66 above colors. Some examples:
67 green # green text, default background color
69 green on yellow # green text, yellow background
70 on yellow # default text color, yellow background
71 These colors can be modified further, by making the foreground bold, or
73 by making the background bright. Some examples:
74 bold green
76 bold white on bright red
77 on bright cyan
78 The order of the words is not important, so the following are equiva‐
80 lent:
81 bold green
83 green bold
84 But the 'on' is important - colors before the 'on' are foreground, and
86 colors after 'on' are background.
87 There is an additional 'underline' attribute that may be used:
89 underline bold red on black
91 And an 'inverse' attribute:
93 inverse red
95 Taskwarrior has a command that helps you visualize these color combina‐
97 tions. Try this:
98 $ task color underline bold red on black
100 You can use this command to see how the various color combinations
102 work. You will also see some sample colors displayed, like the ones
103 above, in addition to the sample requested.
104 Some combinations look very nice, some look terrible. Different termi‐
106 nal programs do implement slightly different versions of 'red', for ex‐
107 ample, so you may see some unexpected variation across machines. The
108 brightness of your display is also a factor.
109
112 Using 256 colors follows the same form, but the names are different,
113 and some colors can be referenced in different ways. First there is by
114 color ordinal, which is like this:
115 color0
117 color1
118 color2
119 ...
120 color255
121 This gives you access to all 256 colors, but doesn't help you much.
123 This range is a combination of 8 basic colors (color0 - color7), then 8
124 brighter variations (color8 - color15). Then a block of 216 colors
125 (color16 - color231). Then a block of 24 gray colors (color232 -
126 color255).
127 The large block of 216 colors (6x6x6 = 216) represents a color cube,
129 which can be addressed via RGB values from 0 to 5 for each component
130 color. A value of 0 means none of this component color, and a value of
131 5 means the most intense component color. For example, a bright red is
132 specified as:
133 rgb500
135 And a darker red would be:
137 rgb300
139 Note that the three digits represent the three component values, so in
141 this example the 5, 0 and 0 represent red=5, green=0, blue=0. Combin‐
142 ing intense red with no green and no blue yields red. Similarly, blue
143 and green are:
144 rgb005
146 rgb050
147 Another example - bright yellow - is a mix of bright red and bright
149 green, but no blue component, so bright yellow is addressed as:
150 rgb550
152 A soft pink would be addressed as:
154 rgb515
156 See if you agree, by running:
158 $ task color black on rgb515
160 You may notice that the large color block is represented as 6 squares.
162 All colors in the first square have a red value of 0. All colors in
163 the 6th square have a red value of 5. Within each square, blue ranges
164 from 0 to 5 left to right, and within each square green ranges from 0
165 to 5, top to bottom. This scheme takes some getting used to.
166 The block of 24 gray colors can also be accessed as gray0 - gray23, in
168 a continuous ramp from black to white.
169
172 If you specify 16-colors, and view on a 256-color terminal, no problem.
173 If you try the reverse, specifying 256-colors and viewing on a 16-color
174 terminal, you will be disappointed, perhaps even appalled.
175 There is some limited color mapping - for example, if you were to spec‐
177 ify this combination:
178 red on gray3
180 you are mixing a 16-color and 256-color specification. Taskwarrior
182 will map red to color1, and proceed. Note that red and color1 are not
183 quite the same tone.
184 Note also that there is no bold or bright attributes when dealing with
186 256 colors, but there is still underline available.
187
190 Taskwarrior will show examples of all defined colors used in your
191 .taskrc, or theme, if you run this command:
192 $ task color legend
194 This gives you an example of each of the colors, so you can see the ef‐
196 fect, without necessarily creating a set of tasks that meet each of the
197 rule criteria.
198
201 Taskwarrior supports colorization rules. These are configuration val‐
202 ues that specify a color, and the conditions under which that color is
203 used. By example, let us add a few tasks:
204 $ task add project:Home priority:H pay the bills (1)
206 $ task add project:Home clean the rug (2)
207 $ task add project:Garden clean out the garage (3)
208 We can add a color rule that uses a blue background for all tasks in
210 the Home project:
211 $ task config color.project.Home 'on blue'
213 We use quotes around 'on blue' because there are two words, but they
215 represent one value in the .taskrc file. Now suppose we wish to use a
216 bold yellow text color for all cleaning work:
217 $ task config color.keyword.clean 'bold yellow'
219 Now what happens to task 2, which belongs to project Home (blue back‐
221 ground), and is also a cleaning task (bold yellow foreground)? The
222 colors are combined, and the task is shown as "bold yellow on blue".
223 Color rules can be applied by project and description keyword, as
225 shown, and also by priority (or lack of priority), by active status, by
226 being due or overdue, by being tagged, or having a specific tag (per‐
227 haps the most useful rule) or by being a recurring task.
228 It is possible to create a very colorful mix of rules. With 256-color
230 support, those colors can be made subtle, and complementary, but with‐
231 out care, this can be a visual mess. Beware!
232 In such cases, consider using the 'rule.color.merge=no' option to dis‐
234 able the color blending.
235 The precedence for the color rules is determined by the configuration
237 variable 'rule.precedence.color', which by default contains:
238 deleted,completed,active,keyword.,tag.,project.,overdue,sched‐
240 uled,due.today,due,blocked,blocking,recurring,tagged,uda.
241 These are just the color rules with the 'color.' prefix removed. The
243 rule 'color.deleted' has the highest precedence, and 'color.uda.' the
244 lowest.
245 The keyword rule shown here as 'keyword.' corresponds to a wildcard
247 pattern, meaning 'color.keyword.*', or in other words all the keyword
248 rules.
249 There is also 'color.project.none', 'color.tag.none' and
251
254 Taskwarrior supports themes. What this really means is that with the
255 ability to include other files into the .taskrc file, different sets of
256 color rules can be included.
257 To get a good idea of what a color theme looks like, try adding this
259 entry to your .taskrc file:
260 include dark-256.theme
262 You can use any of the standard Taskwarrior themes:
264 dark-16.theme
266 dark-256.theme
267 dark-blue-256.theme
268 dark-gray-256.theme
269 dark-green-256.theme
270 dark-red-256.theme
271 dark-violets-256.theme
272 dark-yellow-green.theme
273 light-16.theme
274 light-256.theme
275 solarized-dark-256.theme
276 solarized-light-256.theme
277 dark-default-16.theme
278 dark-gray-blue-256.theme
279 no-color.theme
280 Bear in mind that if you are using a terminal with a dark background,
282 you will see better results using a dark theme.
283 You can also see how the theme will color the various tasks with the
285 command:
286 $ task color legend
288 Better yet, create your own, and share it. We will gladly host the
290 theme file on <https://taskwarrior.org>.
291
294 Copyright (C) 2006 - 2021 T. Babej, P. Beckingham, F. Hernandez.
295 Taskwarrior is distributed under the MIT license. See https://www.open‐
297 source.org/licenses/mit-license.php for more information.
298
301 task(1), taskrc(5), task-sync(5)
302 For more information regarding Taskwarrior, see the following:
304 The official site at
307 <https://taskwarrior.org>
308 The official code repository at
311 <https://github.com/GothenburgBitFactory/taskwarrior>
312 You can contact the project by emailing
315 <support@GothenburgBitFactory.org>
316
319 Bugs in Taskwarrior may be reported to the issue-tracker at
320 <https://github.com/GothenburgBitFactory/taskwarrior/issues>
321task 2.6.2 2016-02-24 task-color(5)