Configuration Files

Aside from the data files in the todo.txt format (see Conforming to), pter's behaviour can be configured through a configuration file.

The configuration file's default location is at ~/.config/pter/pter.conf.

There should have been an example configuration file, example.conf distributed with your copy of pter that can give you an idea on how that works. In this documentation you will find the full explanation.

Note that the configuration file content is case-sensitive!

The configuration file is entirely optional and each option has a default value. That allows you to run pter just fine without ever configuring anything.

The configuration file has these four sections:

• General, for general behaviour,
• Symbols, for icons used in the (task) display,
• Keys, to override default keyboard controls in lists,
• Editor:Keys, to override the default keyboard controls in edit fields (detailed in Keys),
• Colors, for coloring the TUI,
• GUI:Colors, for coloring the tasks in the GUI,
• Highlight, for coloring specific tags of tasks,
• GUI:Highlight, for coloring specific tags of tasks (GUI version, see Highlight).
• GUI, for other GUI specific options

General

use-colors

Whether or not to use colors. Defaults to 'yes'.

scroll-margin

How many lines to show at the lower and upper margin of lists. Defaults to '5'.

safe-save

Safe save means that changes are written to a temporary file and that file is moved over the actual file after writing was completed. Defaults to 'yes'.

This can be problematic if your files are in folders synchronised with cloud services.

search-case-sensitive

Whether or not to search case-sensitive. Defaults to 'yes'.

human-friendly-dates

Here you can define what fields of a task, that are known to contain a date, should be displayed in a more human-friendly way. By default no dates are translated.

Human-friendly means that instead of a 'YYYY-MM-DD' format it might show 'next wednesday', 'tomorrow', or 'in 2 weeks'. It means that dates, that are further away (in the future or the past) will be less precise.

Possible values are due (for due dates), t (for the threshold/tickler dates), completed (for completion dates), created (for creation dates), or all (for all of the above). You can also combine these values by comma separating them like this:

[General]
human-friendly-dates = due, t

task-format

The format string to use for displaying tasks. Defaults to "{selection: >} {nr: >} {done} {tracking }{due }{(pri) }{description}".

See Task Format below for more details.

clear-contexts

A list of comma separated contexts (without the leading @) to remove from a task when it is being marked as done.

For example, you might want to remove the @in context or any @today tags when marking a task as done. In that case clear-contexts should be set to in, today.

default-threshold

The default t: search value to use, even when no other search has been defined. Defaults to 'today'.

This option supports Relative Dates (see pter documentation).

delegation-marker

Marker to add to a task when delegating it. Defaults to @delegated.

delegation-action

Action to take when delegating a task. One of 'none', or 'mail-to' (defaulting to 'mail-to').

