Some time ago, I stumbled across vimoutliner for organizing lists of to-dos. I am pretty happy with vimoutliner as it boils down to a very simple way for organizing to-do items. To-do items are stored in a plain text file and mark-up etc. is largely reduced. Effectively, managing to-do items is just a matter of editing a text file in Vim, with a few helper key bindings.

However, I wanted some more convenience functionality. So, I finally started to experiment with vimscript in order to implement the functionality I wanted. I called the result with which I came up with “vim-todo-helper” which is available via github. In this post, I briefly introduce vim-todo-helper.

The most improvements I wanted and thus that are currently implemented in vim-todo-helper are:

• a modification date that is associated to to-do items and that gets automatically updated when an item is changed
• a possibility to uniquely identify to-do items independently of their content or time stamp
• the possibility to sort item according to their importance
• means for keeping track of items that were deleted
• and shortcuts, e.g., a template for speeding up the insertion of new items or a shortcut for cycling through importance tags.

In order to demonstrate how these features are intended for being used, below, a simple usage example is given. This example is directly taken from the readme of the vim-todo-helper github project:

Starting with an empty file, you can insert a new to-do item below the current line by pressing “+”. Alternatively, you can use “*” to insert a new to-do above the current line. A possible result is shown below. The “X” marks the spot at which the cursor will be placed.

[_] [3_Low] X <1> {2015-12-12_13:45:57}

You can see that the new entry has an unchecked check box “[_]”, a default priority of “3_Low”, an id of 1, and the date shows the date and time when the entry was created. In a normal work flow, you would now fill in some descriptive text to describe the new task/to-do.

The next example shows a few more sample entries:

[_] [3_Low] A low priority to-do <1> {2015-12-12_13:48:03}
[_] [3_Low] Another low prioroty to-do <2> {2015-12-12_13:48:12}
[_] [2_Normal] A higher priority to-do <3> {2015-12-12_13:48:26}
[_] [0_URGENT] An urgent task <4> {2015-12-12_13:48:40}

Side note: I use the setting “noremap t :call SetNextTag()” in my ~/.vimoutlinerrc to use “t” for cycling through the different priority levels when the cursor is placed on the priority entry.

The next example shows that the timestamps are updated whenever an item is changed:

[X] [3_Low] A low priority to-do (This was marked as done.) <1> {2015-12-12_13:50:03}
[_] [3_Low] Another low priority to-do (Fixed a typo here.) <2> {2015-12-12_13:51:18}
[_] [1_High] Change importance. <3> {2015-12-12_13:51:30}
[_] [0_URGENT] An urgent task <4> {2015-12-12_13:48:40}

When you write the file, a line will be added to the end of the file that contains some housekeeping meta data. The data in this line currently shows the highest used id and a list of deleted items. This data is intended for later use when synchronizing files between multiple computers/devices. An example of how this looks is shown below:

[X] [3_Low] A low priority to-do <1> {2015-12-12_13:50:03}
[_] [3_Low] Another low priority to-do (Fixed a typo here.) <2> {2015-12-12_13:51:18}
[_] [1_High] Change importance. <3> {2015-12-12_13:51:30}
[_] [0_URGENT] An urgent task <4> {2015-12-12_13:48:40}
: <4> {}

Please note that this meta data has to be in the very last line of the file, right now.

Last but not least, an example is given how the content looks after deleting some entries:

[X] [3_Low] A low priority to-do <1> {2015-12-12_13:53:49}
[_] [0_URGENT] An urgent task <4> {2015-12-12_13:48:40}
: <4> {2,3}

Please note: while I use vim-todo-helper in conjunction with vimoutliner, there is no dependency from vim-todo-helper to vimoutliner. vim-todo-helper currently works with “pure” Vim.

This was the first time I used vimscript. So, please bear with me when you look at the code or experience issues. Feedback such as improvement suggestions or contributions is always appreciated.