{"id":17042057,"url":"https://github.com/jschlatow/taskopen","last_synced_at":"2025-03-23T01:26:31.392Z","repository":{"id":37473949,"uuid":"1054497","full_name":"jschlatow/taskopen","owner":"jschlatow","description":"Tool for taking notes and open urls with taskwarrior","archived":false,"fork":false,"pushed_at":"2025-02-19T08:00:19.000Z","size":369,"stargazers_count":390,"open_issues_count":14,"forks_count":33,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-14T18:08:13.549Z","etag":null,"topics":["nim","taskwarrior"],"latest_commit_sha":null,"homepage":"","language":"Nim","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jschlatow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2010-11-05T15:41:49.000Z","updated_at":"2025-03-10T19:41:01.000Z","dependencies_parsed_at":"2023-01-25T23:16:28.218Z","dependency_job_id":null,"html_url":"https://github.com/jschlatow/taskopen","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jschlatow%2Ftaskopen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jschlatow%2Ftaskopen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jschlatow%2Ftaskopen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jschlatow%2Ftaskopen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jschlatow","download_url":"https://codeload.github.com/jschlatow/taskopen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245042948,"owners_count":20551693,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nim","taskwarrior"],"created_at":"2024-10-14T09:14:33.471Z","updated_at":"2025-03-23T01:26:31.372Z","avatar_url":"https://github.com/jschlatow.png","language":"Nim","readme":"Taskopen was original developed as a simple wrapper script for taskwarrior that enables interaction with annotations (e.g. open, edit, execute files).\nThe current version is a pretty powerful customisable tool that supports a variety of use cases.\nThis README serves as a basic getting-started guide including install instructions and examples.\nIf your are interested in more details, please have a look at the [wiki] or the [man page].\n\n[wiki]: https://github.com/jschlatow/taskopen/wiki/2.0\n[man page]: doc/man/taskopen.1.md\n\n# Dependencies\n\nThis tool is an enhancement to taskwarrior, i.e. it depends on the task binary. See http://www.taskwarrior.org\n\nTaskopen is implemented in nim (requires at least version 1.4). Taskopen also requires make, xdg-open, and when run on the Windows Subsystem for Linux, wslu.\n\nThe helper scripts are usually run by bash. Some of the scripts also depend on (g)awk.\n\n# What does it do?\n\nIt allows you to link almost any file, webpage or command to a taskwarrior task by adding a filepath, web-link or uri as an annotation. Text notes, images, PDF files, web addresses, spreadsheets and many other types of links can then be filtered, listed and opened by using taskopen.\n\nArbitrary actions can be configured with taskopen to filter and act on the annotations or other task attributes.\n\nRun `taskopen -h` or `man taskopen` for further details.\nThe following sections show some (very) basic usage examples.\n\n\n## Basic usage\n\nAdd a task:\n\n\t$ task add Example\n\nAdd an annotation which links to a file:\n\n\t$ task 1 annotate -- ~/checklist.txt\n\n(Note that the \"--\" instructs taskwarrior to take the following arguments as the description part\nwithout doing any parser magic.)\n\nOpen the linked file by using the task's ID:\n\n\t$ taskopen 1\n\nOr by a filter expression:\n\n\t$ taskopen Example\n\n## Add default notes\n\nInspired by Alan Bowens 'tasknote' you can add a default notes file to a task. These files will be\nautomatically created by the task's UUID and don't require to annotate the task with a specific file path.\n\nAs soon as you annotate a task with 'Notes':\n\n\t$ task 1 annotate Notes\n\n...you can open and edit this file by:\n\n\t$ taskopen 1\n\n...which, by default, opens a file like \"~/tasknotes/5727f1c7-2efe-fb6b-2bac-6ce073ba95ee\".\n\n**Note:** You have to create the folder \"~/tasknotes\" before this works with the default folder.\n\nAutomatically annotating tasks with 'Notes' can be achieved with 'NO_ANNOTATION_HOOK' as described in\nthe manpage taskopenrc(5).\n\nOptionally, you may add any file extension to the annotation (e.g. 'Notes.txt'), which will instruct\ntaskopen to add the same extension to the created file.\n\n## Multiple annotations\n\nYou can also add weblinks to a task and even mix all kinds of annotations:\n\n\t$ task 1 annotate www.taskwarrior.org\n\t$ task 1 annotate I want to consider this\n\t$ task 1 annotate -- ~/Documents/manual.pdf\n\t$ taskopen 1\n\nTaskopen will determine the actionable annotations and will show a menu to let the user choose what to do:\n\n\tPlease select an annotation:\n       1) www.taskwarrior.org\n       2) ~/Documents/manual.pdf\n    Type number:\n\nNote, that the default (`normal`) mode of taskopen is to only show the first applicable action for every annotation.\nThere is also an `any` mode, which presents a menu with _every_ possible action for each annotation.\nIn `batch` mode, it executes the first applicable action for all annotations.\n\n# Installation\n\n## With Makefile\n\nFrom the command line, run the appropriate code for your OS:\n\n### Linux\n\n```bash\ngit clone https://github.com/jschlatow/taskopen.git\ncd taskopen\nmake PREFIX=/usr\nsudo make PREFIX=/usr install\n```\n\n### Mac\n\n```bash\ngit clone https://github.com/jschlatow/taskopen.git\ncd taskopen\nmake PREFIX=/usr/local\nsudo make PREFIX=/usr/local install\n```\n\nThis will install the taskopen binary into the `PREFIX/bin` directory.\nFor packaging, you can add `DESTDIR=/path/to/dir/` to the install command.\n\nBy default, taskopen will recognise any filenames in annotations and open them with `xdg-open` or `open` (on OS X).\nFurther actions must be specified in a configuration file at `~/.config/taskopen/taskopenrc` or `~/.taskopenrc`.\n\nA default configuration file can be created with `taskopen --config ~/.config/taskopen/taskopenrc`.\n\n### Windows Subsystem for Linux\n\nIn a Windows command prompt, enter\n\n```\ngit clone https://github.com/jschlatow/taskopen.git\nsudo apt install make\nsudo apt install nim\nsudo apt install wslu\nsudo apt install xdg-utils\ncd taskopen\nmake PREFIX=/usr\nsudo make PREFIX=/usr install\n```\n\n## With nimble\n\nt.b.d.\n\n\n## Migration from taskopen \u003c 2.0 to taskopen \u003e= 2.0\n\nDue to changes in the command line interface and the configuration file, manual intervention is required.\nPlease have a look at [CLI migration] and [Config migration].\n\n[CLI migration]: https://github.com/jschlatow/taskopen/wiki/CLI#migration\n[Config migration]: https://github.com/jschlatow/taskopen/wiki/Configuration#migration\n\n## Configuration basics\n\nIn order to customise taskopen to your needs, you may need to adapt its configuration file.\n\nTaskopen tries to find a configuration file at the following locations:\n\n* the path specified in `$TASKOPENRC` environment variable\n* `$XDG_CONFIG_HOME/taskopen/taskopenrc` if `$XDG_CONFIG_HOME` is set\n* `~/.config/taskopen/taskopenrc`\n* `~/.taskopenrc`.\n\nPlease also take a look at the manpage [taskopenrc(5)] for the config file syntax.\n\n[taskopenrc(5)]: doc/man/taskopenrc.5.md\n\n# Feature highlights\n\n  * Selecting multiple actions from a list\n  * Arbitrary task filters\n  * Customised annotation filtering\n  * Label-based filtering\n  * Filter command hook\n  * Inline commands\n  * Scripts\n\n## Selecting multiple actions from a list\n\nWhen presented with a menu of actionable annotations, you can select multiple entries (separated by space) or even ranges, e.g.\n\n\n\tPlease select one or multiple actions:\n       1) www.taskwarrior.org\n       2) ~/Documents/manual.pdf\n       3) Notes\n       3) ~/Documents/foobar.txt\n       3) https://www.github.com\n    Type number(s): 1 3-5\n\n## Arbitrary filters\n\nInstead of providing taskopen with an ID you can also pass arbitrary filters in taskwarrior\nnotation, like:\n\n    $ taskopen +next\n\nor\n\n    $ taskopen +bug pro:taskwarrior\n\n## Customised annotation filtering\n\nTaskopen determines the applicability of an action by matching the annotation against the action's regex.\nFor instance, multiple file extensions for default notes may be supported by the following action:\n\n```\n[Actions]\nnotes.regex = \"^Notes\\\\.(.*)\"\nnotes.command = \"$EDITOR ~/Notes/tasknotes/$UUID.$LAST_MATCH\"\n```\n\nNote, that taskopen fills the environment variable `$LAST_MATCH` with the part that matches `(.*)`.\n\n\n## Label-based filtering\n\nYou can label your annotations by using the following syntax:\n\n    $ task 1 annotate view: /path/to/file.html\n    $ task 1 annotate edit: /path/to/file.html\n\nWhen specifying an action, a label regex can be distinguish/filter annotations by their label.\nA configuration example is found in [examples/label_regex].\n\n[examples/label_regex]: ./examples/label_regex\n\n##Filter command hook\n\nYou can specify a filter command that will be executed after the regex matching to determine whether the action really applies to the annotion.\nA simple example is to check for file existence:\n\n```\n[Actions]\nfiles.regex = \"^[\\\\.\\\\/~]+.*\\\\.(.*)\"\nfiles.command = \"$EDITOR $FILE\"\nfiles.filtercommand = \"test -e $FILE\"\n```\n\nAn override for all actions can also be provided at the command line.\n\n##Inline commands\n\nSimilar to the filter command, the inline command can be used for adding information to the menu.\nFor instance, to peek show the first five lines of each file with each menu entry, you can add the following to your config file:\n\n```\nfiles.inlinecommand = \"head -n5 $FILE\"\n```\n\nAn override for all actions can also be provided at the command line.\n\n## Scripts\n\nTaskopen comes with a bunch of [scripts] that serve as examples to perform more advanced actions, inline commands or filter commands.\nMost notably are [addnote] and [editnote].\nThe former is used by default as the NO_ANNOTATION_HOOK and annotates the task with the given ID with 'Notes'.\nThe latter can be used to automatically add a header to new notes files.\nPlease have a look at the scripts or `man taskopen` to find more documentation.\n\n[scripts]: ./scripts\n[addnote]: ./scripts/addnote\n[editnote]: ./scripts/editnote\n\n## Contributions\n\nFeel free to contribute to this project by opening issues or creating pull requests.\nIf you are keen to fix any open issues, please have a look at ones labelled with _help wanted_.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjschlatow%2Ftaskopen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjschlatow%2Ftaskopen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjschlatow%2Ftaskopen/lists"}