-
-
Notifications
You must be signed in to change notification settings - Fork 287
/
task-color.5.in
333 lines (237 loc) · 10.4 KB
/
task-color.5.in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
.TH task-color 5 2016-02-24 "${PACKAGE_STRING}" "User Manuals"
.SH NAME
task-color \- A color tutorial for the Taskwarrior command line todo manager.
.SH SETUP
The first thing you need is make sure you 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.
.SH 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
.SH 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!
.SH 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 bold 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 bold 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.
.SH 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.
.SH 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.
.SH 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.
.SH 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!
In such cases, consider using the 'rule.color.merge=no' option to disable the
color blending.
The precedence for the color rules is determined by the configuration
variable 'rule.precedence.color', which by default contains:
deleted,completed,active,keyword.,tag.,project.,overdue,scheduled,due.today,due,blocked,blocking,recurring,tagged,uda.
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.
.SH 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):
.RS
include ${CMAKE_INSTALL_PREFIX}/${TASK_RCDIR}/dark-256.theme
.RE
You can use any of the standard Taskwarrior themes:
.RS
dark-16.theme
.br
dark-256.theme
.br
dark-blue-256.theme
.br
dark-gray-256.theme
.br
dark-green-256.theme
.br
dark-red-256.theme
.br
dark-violets-256.theme
.br
dark-yellow-green.theme
.br
light-16.theme
.br
light-256.theme
.br
solarized-dark-256.theme
.br
solarized-light-256.theme
.br
dark-default-16.theme
.br
dark-gray-blue-256.theme
.br
no-color.theme
.RE
Bear in mind that if you are using a terminal with a dark background, you will
see better results using a dark 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>.
.SH "CREDITS & COPYRIGHTS"
Copyright (C) 2006 \- 2018 P. Beckingham, F. Hernandez.
Taskwarrior is distributed under the MIT license. See
https://www.opensource.org/licenses/mit-license.php for more information.
.SH SEE ALSO
.BR task(1),
.BR taskrc(5),
.BR task-sync(5)
For more information regarding Taskwarrior, the following may be referenced:
.TP
The official site at
<http://taskwarrior.org>
.TP
The official code repository at
<https://github.com/GothenburgBitFactory/taskwarrior>
.TP
You can contact the project by writing an email to
<support@gothenburgbitfactory.org>
.SH REPORTING BUGS
.TP
Bugs in Taskwarrior may be reported to the issue-tracker at
<http://taskwarrior.org>