# Usage
<!--toc:start-->
- [Introduction](#introduction)
- [Modes](#modes)
- [Priorities](#priorities)
- [Tags](#tags)
- [Search](#search)
- [Due and completed dates](#due-and-completed-dates)
- [Order](#order)
- [Archived status](#archived-status)
- [Staleness](#staleness)
- [Completion Status](#completion-status)
- [Recurring Tasks](#recurring-tasks)
- [Log](#log)
- [Ignoring Directories](#ignoring-directories)
- [Tips](#tips)
- [Editor Remappings](#editor-remappings)
<!--toc:end-->
## Introduction
This app is meant to be an aid in a task management system where tasks are located within plain text files. Tasks are identified and extracted from files by the following criteria:
* the term "TODO" (in caps) must be in the text of the file
* excluding whitespace, a line in a file starting with `[ ]` or `[]` identifies an incomplete task
* excluding whitespace, a line in a file starting with `[X]` or `[x]` is a completed task
* excluding whitespace, a line in a file starting with `[/]` is a partially completed task
* this also works with markdown lists, so, excluding whitespace, lines starting with `- [ ]`, `- []`, `- [X]`, `- [x]`, `- [/]` are recognized as tasks.
A "task set" is a group of tasks. All tasks following a line containing "TODO" will be in a task set labeled as the full text of that line. Another line containing "TODO" within a file will end one task set and start another.
By default, files are defined as .md and .txt files in a folder named "taskfinder" in your home directory (it will be created if it doesn't exist). However, both the directory and the extensions are configurable. Upon first run, this program will create a configuration file at $HOME/.config/taskfinder/config.toml. You can either edit that file or use the configuration mode (`x`) to change the defaults. Also configurable are:
* how many days constitutes a file being stale
* whether to show completed tasks in Files mode by default
* the text in a file that indicates a priority level ("priority markers")
* the location of the evergreen file
* the mode to start the app in (defaults to Files)
* whether the due date for overdue tasks should blink in Files mode
## Modes
There are six possible modes, which are the top-level navigation of the app:
* Files: View tasks per file. Press `f` to enter this mode. Files are ordered by priority level and then last-modified date.
* Tasks: View tasks from all files. Press `t`. Tasks are organized by due date and then priority level.
* Log: View log of task counts. Press `l`.
* Configuration: Adjust the app's settings. Press `x`.
* Evergreen: View an "evergreen" file that you set in the configuration. Press `e`. This mode will not be shown as an option in the Controls panel unless a path to a file has been set.
* Help: View help (this file). Press `h`. Within help mode, press `v` to view the version of the program you are using.
Files mode and Tasks mode offer a variety of ways to filter your files/tasks: by priority, tag, search term, etc. These are shown in the Controls section of the app, which is always on-screen. Both modes also allow opening your files from your favorite terminal-based text editor, with Tasks mode having the ability to go directly to the line of the file the task is on (if using helix, vi, vim, or neovim).
Tasks mode has an additional feature: you can export your upcoming tasks (those that have a due date within the following two weeks) by pressing `X`. They are saved to a file in your data directory (~/.local/share/taskfinder/upcoming_tasks.md on Linux) and to your system clipboard. This is so you can make them available elsewhere - perhaps email or message them to yourself? NOTE: it uses any current filters you have applied, so if you are viewing tasks that have a particular tag when you press `X`, it will export only those tasks.
## Priorities
Priorities are set by using one of the priority markers (see below) and can be set on files, task sets, and/or individual tasks. Here is how they are set at each level:
* file: use one of the priority markers within the first two lines of a file
* task set: use one of the priority markers on the line that starts a task set, i.e. a line containing "TODO"
* task: use one of the priority markers on the line of the task
Priority will be inherited at each lower level (from file to task set to task) if it doesn't have its own priority. Setting a priority at a lower level overrides any priority from the level above it. That is, if you have a file that has a priority of 5, but a task within it that is explicitly set at 1, the task will have a priority of 1. Similarly, if a task set has a priority of 1 but a task within it has a priority of 5, the task will have a priority of 5. To clear an inherited priority and explicitly mark something as having no priority, use "pri@0".
Priorities can be any string you define, but by default they are, from highest to lowest priority: `pri@1`, `pri@2`, `pri@3`, `pri@4`, `pri@5`. To change these, modify the `priority_markers` list in the configuration file. Note, however: **there must be five of them**.
In Files mode, files will automatically be sorted by these priorities, with the tasks from files without one of these markers shown last. At present, task sets within files are ordered by priority, but tasks within task sets are not. Toggle the priority filter by pressing 1-5.
## Tags
Tags can be defined at the file, task set, or task level, using `#` followed by some text, e.g. `#errands`. At the level of a file, tags must go in the first two lines of the file. At the task set and task level, they go on the same line as the task set heading or task, respectively. Any number of tags can be used.
Like priorities, tags are inherited at each lower level. Unlike priorities, however, they are cumulative. That is, if a file is tagged `#work`, all task sets and tasks within that file are also tagged as `#work`. A task set can then have additional tags, which any tasks within it will inherit. At the lowest level, tasks can have tags that neither their task set or file have.
In Files and Tasks mode, press `#` to open a dialog box to enter a (case-insensitive) tag to filter by. In Files mode, tags will only be displayed in the file at the highest level they apply to.
## Search
You can use `\` to bring up a dialog box to search for exact text to filter files or tasks by. In Files mode, this searches the first two lines of a file. In Tasks mode, it searches the text of the task.
## Due and completed dates
Due and completed dates can be defined on an individual task or a task set. This is done by including them in the format "due:YYYY-MM-DD" or "completed:YYYY-MM-DD" on the same line as the task or the task set heading. When setting a date at the task-set level, the tasks within it will inherit that date unless they you set one on them separately.
In Files mode, dates will be colorized (green for incomplete tasks due after today, yellow for incomplete tasks due today, red for overdue incomplete tasks, and magenta for completed tasks). Additionally, the due date for overdue tasks will blink, but this can be disabled in the configuration. Pressing `d` will show only those files/tasks that contain a due date, while `o` will show only those that are overdue.
In Tasks mode, past due dates will be highlighted in red. Incomplete tasks (the default view) are sorted by due date, while completed tasks are sorted by completed date. (Both have a secondary sort by priority.)
## Order
If all of the above is not enough to organize your tasks, you can also explicitly assign ordering to them. To do so, use two colons and a number, e.g. "::1" or "::10", on the same line as a task. (This is only available at the task level, not at the task-set or file level.) Tasks mode will then take this ordering into account (it is ignored - and not displayed - in Files mode), by ordering tasks first by due date, then by order, then by priority. A column in Tasks mode will show the order given to tasks, if any.
## Archived status
Projects can be completed (so I've heard), or perhaps temporarily or permanently abandoned. Archive them by including the text "@archived" anywhere within the project's file. Press `a` to toggle between archived and active files/tasks in both Files and Tasks modes.
## Staleness
If a file is considered stale (last modified more than `days_to_stale` days ago, with default of 365 initially set in the configuration), no tasks from it will be returned. Press `s` to toggle between stale and active files/tasks in both Files and Tasks mode.
## Completion Status
In Files mode, use `c` to toggle between only incomplete tasks and both incomplete/completed tasks (there is no way to view only completed tasks). This filter is slightly different than the others: changing it does not re-process and sort all of the files, but rather simply shows or hides completed tasks. This way, you always stay on the same file when you toggle it, therefore enabling a quick way to focus only on incomplete tasks, or to also view those tasks you've already completed.
In Tasks mode, you can view incomplete tasks (the default view) or completed tasks. Press `c` to toggle between the two.
## Recurring Tasks
You can denote a recurring task by using a time period within parentheses on the line of the task. The possible characters to use are 1-9 and d, w, m, y. (That's day, week, month, year.) The numbers are optional. Here are some examples:
* (d) or (1d) = daily
* (w) or (1w) = weekly
* (m) or (1m) = monthly
* (y) or (1y) = yearly
* (3d) = every 3 days
* (5w) = every 5 weeks
Doing so enables filtering recurring/nonrecurring tasks in Tasks mode with the `r` key. It will toggle between showing only recurring tasks, then only nonrecurring tasks, and then both together.
## Log
The first time during a day that the program is run, it will log the number of complete and incomplete tasks - both overall and by priority. Note that completed tasks from stale or archived files are included in the count, but incomplete tasks from those files are not. `l` will enter Log mode, showing the log of tasks over time as a table. While in log mode, pressing `g` will display the log as a line graph, showing all completed and all incomplete tasks over time. When viewing the graph, use `c` to cycle through the data by completion status: both -> completed -> incomplete -> both...
## Ignoring Directories
If you'd like to ignore certain directories so that they are excluded from discovery (so that no files or tasks are included from them), put them in a file named "ignore" in taskfinder's configuration folder. On Linux, that is ~/.config/taskfinder. Use absolute paths rather than relative paths, one per line. Be sure to spell out the path (e.g. use `/home/kris/<dir>` rather than `~/<dir>`.)
## Tips
Some things that may improve your experience with taskfinder.
- Put things you may change on a task (like the priority or due date) at the end of the line. Then you can open it in your editor and press its mapping for appending in order to edit from the end of the line.
- `Esc` clears all filters in Files and Tasks modes, but if you only want to clear a tag or search filter, you can open up their dialogs again and then just hit submit without entering any text.
- If you use orders, put them in increments of 5 so you can later easily squeeze things in between them. And/or, use this as a way to signify the amount of time a task will take. Quick tasks? Increment by 1. Longer tasks? Increment by 5 or more.
### Editor Remappings
I used to use vim, and then neovim, but now I use [helix](https://helix-editor.com/). So, for now at least, this is specific to helix, but I'm open to suggestions for other editors or may look into them myself some day.
These would go in your ~/.config/helix/config.toml file.
```toml
# "\\" is how to use \ as the beginning of a mapping,
# and so this is a subtable of keys.normal for \
[keys.normal."\\"]
# taskfinder shortcuts
# mark as done ("[ ]" to "[x]")
X = "@ghxs\\[ \\]<ret>c[x]<esc>"
# mark as done and append completed date to end of line
x = "@ghxs\\[ \\]<ret>c[x]<esc><S-a> completed:<esc>:insert-output date +%%Y-%%m-%%d<ret>:pipe tr -d '\n'<ret>"
```
So, in Tasks mode, you could hit enter on a task, and helix would be opened to the line of that task. Press `\`, then `x` and it would be marked as completed and the current date added as the completed date at the end of the line. (Note this requires two external (but ubiquitous, on UNIX/Linux) programs, `date` and `tr`.)