Configuring
***********

You’ll need to configure Todoman before the first usage, using its
simple ini-like configuration file.


Configuration File
==================

The configuration file should be placed in
"$XDG_CONFIG_DIR/todoman/todoman.conf". "$XDG_CONFIG_DIR" defaults to
"~/.config" is most situations, so this will generally be
"~/.config/todoman/todoman.conf".


The [main] section
------------------

cache_path

   The location of the cache file (an sqlite database). This file is
   used to store todo data and speed up execution/startup, and also
   contains the IDs for todos. If the value is not specified, the
   database will be place in the "XDG_CACHE_HOME" directory,
   generally, "~/.cache".

      type:
         cache_path

      default:
color

   By default todoman will disable colored output if stdout is not a
   TTY (value "auto"). Set to "never" to disable colored output
   entirely, or "always" to enable it regardless. This can be
   overridden with the "--color" option.

      type:
         option, allowed values are *always*, *auto* and *never*

      default:
         auto

date_format

   The date format used both for displaying dates, and parsing input
   dates. If this option is not specified the system locale’s is used.

      type:
         date_format

      default:
         %x

default_command

   When running "todo" with no commands, run this command.

      type:
         string

      default:
         list

default_due

   The default difference (in hours) between new todo’s due date and
   creation date. If not specified, the value is 24. If set to 0, the
   due date for new todos will not be set.

      type:
         integer

      default:
         24

default_list

   The default list for adding a todo. If you do not specify this
   option, you must use the "--list" / "-l" option every time you add
   a todo.

      type:
         string

      default:
         None

dt_separator

   The string used to separate date and time when displaying and
   parsing.

      type:
         string

      default:
humanize

   If set to true, datetimes will be printed in human friendly formats
   like “tomorrow”, “in on hour”, “3 weeks ago”, etc.

   If false, datetimes fill be formatted using "date_format" and
   "time_format".

      type:
         boolean

      default:
         False

path

   A glob pattern matching the directories where your todos are
   located. This pattern will be expanded, and each matching directory
   (with any icalendar files) will be treated as a list.

      type:
         string

      default:
         None

startable

   If set to true, only show todos which are currently startable;
   these are todos which have a start date today, or some day in the
   past.  Todos with no start date are always considered current.
   Incomplete todos (eg: partially-complete) # are also included.

      type:
         boolean

      default:
         False

time_format

   The date format used both for displaying times, and parsing input
   times.

      type:
         time_format

      default:
         %X


Sample configuration
====================

The below example should serve as a reference. It will read ics files
from any directory inside "~/.local/share/calendars/", use the
ISO-8601 date format, and set the due date for new todos in 48hs.

   [main]
   # A glob expression which matches all directories relevant.
   path = ~/.local/share/calendars/*
   date_format = %Y-%m-%d
   time_format = %H:%M
   default_list = Personal
   default_due = 48


Color and displayname
=====================

* You can set a color for each task list by creating a "color" file
  containing a colorcode in the format "#RRGGBB".

* A file named "displayname" decides how the task list should be
  named. The default is the directory name.

See also this discussion about metadata for collections in vdirsyncer.
