1taskopen(1) User Manuals taskopen(1)
2
6 taskopen - A companion application for taskwarrior, that facilitates
7 opening annotations.
8
11 taskopen [options] [filter1 filter2 filterN] [\\label]
12
15 Any task in taskwarrior can have zero-or-more annotations. Taskopen can
16 filter, list and open these annotations, and can determine several
17 things about them, based on clues found in the format. An annotation
18 can be a line of text, it can be a link to a file, a link to a program,
19 or a link to a website. If the annotation starts with [label: ]Notes,
20 then taskopen will open (creating if necessary) a text note that is
21 specific to the task, and is named UUID.txt (where UUID is replaced
22 with the actual task uuid). Taskopen can be custom-configured by edit‐
23 ing the .taskopenrc file, see taskopenrc(5).
24
27 General options
28 -h Show a help text.
29 -v Print version information.
31 -V Print more verbose version and environment information.
33 -c <filepath>
35 Use alternate taskopenrc file as specified by filepath.
36 Filter options
40 -a Query all active tasks; clears the EXCLUDE filter.
41 -A Query all tasks. This includes completed and deleted tasks as
43 well. Depending on the size of your database this may be very
44 slow.
45 -n Only show/open notes, i.e. annotations matching NOTES_REGEX.
47 -N Show all but notes; inverse of -n.
49 -f Only show/open real files, i.e. annotations matching FILE_REGEX.
51 -F Show all but real files; inverse of -f.
53 -t Only show/open text annotations, i.e. annotations matching
55 TEXT_REGEX.
56 -T Show all but text annotations; inverse of -t.
58 -B Show only files that don't exist; should be used with -f or -n.
60 -m 'regex'
62 Only include annotations that match regex.
63 --type 'regex'
65 Only open files whose type (as returned by the file command)
66 matches regex.
67 Execution options
71 -b Batch mode, processes every matching annotation.
72 -r Raw mode, opens the annotation text with your EDITOR.
74 -D Delete the annotation instead of opening it.
76 -e Force to open the file with EDITOR.
78 -x [cmd]
80 Execute file, optionally prepend cmd to the command line. See
81 USER COMMANDS for further DETAILS
82 Output options
86 -l List-only mode, does not open any file. Can be combined with -L.
87 -L List-only mode, does not open any file. Shows command line that
89 would be executed. Can be combined with -l.
90 -s 'key1+,key2-'
92 Sort annotations by the given key which can be any taskwarrior
93 attribute (preceded by 'task_') or 'annot', 'label', 'entry',
94 'size', 'type', 'time', 'mtime' or 'atime'. A '+' or '-' may be
95 appended to the field indentifier in order to specify a sort
96 order.
97 -i [cmd]
99 Execute cmd for each file and shows its output interleaved with
100 the other output. A default can be set in the taskopenrc file.
101 See USER COMMANDS for further details.
102 -p 'cmd'
104 Pipe the output of taskopen to 'cmd'. This is supposed to behave
105 just like "taskopen | cmd".
106
109 Any argument that is not recognized as an option or label will be
110 passed to taskwarrior as an additional filter, i.e. any combination of
111 taskwarrior filters can be used with taskopen. The default filter can
112 be specified in the taskopenrc file, see taskopenrc(5).
113
116 Each annotation can have a "label", which is a leading word with a
117 colon and a space
118 <label>: <annotation text>
120 The label can be used to filter and/or sort the listings, and (in a
122 future version) it can be used as to specify how the annotation should
123 be handled. The label may match the NOTES_REGEX in which case the anno‐
124 tation is considered to be a link to the corresponding Notes file.
125
128 A user command can be specified on the command line by -i, -x or in the
129 taskopenrc file. By default, the decoded annotation (usually a file
130 path) will be passed as an argument to the user-specified command. This
131 behaviour can be overridden by using one or more of the following envi‐
132 ronment variables explicitly:
133 $FILE Contains the decoded annotation (usually a file path or a URI).
136 $UUID Contains the UUID of the corresponding task.
139 $ID Contains the ID of the corresponding task; may be empty.
142 $LABEL Contains the LABEL text of the annotation; may be empty.
145 $ANNOTATION
148 Contains the undecoded annotation text.
149 $LAST_MATCH
152 Contains the last sub-pattern of the matched REGEX, see examples
153 in taskopenrc(5).
154 $TASK_*
157 Such as TASK_PROJECT, which contains the value of the taskwar‐
158 rior attribute "project" as soon as you let taskopen know about
159 this attribute by adding it to the TASK_ATTRIBUTES variable in
160 your taskopenrc.
161 This way, for instance, you can choose to pass the UUID instead of the
163 file path to you command like this:
164 $ taskopen -i 'echo $UUID'
165
168 Basic usage
169 Create a new taskwarrior task:
170 $ task add Example
171 Add an annotation which links to a file:
173 $ task 1 annotate -- ~/checklist.txt
174 (Note that the "--" instructs taskwarrior to take the following argu‐
176 ments as the description part without doing any parser magic. This is
177 particularly useful to circumvent bug #819.)
178 Open the linked file by using the task's ID:
180 $ taskopen 1
181 or by a filter expression:
183 $ taskopen Example
184 Default notes
187 Inspired by Alan Bowens 'tasknote' you can add a default notes file to
188 a task. These files will be automatically created by the task's UUID
189 and don't require to annotate the task with a specific file path. The
190 folder in which these files will be stored, the triggering text
191 (default: "Notes") as well as the command to be executed can be cus‐
192 tomised by editing the taskopenrc file.
193 As soon as you annotate a task with 'Notes':
195 $ task 1 annotate Notes
196 you can open and edit this file by:
198 $ taskopen 1 -n
199 which will use your default EDITOR to open a file like ~/tas‐
201 knotes/5727f1c7-2efe-fb6b-2bac-6ce073ba95ee.txt
202 Multiple annotations
205 You can also add weblinks to a task and even mix all kinds of annota‐
206 tions:
207 $ task 1 annotate web: www.taskwarrior.org
208 $ task 1 annot I want to consider this
210 $ task 1 ann -- man: ~/Documents/manual.pdf
212 (note: taskopen currently works only with "link-type" annotations, so
215 the second annot above will not be listed) There are various ways to
216 open either the URI or the pdf file. If taskopen finds more than one
217 annotation matching the filter, it will output a list and ask for user
218 interaction:
219 $ taskopen 1
221 Please select an annotation:
223 1) man: ~/Documents/manual.pdf
224 2) web: www.taskwarrior.org
225 3) Notes
226 4) ~/checklist.txt
227 Type number(s):
229 Enter the number(s) of the annotation to open it, or any other charac‐
231 ter to abort. Multiple selections can be opened in sequence, by enter‐
232 ing a comma-separated list and/or range (as in 1,3,4 or 2-4)
233 You can use filters to directly address the desired annotation(s)...
235 by label:
237 $ taskopen 1 \\web
239 by regular expression:
241 $ taskopen 1 -m Doc
243 or by file type:
245 $ taskopen 1 --type PDF
247 Filter options and taskwarrior attributes can be used in any combina‐
249 tion.
250 Clean up annotations
253 The -x option can be used to execute arbitrary commands. The decoded
254 annotation, which will be a file path in most cases, will be passed as
255 a command line argument. This enables the user to do fancy things like
256 removing unused files from the filesystem:
257 $ taskopen -x 'rm' -A status.is:deleted
259 This command will show you a list of annotations of any deleted task.
261 You can then select one or even multiple items of the list in order to
262 remove the corresponding file from the filesystem.
263 You may also decide to precheck the command that is going to be exe‐
265 cuted by taskopen by adding the -L argument.
266 If you are sure that you want to execute the command on every file you
268 may consider activating the batch mode by adding the -b option.
269 Taskopen will then skip the user interaction and automatically select
270 all entries from the list.
271 Repair broken links
274 The -B option can be used to detect links to files that don't exist and
275 to repair the annotations, e.g.:
276 $ taskopen -b -f -B -r
278 This command operates in batch mode (-b), but only on annotations
280 matching FILE_REGEX (-f) that link to non-existing files (-B). For each
281 of those annotations it jumps into raw editing mode (-r) so that you
282 can correct the annotation text.
283 Output/interleave additional information
286 Interleaving of arbitrary information can be achieved by using the -i
287 'cmd' argument. This is particularly useful when you are using rather
288 general filters. The provided cmd will be executed for every annotation
289 that is going to be listed and the output of this command will be
290 interleaved with the list items. Taskopen comes with a number of helper
291 scripts that may be useful for this, e.g. for peeking into all your
292 Notes files:
293 $ taskopen -i 'headindent -n 5' -n
295
298 ~/.taskopenrc
299 User configuration file - see also taskopenrc(5). This can be
300 overriden by the -c argument.
301 ~/.taskopen/scripts/
304 User-specific extension scripts. Will be contained in taskopen's
305 PATH variable by default.
306
309 2010 - 2012
310 The first release of taskopen was a quite simple bash script.
311 early 2013
314 Re-implementation of taskopen in perl.
315
318 Copyright (C) 2010 - 2016, J. Schlatow
319 Taskopen is distributed under the GNU General Public License. See
321 http://www.opensource.org/licenses/gpl-2.0.php for more information.
322
325 taskopenrc(5)
326 For more information regarding taskopen, see the following:
328 The official site at
331 <https://github.com/ValiValpas/taskopen/>
332 The official code repository at
335 <git://github.com/ValiValpas/taskopen.git>
336
339 Bugs in taskopen may be reported to the issue-tracker at
340 <https://github.com/ValiValpas/taskopen/issues>
341taskopen v1.1.5 2019-02-02 taskopen(1)