Vimming Things Done: a GTD-ish system which lives in vim.

Text files are great for writing down your projects and tasks. They're crappy for figuring out your TODO list at any given moment. What you need is software to parse your text file and show you the things you could be working on right now, starting with the most relevant.

VTD is this software.

It creates a special buffer for your TODO list -- the "VTD View" -- whose contents are based on an underlying text file. This buffer skips irrelevant items -- such as tasks blocked by other tasks, "home" tasks while you're at work (or vice versa), or tasks you've hidden until a future date. And the items it does show are sorted by importance: "Late" before "Due" before "Ready", with higher-priority items first in each category.

Here are a few VTD syntax basics. For more, see example.vtd in this repository, or the unit tests in chiphogg/libvtd.

= A section =

@ An action

# An ordered project: priority one! @p:1
  @ A sub-action (also priority one due to inheritance)
  @ The next sub-action (which is blocked until the first action is done)

- An unordered project
  @ A priority 2 action @p:2
  @ An action with no priority

@ This needs to get done soon! Kind of. <2015-05-15
@ This will be marked as "due" 30 days before the due date <2015-01-01(30)
@ And this can only be done in a long while. >2100-02-14

= More advanced features =

@ Finish reading docs. #readthedocs
@ :vi intro.vtd @after:readthedocs

@ Make some espresso EVERY day [07:00 - 07:45]
  * Comments begin with a '*'.

The following things are awesome.

• Priorities, due dates, "hide-until" dates, and contexts are all inheritable.
  • e.g., if a project is priority 1, all its tasks will be too by default.
• Checking off a task with <Space> is very smooth -- one never has to edit the underlying file!
• Undo and redo work flawlessly
• Support for recurring actions (daily, weekly, and monthly), inboxes, and the "waiting/delegated" list
• Projects without actions show up in the action list, as {MISSING Next Action}

The VTD View buffer is designed to mimic regular files (wherever it makes sense). Interacting with the buffer should feel natural to any vim user.

You check off a task by pressing "spacebar" in the VTD View. Behind the scenes, this constructs a patch command which alters the underlying file, marking the corresponding line as DONE. VTD then re-reads the file and re-displays your system, making it feel as if you altered the View buffer directly.

If you made a mistake or changed your mind, you can hit u to undo and <Ctrl-R> to redo. (VTD keeps infinite undo and redo.)

The following are the biggest pain points.

• Doesn't support a "project-focused" workflow very well (#3)
  • This is often downright confusing.
• Task display: sometimes gives too much information, sometimes too little (#4)
• Haven't figured out how to add/edit from the View (only checkoffs so far) (#5)

A key goal before hitting 1.0 is that users should never need to edit the underlying text file. (Admittedly, I am pretty far from that goal at the moment...)

If you don't have a favourite vim plugin manager, I suggest Vundle or NeoBundle. Simply add the appropriate line(s) to your .vimrc.

Note that VTD is a maktaba-based plugin. If your plugin manager isn't maktaba-enabled -- and right now, none of them are -- you will also need to install maktaba if you haven't already.

Highly recommended: Install glaive for easy configuration.

" These lines go after vundle#begin(), and before vundle#end().
Bundle 'google/maktaba'
Bundle 'google/glaive'
Bundle 'chiphogg/vim-vtd'

" This line needs to go after vundle#end().
call glaive#Install()

" These lines go after neobundle#begin(), and before neobundle#end().
NeoBundle 'google/maktaba'
NeoBundle 'google/glaive'
NeoBundle 'chiphogg/vim-vtd'

" This line needs to go after neobundle#end().
call glaive#Install()

VTD uses maktaba settings. You should set them the easy way, by using Glaive. For example, let's see how to enable keymappings and set the files setting to ['~/todo.vtd']. With Glaive, you can do all that in a single line:

Glaive vtd plugin[mappings] files=`['~/todo.vtd']`

Without Glaive, just use the maktaba settings directly. (And if you don't know how to do that, install Glaive.)

The following sections list the available VTD settings.

(Type: List of strings)

The names of the VTD files to read.

Example:

Glaive vtd files=`['~/todo.vtd', '~/extra.vtd']`

Highly recommended.

Defines a keymapping to enter the VTD View buffer.

With no arguments, this defaults to <Leader>t (see :help <Leader>).

If a string argument is supplied, that string will be the keymapping.

Example:

Glaive vtd plugin[mappings]='qwer'

(This sets a mapping for qwer to enter the VTD View buffer.)

(Type: List of strings)

Contexts to include or exclude by default. (To exclude a context, preface it with a minus sign.)

Example:

Glaive vtd contexts=`['work', '-home']`