Skip to content
Brett Terpstra edited this page Mar 18, 2022 · 16 revisions

Doing's main config file is stored in ~/.doingrc, and a skeleton file is created on the first run. Just run doing on its own to create the file.

A basic configuration looks like this:

---
doing_file: /Users/username/Dropbox/doing.taskpaper
doing_file_sort: desc
current_section: Currently
default_template: '%date: %title%note'
default_date_format: '%Y-%m-%d %H:%M'
marker_tag: flagged
marker_color: yellow
tags_color: boldcyan
default_tags: []
paginate: false
:include_notes: true
views:
  color:
    date_format: '%F %_I:%M%P'
    section: Currently
    count: 10
    wrap_width: 0
    template: '%boldblack%date %boldgreen| %boldwhite%title%default%note'
    order: desc
templates:
  default:
    date_format: '%Y-%m-%d %H:%M'
    template: '%date | %title%note'
    wrap_width: 0
  today:
    date_format: '%_I:%M%P'
    template: '%date: %title%odnote'
    wrap_width: 0
  last:
    date_format: '%_I:%M%P on %a'
    template: '%title (at %date)%odnote'
    wrap_width: 0
  recent:
    date_format: '%_I:%M%P'
    template: '%date > %title%odnote'
    wrap_width: 50
    count: 10
autotag:
  whitelist:
  - coding
  - design
  synonyms:
    brainstorming:
    - thinking
    - idea
export_templates:
  css:
  haml:
  markdown:
editors:
  default: vim
  doing_file: TaskPaper
  config: Sublime Text
timer_format: human
duration: true
search:
  matching: pattern
  distance: 3
  case: smart

Updating the config

From time to time a new configuration option is added to Doing, either by a plugin, or just a new feature in development. To incorporate keys that have been added since your .doingrc was created, run doing config update. This will leave existing keys as is, but add any missing keys with their default values (or empty if the option has no default).

Per-folder configuration

Any options found in a .doingrc anywhere in the hierarchy between your current folder and your home folder will be appended to the base configuration, overriding or extending existing options. This allows you to put a .doingrc file into the base of a project and add specific configurations (such as default tags) when working in that project on the command line. These can be cascaded, with the closest .doingrc to your current directory taking precedence.

Configurations are deep merged, and arrays are concatenated. If a configuration value is an array, the new array will be appended to the old array. For example, if you have autotag whitelist tags defined in your base config, and then a local config defines a new array of whitelisted words, the lists will be combined.

Possible uses:

  • Define custom HTML or Markdown output on a per-project basis using the html_template option for custom templates. Customize time tracking reports based on project or client.
  • Define default_tags for a project so that every time you doing now from within that project directory or its subfolders, it gets tagged with that project automatically.
  • Use a different doing_file for each current project, or use top-level directories to define contextual doing files (e.g. work and personal).

Any part of the configuration can be copied into these local files and modified. You only need to include the parts you want to change or add.

To see a list of .doingrc files detected in the current directory tree, run doing config list. Files will be listed in order of precedence; values defined in a file override any matching keys in files below it.

To generate a local .doingrc file for the current directory, you can use doing config set [key] [value]. A menu will be shown allowing you to select from all configuration files, or to generate a new file for the current directory. As a convenience, you can use doing tag_dir [tag...], which will create a local config containing the default_tags key for quickly adding time tracking to a project folder.

Getting and setting individual values

You can use doing config get to quickly see the value of a setting. Run without arguments, it will output the entire configuration (merged with any local .doingrc files found). To get the value for a specific key, provide a dot-separated key path. E.g. to get the wrap_width setting of your default template, run doing config get templates.default.wrap_width. Keys are fuzzy matched, so that can be shortened to doing config get templ.def.wrap or similar. You can change the output format using --output TYPE, where TYPE is yaml, json, or raw.

You can also use doing config set to set a value. Provide a key path and a value, e.g. doing config set templates.default.wrap_width 60. If the key already exists, you can use fuzzy matching (tmpl.def.wrap), but if the key is new in the config file, you need to spell out any missing keys precisely. If local configurations are detected, a menu will be presented asking which file to apply the setting to. This allows you to update config settings in just the current directory tree if desired. Use --remove to remove a key from the config file entirely. Any parent keys left empty by the removal will also be removed.

Common settings

Doing file location

One thing you might want to adjust is the location of the Doing File, possibly to a synced location. That's done using the doing_file key:

