taskopen(1)

📦
version 1.1.5 · 2 versions
, in fedora 43, fedora 44

💖 taskopen(1) — the manual page, but make it cute 💖

okay so bestie, you know taskopen(1)? it's literally the companion app for taskwarrior, and it's the one that opens your annotations. she's iconic, she's efficient, and she's about to be your new favorite. let's get into it 🫶

✨ NAME ✨

taskopen — a companion application for taskwarrior, that facilitates opening annotations. no cap, that's the whole job and she does it flawlessly 💅

🌸 SYNOPSIS 🌸

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

🦋 DESCRIPTION 🦋

so here's the tea 🍓 — any task in taskwarrior can have zero-or-more annotations. zero! or a million! no judgement. taskopen can filter, list and open these annotations, and she can figure out several things about them based on clues she finds in the format.

an annotation can be a bunch of things:

  • a line of text
  • a link to a file
  • a link to a program
  • a link to a website

and if the annotation starts with [label: ]Notes, then taskopen will open (creating it if necessary, she's proactive like that ✨) a text note that's specific to the task, named UUID.txt — where UUID gets replaced with the actual task uuid, iykyk.

taskopen can be custom-configured by editing the .taskopenrc file, see taskopenrc(5). go off, customize your life 💖

👑 OPTIONS 👑

💫 General options 💫

  • -h — show a help text. a lil' helping hand, we love to see it 🫶
  • -v — print version information.
  • -V — print more verbose version and environment information. she's giving ✨detail✨
  • -c <filepath> — use an 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. like, go-make-a-snack slow. fr fr.
  • -n — only show/open notes, i.e. annotations matching NOTES_REGEX.
  • -N — show all but notes; the inverse of -n.
  • -f — only show/open real files, i.e. annotations matching FILE_REGEX.
  • -F — show all but real files; the inverse of -f.
  • -t — only show/open text annotations, i.e. annotations matching TEXT_REGEX.
  • -T — show all but text annotations; the 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. no questions asked, she just goes 💅
  • -r — raw mode, opens the annotation text with your EDITOR.
  • -D — delete the annotation instead of opening it. bye bestie 👋
  • -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 the 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 — so literally any combination of taskwarrior filters can be used with taskopen. the default filter can be specified in the taskopenrc file, see taskopenrc(5). mix and match, she's flexible like that 💜

🏷️ 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. she's got range ✨

🧚 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) — she ate that 💅

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. go wild bestie ✨

🧹 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. careful with that one tho 😭

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

$ 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. fixing your own mess? main character energy honestly 🫶

🖨️ 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. baby steps, we all start somewhere 🥹
  • early 2013 — re-implementation of taskopen in perl. glow up of the century ✨

💖 CREDITS & COPYRIGHTS 💖

Copyright (C) 2010 - 2020, 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>

and that's the whole manual bestie!! this was taskopen v1.1.5, dated 2020-02-04, and it's still serving looks in the taskopen(1) section of your friendly neighborhood user manual 💅✨ no cap, go open some annotations. periodt 🎀

📦 where this page comes from