taskopen(1)

NAME
taskopen - A companion application for taskwarrior, that facilitates opening annotations.

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

DESCRIPTION
Any task in taskwarrior can have zero-or-more annotations. Taskopen can filter, list and open these annotations, and can determine several things about them, based on clues found in the format. An annotation can be a line of text, it can be a link to a file, a link to a program, or a link to a website. If the annotation starts with [label: ]Notes, then taskopen will open (creating if necessary) a text note that is specific to the task, and is named UUID.txt (where UUID is replaced with the actual task uuid). Taskopen can be custom-configured by editing the .taskopenrc file, see taskopenrc(5).

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
Add an annotation which links to a file:
    $ 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:
    $ taskopen -x 'rm' -A status.is:deleted
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.

  Repair broken links
The -B option can be used to detect links to files that don't exist and to repair the annotations, e.g.:
    $ taskopen -b -f -B -r
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.

  Output/interleave additional information
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:
    $ taskopen -i 'headindent -n 5' -n

FILES & FOLDERS

~/.taskopenrc
    User configuration file - see also taskopenrc(5). This can be overriden by the -c argument.

~/.taskopen/scripts/
    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
    Re-implementation of taskopen in perl.

CREDITS & COPYRIGHTS
Copyright (C) 2010 - 2016, J. Schlatow Taskopen is distributed under the GNU General Public License. See http://www.opensource.org/licenses/gpl-2.0.php for more information.

SEE ALSO
taskopenrc(5) For more information regarding taskopen, see the following:

The official site at
    <https://github.com/ValiValpas/taskopen/>

The official code repository at
    <git://github.com/ValiValpas/taskopen.git>

REPORTING BUGS

Bugs in taskopen may be reported to the issue-tracker at
    <https://github.com/ValiValpas/taskopen/issues>