tasknc(1)

📦 version 2020-12, in nixos 26.05, nixpkgs unstable

💖 tasknc(1) — the tasknc manual 💖

okay so bestie, welcome to the tasknc manual ✨ this is the page for tasknc(1), and it's literally a whole vibe. by mjheagle, no cap.

🌸 NAME 🌸

tasknc — a ncurses wrapper around Taskwarrior, written in C 🫶

by mjheagle

✨ SYNOPSIS ✨

Usage: tasknc [option] [value]

🦋 DESCRIPTION 🦋

tasknc is a ncurses wrapper around the Taskwarrior task manager, in C. that's it, that's the whole flex 💅

🎀 INVOCATION OPTIONS 🎀

  • -h, --help — prints the help message 🥰
  • -v, --version — prints the version of tasknc 👑
  • -d, --debug mode — debug mode, which means no curses gui (feral behavior, honestly). modes can be given as a list, as long as they're all inside a single argument. the modes are:
    • all
    • eval_string
    • task_count
    • trim
    • search
    • set_var
  • -f, --filter — sets an initial filter string 🌈
  • -l, --loglevel loglvl — sets the log level to loglvl, which must be a non-negative integer 🔥

⭐ DEFAULT KEY BINDS ⭐

  • j/k/arrowkeys — navigation up and down 🦋
  • home/g — go to first task
  • end/G — go to last task
  • e — edit selected task ✏️
  • r — reload task list
  • u — run task undo
  • d — delete selected task 💀
  • c — mark selected task as complete ✅
  • a — create a new task
  • v/enter — run task info on selected task
  • s — resort list (it prompts you for the sort order)
  • y — synchronize (runs task sync)
  • q — exit tasknc/pager window 👋
  • / — search for task 🔍
  • n — go to next task result
  • f — filter (prompts you for a filter string)
  • : — open command prompt 🫶

💜 CONFIGURATION 💜

tasknc honors a config file located at:

$XDG_CONFIG_HOME/tasknc/config

or, if $XDG_CONFIG_HOME doesnt exist:

$HOME/.config/tasknc/config

an example config can be found at /usr/share/tasknc/config 🎁

the configuration file contains a series of commands, and those commands follow the format of the commands listed below, iykyk.

🌈 COMMANDS 🌈

commands are either supplied at the command prompt or listed in the configuration file — they're used to configure tasknc to behave as you desire ✨

add — creates a new task and opens it for editing.

bind mode key function args — assigns function to run every time key is pressed in mode. defining keys is described in the KEYS section. functions are anything listed in COMMANDS.

color object foreground background rule — assigns an object to be a color when rule is satisfied. only task objects evaluate rules 😌 the following objects are available:

  • error — error messages
  • header — title bar & pager title
  • task — tasks in task list

colors are specified in one of three formats:

  • integer — the number of the color you desire, where -1 is default
  • colorNNN — where NNN is the color you desire in 3 digits
  • color string — where the following colors are recognized: black, red, green, yellow, blue, magenta, cyan, and white

rules are specified in the following format: ~pattern arg. pattern is a single character; if it's lowercase it indicates a positive match, and if it's uppercase it indicates a negative match. regular expression arguments must be enclosed in single quotes 👀 the following patterns are available:

  • s — task is selected
  • t — task is started
  • p 'regex' — project matches regex
  • d 'regex' — description matches regex
  • t 'regex' — tags match regex
  • r 'regex' — priority matches regex

command optarg — runs the command optarg, or prompts the user for a command with no arg.

complete — marks selected task as complete ✅

delete — deletes selected task

edit — opens task for editing

dump — will write active task info to the log file. this is mostly for debugging.

scrdump — will write the ncurses screen dump to file. this is mostly for debugging.

filter — applies filter string optarg, or prompts user for a filter string with no arg.

f_redraw — force a redraw of the whole screen.

help — will open the help window, which will list keybinds 🫶

modify optarg — runs task modify on the selected task with modifications specified in optarg, or gathered from a user prompt with no arg.

quit — will exit tasknc.

reload — will force tasknc to re-import the task list.

scroll_down — moves the cursor down

scroll_end — moves the cursor to the end of the task list

scroll_home — moves the cursor to the first task

scroll_up — moves the cursor up

search optarg — searches task list for string optarg, or prompts user for a search string with no arg.

search_next — goes to the next item in the task list that matches the search string.

set variable value — will attempt to set variable to a parsed value. a list of available variables is in the VARIABLES section.

shell command — will run an interactive command. a %s will be replaced with the active task's uuid. the task list will be reloaded after.

shell_bg command — will run a background command. a %s will be replaced with the active task's uuid. the task list will be reloaded after.