'none' does nothing, but 'mail-to' will attempt to start your email program to write an email. If your task has a 'to:' attribute (or whatever you set up for delegation-to, it will be used as the recipient for the email.

delegation-to

Attribute name to use when delegating a task via email. Defaults to to. Eg. "clean the dishes to:bob" will compose the email to "bob" when delegating a task and the delegation action is "mail-to".

editor

The external text editor to use instead of whatever is defined in the VISUAL or EDITOR environment variables. If pter can’t find a valid editor in neither this configuration option nor these environment variables, it will fall back to nano in the wild hopes that it might be installed.

Defaults to nothing, because the environment variables should be all that’s required.

This option is ignored in qpter.

protocols

What protocols should be considered when using the 'Open URL' function on a task. Defaults to http, https, mailto, ftp, ftps.

add-creation-date

Whether or not to automatically add the creation date of a task to it. Defaults to yes.

create-from-search

If set to yes, positive expressions (that do not refer to time or done) of the active search (eg. @context +project word, but not -@context due:+7d done:y -others) will be added automatically to a newly created task. Defaults to no.

auto-id

Whether or not to automatically add an ID to newly created tasks. Defaults to no.

hide-sequential

Whether or not to automatically hide tasks that have uncompleted preceding tasks (see Task Sequences in pter documentation). Defaults to yes.

info-timeout

How long should info messages remain visible in the status bar of the TUI application. Defaults to 5, so 5 seconds.

use-completion

Whether or not to use completion for contexts (@) and projects (+) in the search field, task creation, and task editing fields of the TUI. Defaults to yes.

delete-is

What behaviour the delete function is actually showing. Can be one of these:

• disabled, no functionality at all. There is no delete. This is the default.
• trash, deleted tasks are moved to the trash file (see trash-file option below).
• permanent, actually deletes the task.

trash-file

Where your trash file is. This option is only used if delete-is is set to trash. Defaults to ~/.config/pter/trash.txt.

archive-is

Defines the behaviour of the archive function. Can be one of these:

• relative, the archive file is assumed to be in the same place as the todo.txt file, but called archive.txt,
• centralised, there is only one archive file for all todo.txt files. Its location is controlled by archive-file,
• disabled, there is no archiving.

Defaults to centralised.

archive-file

Where your archive file is. This file will be used to receive archived tasks if the archive-is option is set to centralised. Defaults to ~/.config/pter/archive.txt.

reuse-recurring

Reuse existing recurring task entry instead of creating a new one. If set, completing a task with a rec: (recurring) tag will be reused for the follow-up task instead of creating a new task.

Defaults to no.

related-show-self

Whether or not to show the current task, too, when showing its related tasks. This can be set to yes, no or force.

yes means, not only the related tasks are shown, but also this one.

force is the same as yes, but if the current task does not have an id: attribute, it will be given one. In other words, this option may modify your todo.txt file.

Defaults to yes.

files

Default todo file(s) to load. This option is ignored when pter is given some todo.txt file(s) in the command line parameters.

For example: files = ~/Documents/todo.txt.

To provide multiple files, separate them with newlines, like this:

[General]
files =
    ~/shared/group_todo.txt
    ~/Documents/todo.txt

This option does not apply to qpter, which tracks opened files differently.

notes

The directories where notes should be looked for when references as note: in a task.

For example: notes = ~/Documents/task_notes/.

To provide multiple folder, separate them with newlines, like this:

[General]
notes =
    ~/shared/group_notes/
    ~/Documents/task_notes/

Multiple folders will be searched in order when opening a task note. If no note exists, it will be created in the first given folder.

note-suffix

The file extension that's used when finding notes when the file extension is not provided.

Defaults to .txt.

note-naming

Defines the behaviour of pter when you edit a task's note, but no note: tag is defined.

Possible options are:

• cancel, don't try to edit the task's note
• auto, create a file based on the task's ID, create a task ID if necessary
• user-input, ask the user for the name of the file

Defaults to user-input.

include

Include these configuration files. May be a newline separated list of additional configuration files, or a single additional configuration file to load after this base configuration file has been processed.

Examples:

[General]
include = ~/.pter/extra.conf

or:

[General]
include =
    ~/.pter/extra.conf
    ~/.config/colors/pter.conf

The additional configuration will be loaded in order and may overwrite earlier settings.

Symbols

The following symbols (single unicode characters or even longer strings of unicode characters) can be defined:

• selection, what symbol or string to use to indicate the selected item of a list
• not-done, what symbol or string to use for tasks that are not done
• done, what symbol or string to use for tasks that are done
• overflow-left, what symbol or string to use to indicate that there is more text to the left
• overflow-right, what symbol or string to use to indicate that there is more text to the right
• overdue, the symbol or string for tasks with a due date in the past
• due-today, the symbol or string for tasks with a due date today
• due-tomorrow, the symbol or string for tasks with a due date tomorrow
• tracking, the symbol or string to show that this task is currently being tracked

If you want to use spaces around your symbols, you have to quote them either with ' or ".

An example could be:

[Symbols]
not-done = " "
done = ✔

Keys

In the configuration file you can assign keyboard shortcuts to the various functions in pter and qpter.

For details on how to setup shortcuts for qpter, please see below in section GUI Keys.

There are three main distinct groups of functions. The first, for general lists:

• cancel: cancel or exit the current window or input field
• jump-to: enter a number to jump to that item in the list
• first-item: jump to the first item in a list
• last-item: jump to the last item in a list
• page-up: scroll up by one page
• page-down: scroll down by one page
• next-item: select the next item in a list
• prev-item: select the previous item in a list

Second, there are more complex functions to edit tasks or control pter (for these functions you may use key sequences, see below for details):

• quit: quit the program
• show-help: show the full screen help (only key bindings so far)
• open-manual: open this manual in a browser
• create-task: create a new task
• edit-task: edit the selected task
• edit-external: edit the selected task in an external text editor
• edit-file-external: edit the todo.txt of the selected task in an external editor
• delete-task: delete the selected task or move it to trash, depends on the configuration option delete-is (by default not bound to any key)
• archive: move the selected task to the designated archive file
• load-search: show the saved searches to load one
• open-url: open a URL of the selected task
• refresh-screen: rebuild the GUI
• reload-tasks: enforce reloading of all tasks from all sources
• save-search: save the current search
• search: enter a new search query
• clear-search: clear the search query
• search-context: select a context from the selected task and search for it
• search-project: select a project from the selected task and search for it
• select-context: select a context from all used contexts and search for it
• select-project: select a project from all used projects and search for it
• show-related: show tasks that are related to this one (by means of after: or ref:)
• toggle-done: toggle the "done" state of a task
• toggle-hidden: toggle the "hidden" state of a task
• toggle-tracking: start or stop time tracking for the selected task
• to-clipboard: copy the selected task's full text to clipboard
• delegate: delegate a task
• prio-a: set the selected task's priority to (A)
• prio-b: set the selected task's priority to (B)
• prio-c: set the selected task's priority to (C)
• prio-d: set the selected task's priority to (D)
• prio-none: remove the priority from the selected task
• prio-up: increase the priority of the selected task
• prio-down: decrease the priority of the selected task
• nop: nothing (in case you want to unbind keys)

And finally, the list of functions for edit fields:

• cancel, cancel editing, leave the editor (reverts any changes)
• del-left, delete the character left of the cursor
• del-right, delete the character right of the cursor
• del-to-bol, delete all characters from the cursor to the beginning of the line
• go-bol, move the cursor to the beginning of the line
• go-eol, move the cursor to the end of the line
• go-left, move the cursor one character to the left
• go-right, move the cursor one charackter to the right
• goto-empty, move the cursor to the next tag:value where the is no value
• submit-input, accept the changes, leave the editor (applies the changes)
• select-file, when creating a new task, this allows you to select what todo.txt file to save the task in
• comp-next, next item in the completion list
• comp-prev, previous item in the completion list
• comp-use, use the selected item in the completion list
• comp-close, close the completion list

Keyboard shortcuts are given by their character, for example d. To indicate the shift key, use the upper-case of that letter (D in this example).

To express that the control key should be held down for this shortcut, prefix the letter with ^, like ^d (for control key and the letter "d").

Additionally there are some special keys understood by pter:

• <backspace>
• <del>
• <left> left cursor key
• <right> right cursor key
• <up> cursor key up
• <down> cursor key down
• <pgup> page up
• <pgdn> page down
• <home>
• <end>
• <escape>
• <return>
• <tab>
• <f1> through <f12>

An example could look like this:

[Keys]
^k = quit
<F3> = search
C = create-task

[Keys]
p+ = prio-up
p- = prio-down
pa = prio-a
pb = prio-b
pc = prio-c
pd = prio-d
p0 = prio-none

[GUI:Keys]
new = Ctrl+N
toggle-done = Ctrl+D

Colors

Colors are defined in pairs, separated by comma: foreground and background color. Some color's names come with a sel- prefix so you can define the color when it is a selected list item.

You may decide to only define one value, which will then be used as the text color. The background color will then be taken from normal or sel-normal respectively.

If you do not define the sel- version of a color, pter will use the normal version and put the sel-normal background to it.

If you specify a special background for the normal version, but none for the selected version, the special background of the normal version will be used for the selected version, too!

• normal, any normal text and borders
• sel-normal, selected items in a list
• error, error messages
• sel-overflow, overflow, color for the scrolling indicators when editing tasks (and when selected)
• sel-overdue, overdue, color for a task when it’s due date is in the past (and when selected)
• sel-due-today, due-today, color for a task that’s due today (and when selected)
• sel-due-tomorrow, due-tomorrow, color for a task that’s due tomorrow (and when selected)
• inactive, color for indication of inactive texts
• help, help text at the bottom of the screen
• help-key, color highlighting for the keys in the help
• pri-a, sel-pri-a, color for priority A (and when selected)
• pri-b, sel-pri-b, color for priority B (and when selected)
• pri-c, sel-pri-c, color for priority C (and when selected)
• context, sel-context, color for contexts (and when selected)
• project, sel-project, color for projects (and when selected)
• tracking, sel-tracking, color for tasks that are being tracked right now (and when selected)

If you prefer a red background with green text and a blue context, you could define your colors like this:

[Colors]
normal = 2, 1
sel-normal = 1, 2
context = 4

GUI:Colors

The GUI has a somewhat different coloring scheme. The available colors are:

• normal, any regular text in the description of a task,
• done, color for tasks that are done,
• overdue, text color for overdue tasks,
• due-today, color for tasks that are due today,
• due-tomorrow, color for tasks that are due tomorrow,
• project, color for projects,
• context, color for contexts,
• tracking, color for tasks that are currently being tracked,
• pri-a, color for the priority A,
• pri-b, color for the priority b,
• pri-c, color for the priority C,
• url, color for clickable URLs (see protocols in General)

Highlight

Highlights work exactly like colors, but the color name is whatever tag you want to have colored.

If you wanted to highlight the due: tag of a task, you could define this:

[Highlight]
due = 8, 0

For the GUI, use GUI:Highlight. The colors can be specific as hex values (3, or 6-digits) or named:

[GUI:Highlight]
due = red
t = #4ee
to = #03fe4b

Task Format

The task formatting is a mechanism that allows you to configure how tasks are being displayed in pter. It uses placeholders for elements of a task that you can order and align using a mini language similar to Python’s format specification mini-language, but much less complete.

qpter uses only part of the definition, see below in the list of field names, if you only care for qpter.

If you want to show the task’s age and description, this is your task format:

task-format = {age} {description}

The space between the two fields is printed! If you don’t want a space between, this is your format:

task-format = {age}{description}

You might want to left align the age, to make sure all task descriptions start below each other:

task-format = {age: <}{description}

Now the age field will be left aligned and the right side is filled with spaces. You prefer to fill it with dots?:

task-format = {age:.<}{description}

Right align works the same way, just with >. There is currently no centering.

Suppose you want to surround the age with brackets, then you would want to use this:

task-format = {[age]:.<}{description}

Even if no age is available, you will always see the [...] (the amount of periods depends on the age of the oldest visible task; in this example some task is at least 100 days old).

If you don’t want to show a field, if it does not exist, for example the completion date when a task is not completed, then you must not align it:

task-format = {[age]:.<}{completed}{description}

You can still add extra characters left or right to the field. They will not be shown if the field is missing:

task-format = {[age}:.<}{ completed 😃 }{description}

Now there will be an emoji next to the completion date, or none if the task has no completion date.

All that being said, qpter uses the same task-format configuration option to show tasks, but will disregard some fields (see below) and only use the field names, but not alignment or decorations.

GUI

The GUI specific options are defined in the [GUI] section:

font

The name of the font to use for the task list.

font-size

The font size to use for the task list. You can specify the size either in pixel (eg. 12px) or point size (eg. 14pt). Unlike pixel sizes, point sizes may be a non-integer number, eg. 16.8pt.

single-instance

Whether or not qpter may only be started once.

clickable

If enabled, this allows you to click on URLs (see option protocols in General) to open them in a webbrowser, and to click on contexts and projects to add them to the current search. Disabling this option may improve performance. The default is yes, ie. URLs, contexts, and projects are clickable.

daily-reload

The time (in format HH:MM) when qpter will automatically reload upon passing midnight. Defaults to 00:00.

Include

You can specify additional configuration files by specifying the include option in the [General] section, see above.

The previous method to include a secondary configuration file by means of the [Include] section is deprecated.

Conforming To

pter config files are read using Python's ConfigParser and therefore follow its syntax. For more details, see https://docs.python.org/3/library/configparser.html.

See Also

pter(1), qpter(1)