A companion application for taskwarrior, that facilitates opening annotations.

## Synopsis

taskopen [options] [filter1 filter2 filterN] [\\label]

## Options

### General options

-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.

### Filter options

-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.

### Execution options

-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

### Output options

-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".

## Filters

Any argument that is not recognized as an option or label will be passed to taskwarrior as an additional filter, i.e. any combination of taskwarrior filters can be used with taskopen. The default filter can be specified in the taskopenrc file, see taskopenrc(5).

## Labels

Each annotation can have a "label", which is a leading word with a colon and a space

<label>: <annotation text>

The label can be used to filter and/or sort the listings, and (in a future version) it can be used as to specify how the annotation should be handled. The label may match the NOTES_REGEX in which case the annotation is considered to be a link to the corresponding Notes file.

## User Commands

A user command can be specified on the command line by -i, -x or in the taskopenrc file. By default, the decoded annotation (usually a file path) will be passed as an argument to the user-specified command. This behaviour can be overridden by using one or more of the following environment variables explicitly:

$FILE Contains the decoded annotation (usually a file path or a URI).$UUID

Contains the UUID of the corresponding task.

$ID Contains the ID of the corresponding task; may be empty.$LABEL

Contains the LABEL text of the annotation; may be empty.

$ANNOTATION Contains the undecoded annotation text.$LAST_MATCH

Contains the last sub-pattern of the matched REGEX, see examples in taskopenrc(5).

$TASK_* Such as TASK_PROJECT, which contains the value of the taskwarrior attribute "project" as soon as you let taskopen know about this attribute by adding it to the TASK_ATTRIBUTES variable in your taskopenrc. This way, for instance, you can choose to pass the UUID instead of the file path to you command like this:$ taskopen -i 'echo $UUID' ## Examples ### Basic usage Create a new taskwarrior task:$ task add Example

$task 1 annotate -- ~/checklist.txt (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:$ taskopen 1

or by a filter expression:

$taskopen Example ### Default notes 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':$ task 1 annotate Notes

you can open and edit this file by:

$taskopen 1 -n which will use your default EDITOR to open a file like ~/tasknotes/5727f1c7-2efe-fb6b-2bac-6ce073ba95ee.txt ### Multiple annotations You can also add weblinks to a task and even mix all kinds of annotations:$ task 1 annotate web: www.taskwarrior.org

$task 1 annot I want to consider this$ task 1 ann -- man: ~/Documents/manual.pdf

(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:

$taskopen 1 Please select an annotation: 1) man: ~/Documents/manual.pdf 2) web: www.taskwarrior.org 3) Notes 4) ~/checklist.txt Type number(s): 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:$ taskopen 1 \\web

by regular expression:

$taskopen 1 -m Doc or by file type:$ taskopen 1 --type PDF

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

### Clean up annotations

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:

## Files & Folders

User-specific extension scripts. Will be contained in taskopen's PATH variable by default.

## History

2010 - 2012

The first release of taskopen was a quite simple bash script.

early 2013

Copyright (C) 2010 - 2020, J. Schlatow