show variable — will print the formatted contents of variable to either stdout or the prompt area of the ncurses window.

sort optarg — applies a sort defined by string optarg, or prompts user for sort mode with no arg. the sort string defines the priority of each sort component. tasks will first be compared by the first character's order, then if they're equal, the next character's sort order gets evaluated. the default sort order is due, priority, project, uuid (notated drpu). capitalized characters indicate invert the sort for that field 🙃 the following characters are valid sorts:

  • d — due
  • n — index
  • p — project
  • r — priority
  • u — uuid

source file — read configuration file and run commands that are contained in it.

source_cmd command — run a command and read commands from its output.

stats — will display the output of task stat.

sync — runs task sync.

toggle_start — toggles the task's status as started or stopped.

unbind mode key — will remove all keybindings from a specific key in mode.

undo — runs task undo.

version — will print the version info about tasknc to the prompt area of the ncurses window.

view — will open the view window for the selected task 👑

🍓 VARIABLES 🍓

curs_timeout — an integer variable which is the number of milliseconds after which ncurses options should time out. this variable must be set in the config file. (default: 500)

filter_string — the string which is currently filtering the displayed task list. (default: status:pending)

follow_task — a boolean which dictates whether the selected line will stay selected after the task is chenaged. (default: 1)

history_max — an integer variable which defines the maximum number of history entries for a given prompt. this variable must be set in the config file. (default: 50)

log_level — an integer variable which defines which log messages should be printed. all messages at or below the log level are printed and written to file. (default: 1) log levels:

  • 0 — Default messages
  • 1 — Error messages
  • 2 — Warning messages
  • 3 — Informative messages
  • 4 — Debug messages
  • 5 — Verbose debug messages

program_name — the string which defines the name of the program. this variable is read-only 🔒

program_author — the string which defines the author of tasknc. this variable is read-only 🔒

program_version — the string which defines the version of tasknc. this variable is read-only 🔒

search_string — the string that is currently being searched for. (default: NULL)

selected_line — the integer number of the task which is currently selected.

sort_mode — a character which defines the sort mode. (default: drpu) sort modes:

  • d — due date
  • n — index
  • p — project name
  • r — priority

statusbar_timeout — an integer variable which is the number of seconds after which the message in the statusbar times out. (default: 3)

task_count — the integer number of tasks which are displayed. this variable is read-only 🔒

task_format — the string which defines the format of a displayed task. see FORMATS for more info. this variable must be set in the config file. (default: " $project $description $> ?$due?$due?$-6priority?")

task_version — a string variable which contains the version of Taskwarrior which is being wrapped.

title_format — the string which defines the format of the title bar. see FORMATS for more info. this variable must be set in the config file. (default: " $program_name ($selected_line/$task_count) $> $date")

view_format — the string which defines the format of the title bar of the pager when viewing a task. see FORMATS for more info. this variable must be set in the config file. (default: " task info")

🧚 FORMATS 🧚

formats describe how a line is printed. variables are denoted by a preceding $. the variables listed in the VARIABLES section are all available 💅

if you would like whitespace at the beginning or end of the string, enclose it in double quotes. field length can be specified by a positive integer between the variable indicator ($) and the variable name.

the following additional variables are also available:

  • date — displays the current date.
  • > — marks the beginning of the right-aligned portion of the formatted section.

for task formats, the following variables are available:

  • description
  • due
  • project

🌸 MODES 🌸

  • tasklist
  • pager

🔥 KEYS 🔥

keys may be specified as an integer or character. in addition, special key strings are recognized. when pressing an unbound key, tasknc will display its name in the statusbar message 👀

💀 SIGNALS 💀

if tasknc receives SIGUSR1, it will reload the task list after the next getch timeout (less than one second, by default) ⚡

🙈 BUGS 🙈

please report bugs on http://github.com/lharding/tasknc 🫶

if you experience a segmentation fault, please try the following to attempt an easy fix:

make clean; make

when reporting segmentation faults, please run the valgrind_test.sh script from within the test directory and attach the resulting valgrind_errors file to your bug report 🐛

👑 AUTHOR 👑

maintained by Leander Harding <lsh@lsh.io>

originally developed by mjheagle <mjheagle8@gmail.com>

🌟 CONTRIBUTORS 🌟

special thanks to the following contributors: irl, marcusmueller, prurigo 💖

🎀 SEE ALSO 🎀

task(1)

and that's the whole page, bestie 🫶 this was tasknc — version 2020-12-17, dated 1980-01-01 (iconic honestly), living in section tasknc(1). go forth and slay your task list 💅✨

📦 where this page comes from