doing_file: /Users/username/Dropbox/?? What was I doing.md

I keep mine in my nvUltra folder for quick access and syncing between machines. If desired, you can give it a .taskpaper extension to make it more recognizable to other applications. Any extension will work.

By default the entries in the Doing file are sorted descending by date, with the newest entries in each section at the top. If you'd prefer to have each section sorted oldest to newest, change doing_file_sort to "asc".

"Current actions" section

You can rename the section that holds your current tasks. By default, this is Currently, but if you have some other bright idea, feel free:

current_section: Currently

Default editors

Use the editors section to define what editor apps will be used for commands that require them. An editor can be a command line tool like vim or subl, or (on Mac) an application name like "VS Code" or "TaskPaper."

editors:
  default: vim
  doing_file: TaskPaper
  config: Sublime Text
  pager: less -Xr

default is the fallback for all editor commands. If this isn't defined, whatever is set in $GIT_EDITOR or $EDITOR will be used (in that order).

In the case of the doing now -e command or any command that edits entries or notes, default (or $EDITOR) will be called.

The only requirements for default and editors set in the environment are that they be launchable from the command line and able to "wait." In the case of Sublime Text and TextMate, just use -w like this: subl -w. Vim automatically waits when run from the command line, but if you're using MacVim, you'll need to run mvim -f.

doing_file is the app in which your Doing file will be opened with doing open. This can be any text editor or app (vim, VS Code, TaskPaper). If this is blank, the Doing file will be opened by whatever the system default is for the doing file extension (default is .md), or you can use -a app_name or -b bundle_id to override.

config defines a separate app in which to open the config file when running doing config.

HTML/Markdown Templates

For commands that provide an HTML or Markdown output option, you can customize the templates used for markup and CSS. The HTML markup uses HAML, and the styles are pure CSS. The Markdown template uses Ruby ERB templating.

To see all available template types, run doing template -l. To export the default configurations for customization, use doing template TYPE. This will output to STDOUT where you can pipe it to a file, e.g. doing template haml > my_template.haml.

Once you have a template file prepared, edit .doingrc and look for the export_templates: section. There are sub-values for each available template type. (Run doing config update if you're not seeing a template key you think you should.) Add the template paths to the appropriate keys. A tilde may be substituted for your home directory, e.g. css: ~/styles/doing.css.

Pagination

By default Doing will only page output if you use the --pager global option. You can turn on paging by default (whenever the output is longer than the terminal) with the configuration key:

paginate: true

Natural Language Expansion in Tags

By default Doing will parse natural language date strings it finds in certain tags, including @done and @completed. Entering doing now a quick entry @done(3pm) would expand the @done tag value to a Doing-compatible date string (3pm of the current day). You can apply this to your own custom tags if needed, just add the tags to match to the date_tags key:

date_tags: ['completed?', deferred]

Note that 'completed?' is actually a pattern. All of the values will be read as regular expressions, so you can use regex syntax in your pattern to match multiple tags. In this case both @complete and @completed will have their dates parsed.

Invalid date strings are ignored. If the value of a date_tag isn't parseable as a date string, its original content will be left in place.

Search Settings

You can control the way searching is performed using the search settings. See Tag And Search Filtering for details.

search:
  matching: pattern # pattern, fuzzy, or exact
  distance: 3       # distance allowed between letters when fuzzy matching
  case: smart       # sensitive, ignore, or smart
  highlight: true   # highlight search results in terminal output

Output Formatting

The key timer_format affects how tag totals are displayed when view commands are given the --totals option. The default is "text", which will display the tag name followed by DD:HH:MM formatted time. If you set it to "human", a nicer ascii display will be output with totals listed in "XXh XXm" format. Other formats include "markdown", "html", and "json", but these are primarily for use in other output formats.

The key interval_format is the same as timer_format, but applies to time intervals (%interval) and durations (%duration). It can be human, text, or any of the recognized formatters:

key example
clock 01:01:20
hmclock 25:20
dhm 1d 1h 20m
hm 25h 20m
m 80m
tight 1d1h20m
natural 1 day, 1 hour, 20 minutes
speech 1 day, 1 hour, and 20 minutes

The key duration can be applied to the root or to any template. If set to true, entries that don't have a @done tag can display an elapsed time since they were created (or reset). Requires that you include %duration in your templates.

For template formatting, see Templates

To configure custom views with presets, see Custom Views

See Autotagging for automatic tagging configuration.