taskopen - Man Page

-h

Show a help text.

-v

Print version information.

-V

Print more verbose version and environment information.

-c <filepath>

Use alternate taskopenrc file as specified by filepath.

-a

Query all active tasks; clears the EXCLUDE filter.

-A

Query all tasks. This includes completed and deleted tasks as well. Depending on the size of your database this may be very slow.

-n

Only show/open notes, i.e. annotations matching NOTES_REGEX.

-N

Show all but notes;  inverse of -n.

-f

Only show/open real files, i.e. annotations matching FILE_REGEX.

-F

Show all but real files; inverse of -f.

-t

Only show/open text annotations, i.e. annotations matching TEXT_REGEX.

-T

Show all but text annotations; inverse of -t.

-B

Show only files that don't exist; should be used with -f or -n.

-m 'regex'

Only include annotations that match regex.

--type 'regex'

Only open files whose type (as returned by the file command) matches regex.

-b

Batch mode, processes every matching annotation.

-r

Raw mode, opens the annotation text with your EDITOR.

-D

Delete the annotation instead of opening it.

-e

Force to open the file with EDITOR.

-x [cmd]

Execute file, optionally prepend cmd to the command line. See User Commands for further DETAILS

-l

List-only mode, does not open any file. Can be combined with -L.

-L

List-only mode, does not open any file. Shows command line that would be executed. Can be combined with -l.

-s 'key1+,key2-'

Sort annotations by the given key which can be any taskwarrior attribute (preceded by 'task_') or 'annot', 'label', 'entry', 'size', 'type', 'time', 'mtime' or 'atime'. A '+' or '-' may be appended to the field indentifier in order to specify a sort order.

-i [cmd]

Execute cmd for each file and shows its output interleaved with the other output. A default can be set in the taskopenrc file. See User Commands for further details.

-p 'cmd'

Pipe the output of taskopen to 'cmd'. This is supposed to behave just like "taskopen | cmd".

Create a new taskwarrior task:

Add an annotation which links to a file:

(Note that the "--" instructs taskwarrior to take the following arguments as the description part without doing any parser magic. This is particularly useful to circumvent bug #819.)

Open the linked file by using the task's ID:

or by a filter expression:

Inspired by Alan Bowens 'tasknote' you can add a default notes file to a task. These files will be automatically created by the task's UUID and don't require to annotate the task with a specific file path. The folder in which these files will be stored, the triggering text (default: "Notes") as well as the command to be executed can be customised by editing the taskopenrc file.

As soon as you annotate a task with 'Notes':

you can open and edit this file by:

which will use your default EDITOR to open a file like ~/tasknotes/5727f1c7-2efe-fb6b-2bac-6ce073ba95ee.txt

You can also add weblinks to a task and even mix all kinds of annotations:

(note: taskopen currently works only with "link-type" annotations, so the second annot above will not be listed) There are various ways to open either the URI or the pdf file. If taskopen finds more than one annotation matching the filter, it will output a list and ask for user interaction:

Enter the number(s) of the annotation to open it, or any other character to abort. Multiple selections can be opened in sequence, by entering a comma-separated list and/or range (as in 1,3,4 or 2-4)

You can use filters to directly address the desired annotation(s)...

by label:

by regular expression:

or by file type:

Filter options and taskwarrior attributes can be used in any combination.

The -x option can be used to execute arbitrary commands. The decoded annotation, which will be a file path in most cases, will be passed as a command line argument. This enables the user to do fancy things like removing unused files from the filesystem:

This command will show you a list of annotations of any deleted task. You can then select one or even multiple items of the list in order to remove the corresponding file from the filesystem.

You may also decide to precheck the command that is going to be executed by taskopen by adding the -L argument.

If you are sure that you want to execute the command on every file you may consider activating the batch mode by adding the -b option. Taskopen will then skip the user interaction and automatically select all entries from the list.

The -B option can be used to detect links to files that don't exist and to repair the annotations, e.g.:

This command operates in batch mode (-b), but only on annotations matching FILE_REGEX (-f) that link to non-existing files (-B). For each of those annotations it jumps into raw editing mode (-r) so that you can correct the annotation text.

Interleaving of arbitrary information can be achieved by using the -i 'cmd' argument. This is particularly useful when you are using rather general filters. The provided cmd will be executed for every annotation that is going to be listed and the output of this command will be interleaved with the list items. Taskopen comes with a number of helper scripts that may be useful for this, e.g. for peeking into all your Notes files: