taskopen - GitLite

KO | EN

gitlite — search

#javascript #python #hacktoberfest #android #deep-learning #docker #nodejs #java #windows #cli #kubernetes #awesome-list #security #openai

taskopen

(★ 432)

Tool for taking notes and open urls with taskwarrior (mirror of https://codeberg.org/jschlatow/taskopen)

File Explorer

Download Latest Version (.zip)

- - config.yml
- - config.yml
- - taskopen.1
  - taskopen.1.md
  - taskopenrc.5
  - taskopenrc.5.md
- - taskreviewrc
- default
- markdown
- templates
- utility_task
- - do_review.sh
  - mess2task
  - mess2task2
  - mutt2task
- addnote
- archive
- attach
- editnote
- rawedit
- taskban
- vims
- xdg-open-cli
- config.nim
- core.nim
- exec.nim
- output.nim
- taskopen.nim
- taskwarrior.nim
- types.nim
AUTHORS
LICENSE
Makefile
NEWS
README.md
taskopen.nimble

# Installation Guide

1. Get the code

git clone https://github.com/jschlatow/taskopen

Downloads the entire project code from GitHub to your computer.

cd taskopen

Moves into the project folder you just downloaded.

2. Official Install Script

Easy Recommended

Prerequisites

APT (Debian/Ubuntu 계열) Built into Debian/Ubuntu-based Linux distributions.

sudo apt install make

Installs directly from the APT package repository (Debian/Ubuntu-based).

sudo apt install nim

Installs directly from the APT package repository (Debian/Ubuntu-based).

sudo apt install wslu

Installs directly from the APT package repository (Debian/Ubuntu-based).

sudo apt install xdg-utils

Installs directly from the APT package repository (Debian/Ubuntu-based).

✅ After installing, open a new terminal and run the program's version command (e.g. --version) to confirm it worked.

Pulled directly from this repo's README.

3. Make

Medium

Prerequisites

Git Needed to download the project code from GitHub.
Make Usually pre-installed on Linux/macOS. On Windows, install separately (e.g. via MSYS2 or WSL).

make PREFIX=/usr

Compiles the code based on the generated build configuration to produce an executable.

make PREFIX=/usr/local

Compiles the code based on the generated build configuration to produce an executable.

✅ If it finishes without errors, it worked. Try running the generated executable directly.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Taskopen was original developed as a simple wrapper script for taskwarrior that enables interaction with annotations (e.g. open, edit, execute files).
The current version is a pretty powerful customisable tool that supports a variety of use cases.
This README serves as a basic getting-started guide including install instructions and examples.
If your are interested in more details, please have a look at the [wiki] or the [man page].

[wiki]: https://codeberg.org/jschlatow/taskopen/wiki/2.0
[man page]: doc/man/taskopen.1.md

# Dependencies

This tool is an enhancement to taskwarrior, i.e. it depends on the task binary. See http://www.taskwarrior.org

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

The helper scripts are usually run by bash. Some of the scripts also depend on (g)awk.

# What does it do?

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

Arbitrary actions can be configured with taskopen to filter and act on the annotations or other task attributes.

Run `taskopen -h` or `man taskopen` for further details.
The following sections show some (very) basic usage examples.

## Basic usage

Add a 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.)

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

$ taskopen 1

Or by a filter expression:

$ taskopen Example

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

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

$ task 1 annotate Notes

...you can open and edit this file by:

$ taskopen 1

...which, by default, opens a file like "~/tasknotes/5727f1c7-2efe-fb6b-2bac-6ce073ba95ee".

**Note:** You have to create the folder "~/tasknotes" before this works with the default folder.

Automatically annotating tasks with 'Notes' can be achieved with 'NO_ANNOTATION_HOOK' as described in
the manpage taskopenrc(5).

Optionally, you may add any file extension to the annotation (e.g. 'Notes.txt'), which will instruct
taskopen to add the same extension to the created file.

## Multiple annotations

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

$ task 1 annotate www.taskwarrior.org
	$ task 1 annotate I want to consider this
	$ task 1 annotate -- ~/Documents/manual.pdf
	$ taskopen 1

Taskopen will determine the actionable annotations and will show a menu to let the user choose what to do:

Please select an annotation:
       1) www.taskwarrior.org
       2) ~/Documents/manual.pdf
    Type number:

Note, that the default (`normal`) mode of taskopen is to only show the first applicable action for every annotation.
There is also an `any` mode, which presents a menu with _every_ possible action for each annotation.
In `batch` mode, it executes the first applicable action for all annotations.

# Installation

## With Makefile

From the command line, run the appropriate code for your OS:

### Linux

```bash
git clone https://codeberg.org/jschlatow/taskopen.git
cd taskopen
make PREFIX=/usr
sudo make PREFIX=/usr install
```

### Mac

```bash
git clone https://codeberg.org/jschlatow/taskopen.git
cd taskopen
make PREFIX=/usr/local
sudo make PREFIX=/usr/local install
```

This will install the taskopen binary into the `PREFIX/bin` directory.
For packaging, you can add `DESTDIR=/path/to/dir/` to the install command.

By default, taskopen will recognise any filenames in annotations and open them with `xdg-open` or `open` (on OS X).
Further actions must be specified in a configuration file at `~/.config/taskopen/taskopenrc` or `~/.taskopenrc`.

A default configuration file can be created with `taskopen --config ~/.config/taskopen/taskopenrc`.

### Windows Subsystem for Linux

In a Windows command prompt, enter

```
git clone https://codeberg.org/jschlatow/taskopen.git
sudo apt install make
sudo apt install nim
sudo apt install wslu
sudo apt install xdg-utils
cd taskopen
make PREFIX=/usr
sudo make PREFIX=/usr install
```

## With nimble

t.b.d.

## Migration from taskopen < 2.0 to taskopen >= 2.0

Due to changes in the command line interface and the configuration file, manual intervention is required.
Please have a look at [CLI migration] and [Config migration].

[CLI migration]: https://codeberg.org/jschlatow/taskopen/wiki/CLI#migration
[Config migration]: https://codeberg.org/jschlatow/taskopen/wiki/Configuration#migration

## Configuration basics

In order to customise taskopen to your needs, you may need to adapt its configuration file.

Taskopen tries to find a configuration file at the following locations:

* the path specified in `$TASKOPENRC` environment variable
* `$XDG_CONFIG_HOME/taskopen/taskopenrc` if `$XDG_CONFIG_HOME` is set
* `~/.config/taskopen/taskopenrc`
* `~/.taskopenrc`.

Please also take a look at the manpage [taskopenrc(5)] for the config file syntax.

[taskopenrc(5)]: doc/man/taskopenrc.5.md

# Feature highlights

* Selecting multiple actions from a list
  * Arbitrary task filters
  * Customised annotation filtering
  * Label-based filtering
  * Filter command hook
  * Inline commands
  * Scripts

## Selecting multiple actions from a list

When presented with a menu of actionable annotations, you can select multiple entries (separated by space) or even ranges, e.g.

Please select one or multiple actions:
       1) www.taskwarrior.org
       2) ~/Documents/manual.pdf
       3) Notes
       3) ~/Documents/foobar.txt
       3) https://www.github.com
    Type number(s): 1 3-5

## Arbitrary filters

Instead of providing taskopen with an ID you can also pass arbitrary filters in taskwarrior
notation, like:

$ taskopen +next

or

$ taskopen +bug pro:taskwarrior

## Customised annotation filtering

Taskopen determines the applicability of an action by matching the annotation against the action's regex.
For instance, multiple file extensions for default notes may be supported by the following action:

```
[Actions]
notes.regex = "^Notes\\.(.*)"
notes.command = "$EDITOR ~/Notes/tasknotes/$UUID.$LAST_MATCH"
```

Note, that taskopen fills the environment variable `$LAST_MATCH` with the part that matches `(.*)`.

## Label-based filtering

You can label your annotations by using the following syntax:

$ task 1 annotate view: /path/to/file.html
    $ task 1 annotate edit: /path/to/file.html

When specifying an action, a label regex can be distinguish/filter annotations by their label.
A configuration example is found in [examples/label_regex].

[examples/label_regex]: ./examples/label_regex

##Filter command hook

You can specify a filter command that will be executed after the regex matching to determine whether the action really applies to the annotion.
A simple example is to check for file existence:

```
[Actions]
files.regex = "^[\\.\\/~]+.*\\.(.*)"
files.command = "$EDITOR $FILE"
files.filtercommand = "test -e $FILE"
```

An override for all actions can also be provided at the command line.

##Inline commands

Similar to the filter command, the inline command can be used for adding information to the menu.
For instance, to peek show the first five lines of each file with each menu entry, you can add the following to your config file:

```
files.inlinecommand = "head -n5 $FILE"
```

An override for all actions can also be provided at the command line.

## Scripts

Taskopen comes with a bunch of [scripts] that serve as examples to perform more advanced actions, inline commands or filter commands.
Most notably are [addnote] and [editnote].
The former is used by default as the NO_ANNOTATION_HOOK and annotates the task with the given ID with 'Notes'.
The latter can be used to automatically add a header to new notes files.
Please have a look at the scripts or `man taskopen` to find more documentation.

[scripts]: ./scripts
[addnote]: ./scripts/addnote
[editnote]: ./scripts/editnote

## Contributions

Feel free to contribute to this project by opening issues or creating pull requests.
If you are keen to fix any open issues, please have a look at ones labelled with _help wanted_.