1taskopen(1)                      User Manuals                      taskopen(1)
2
3
4

NAME

6       taskopen  -  A  companion application for taskwarrior, that facilitates
7       opening annotations.
8
9

SYNOPSIS

11       taskopen [options] [filter1 filter2 filterN] [\\label]
12
13

DESCRIPTION

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
25

OPTIONS

27   General options
28       -h     Show a help text.
29
30       -v     Print version information.
31
32       -V     Print more verbose version and environment information.
33
34       -c <filepath>
35              Use alternate taskopenrc file as specified by filepath.
36
37
38
39   Filter options
40       -a     Query all active tasks; clears the EXCLUDE filter.
41
42       -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
46       -n     Only show/open notes, i.e. annotations matching NOTES_REGEX.
47
48       -N     Show all but notes;  inverse of -n.
49
50       -f     Only show/open real files, i.e. annotations matching FILE_REGEX.
51
52       -F     Show all but real files; inverse of -f.
53
54       -t     Only  show/open  text  annotations,  i.e.  annotations  matching
55              TEXT_REGEX.
56
57       -T     Show all but text annotations; inverse of -t.
58
59       -B     Show only files that don't exist; should be used with -f or -n.
60
61       -m 'regex'
62              Only include annotations that match regex.
63
64       --type 'regex'
65              Only  open  files  whose  type (as returned by the file command)
66              matches regex.
67
68
69
70   Execution options
71       -b     Batch mode, processes every matching annotation.
72
73       -r     Raw mode, opens the annotation text with your EDITOR.
74
75       -D     Delete the annotation instead of opening it.
76
77       -e     Force to open the file with EDITOR.
78
79       -x [cmd]
80              Execute file, optionally prepend cmd to the  command  line.  See
81              USER COMMANDS for further DETAILS
82
83
84
85   Output options
86       -l     List-only mode, does not open any file. Can be combined with -L.
87
88       -L     List-only  mode, does not open any file. Shows command line that
89              would be executed. Can be combined with -l.
90
91       -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 or‐
96              der.
97
98       -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
103       -p 'cmd'
104              Pipe the output of taskopen to 'cmd'. This is supposed to behave
105              just like "taskopen | cmd".
106
107

FILTERS

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
114

LABELS

116       Each annotation can have a "label", which is  a  leading  word  with  a
117       colon and a space
118
119              <label>: <annotation text>
120
121       The label can be used to filter and/or sort the listings, and (in a fu‐
122       ture version) it can be used as to specify how the annotation should be
123       handled.  The label may match the NOTES_REGEX in which case the annota‐
124       tion is considered to be a link to the corresponding Notes file.
125
126

USER COMMANDS

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
134
135       $FILE  Contains the decoded annotation (usually a file path or a URI).
136
137
138       $UUID  Contains the UUID of the corresponding task.
139
140
141       $ID    Contains the ID of the corresponding task; may be empty.
142
143
144       $LABEL Contains the LABEL text of the annotation; may be empty.
145
146
147       $ANNOTATION
148              Contains the undecoded annotation text.
149
150
151       $LAST_MATCH
152              Contains the last sub-pattern of the matched REGEX, see examples
153              in taskopenrc(5).
154
155
156       $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
162       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
166

EXAMPLES

168   Basic usage
169       Create a new taskwarrior task:
170              $ task add Example
171
172       Add an annotation which links to a file:
173              $ task 1 annotate -- ~/checklist.txt
174
175       (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
179       Open the linked file by using the task's ID:
180              $ taskopen 1
181
182       or by a filter expression:
183              $ taskopen Example
184
185
186   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  (de‐
191       fault: "Notes") as well as the command to be executed can be customised
192       by editing the taskopenrc file.
193
194       As soon as you annotate a task with 'Notes':
195              $ task 1 annotate Notes
196
197       you can open and edit this file by:
198              $ taskopen 1 -n
199
200       which will  use  your  default  EDITOR  to  open  a  file  like  ~/tas‐
201       knotes/5727f1c7-2efe-fb6b-2bac-6ce073ba95ee.txt
202
203
204   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
209              $ task 1 annot I want to consider this
210
211              $ task 1 ann -- man: ~/Documents/manual.pdf
212
213
214       (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
220              $ taskopen 1
221
222              Please select an annotation:
223                 1) man: ~/Documents/manual.pdf
224                 2) web: www.taskwarrior.org
225                 3) Notes
226                 4) ~/checklist.txt
227
228              Type number(s):
229
230       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
234       You can use filters to directly address the desired annotation(s)...
235
236       by label:
237
238              $ taskopen 1 \\web
239
240       by regular expression:
241
242              $ taskopen 1 -m Doc
243
244       or by file type:
245
246              $ taskopen 1 --type PDF
247
248       Filter options and taskwarrior attributes can be used in  any  combina‐
249       tion.
250
251
252   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
258              $ taskopen -x 'rm' -A status.is:deleted
259
260       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
264       You may also decide to precheck the command that is going  to  be  exe‐
265       cuted by taskopen by adding the -L argument.
266
267       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
272
273   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
277              $ taskopen -b -f -B -r
278
279       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
284
285   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 in‐
290       terleaved 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
294              $ taskopen -i 'headindent -n 5' -n
295
296

FILES & FOLDERS

298       ~/.taskopenrc
299              User configuration file - see also taskopenrc(5).  This  can  be
300              overriden by the -c argument.
301
302
303       ~/.taskopen/scripts/
304              User-specific extension scripts. Will be contained in taskopen's
305              PATH variable by default.
306
307

HISTORY

309       2010 - 2012
310              The first release of taskopen was a quite simple bash script.
311
312
313       early 2013
314              Re-implementation of taskopen in perl.
315
316

CREDITS & COPYRIGHTS

318       Copyright (C) 2010 - 2020, J. Schlatow
319
320       Taskopen is distributed under  the  GNU  General  Public  License.  See
321       http://www.opensource.org/licenses/gpl-2.0.php for more information.
322
323

SEE ALSO

325       taskopenrc(5)
326
327       For more information regarding taskopen, see the following:
328
329
330       The official site at
331              <https://github.com/ValiValpas/taskopen/>
332
333
334       The official code repository at
335              <git://github.com/ValiValpas/taskopen.git>
336
337

REPORTING BUGS

339       Bugs in taskopen may be reported to the issue-tracker at
340              <https://github.com/ValiValpas/taskopen/issues>
341
342
343
344
345taskopen v1.1.5                   2020-02-04                       taskopen(1)
Impressum