# Usage ## Modes There are four possible modes: * Files: View tasks per file. Press `f` to enter this mode. The app starts in this mode. Files are ordered by priority level and last modified date. * Log: View log of task counts. Press `l`. * 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`. There's not much more to say about the Evergreen and Help modes, and only a little bit more to say about Log mode. So, first we'll touch upon Log mode and then the remainder of this document will mostly focus on Files mode. ## 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 achived 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. ## Tasks, task sets, files, and configuration How tasks get identified and extracted from files: * 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 labelled 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. Edit the file to change these defaults. Also configurable are: * how many days constitutes a file being stale * whether to include completed tasks by default * the text in a file that indicates a priority level ("priority markers") * the location of the evergreen file ## Priorities Priorities can be set at either the file level or the task-set level. To set the priority on a file, use one of the priority markers (see below) within the first two lines of a file. To set one at the task-set level, include one of the priority markers on the line that starts a task set, i.e. a line containing "TODO". Task sets without a priority will inherit the priority of the file, if any. Priorities can be a 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**. Results will automatically be sorted by these priorities, with the tasks from files without one of these markers shown last. Toggle the priority filter by pressing 1-5. ## Tags Unlike priorities, tags are defined at the file level only, and they must be in the first two lines of the file. Tags are actually just whatever string you pass, so you may follow whatever convention you like. I use the form "@sometag". Press `t` to open a dialog box to enter a tag. ## Due and completed dates If a task (see above on how a task is identified) contains a due date (in the form "due:YYYY-MM-DD"), the date will be colorized (red if in the past and the task is incomplete, green otherwise). Pressing `d` will show only those files that contain a due date. You may also note when a task has been completed by adding "completed:YYYY-MM-DD" to its line. Like due dates, it will be colorized. ## 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. ## Staleness If a file is considered stale (last modified more than `days_to_stale` days ago, with default of 365 initially set in the config file), no tasks from it will be returned. Press `s` to toggle between stale and active files/tasks. ## Completion Status Use `c` to toggle between only incomplete tasks and both incompleted/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. ## Example files Here is the text of two example files to demonstrate the conventions/expectations described above. Explanatory comments for our purposes here start with a '#'. A file with no file-level priority: ```text Tree planting # <- first line/title of the file @thegreatoutdoors # <- tags; no priority at the file level. TODO (preparation) (pri@1): # <- a task set with level 1 (highest) priority. [x] identify sapling to transplant # <- a completed task TODO (actual planting) (pri@2): # <- a task set with a level 2 priority. [/] dig a hole # <- a partially complete task [ ] dig up the sapling # <- an incomplete task [] plant sapling # <- also an incomplete task ``` Another possible configuration: ```text Tree planting @thegreatoutdoors pri@2 # <- priority 2 at the file level TODO (preparation): # <- a task set with no priority [x] identify sapling to transplant - maybe the holly? # <- a note, ignored by program TODO: # <- another task set with no priority [/] dig a hole [ ] dig up the sapling [] plant sapling (due:2025-10-01) # <- an incomplete task with a due date ```