-
-
Notifications
You must be signed in to change notification settings - Fork 91
Configuration
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
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).
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 youdoing 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.
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.
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".
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
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
.
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
.
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
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.
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
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.