Vimania: Todo list management in VIM

modern markdown todo list management in VIM

Key features:

• todo list management with embedded database, keep your todo items within the context/file where they belong, but have a centralized view on it
• no more missing, obsolete or duplicated todos
• Synchronization of todo status between Markdown files and database
• todo lists within code fences in markdown are ignored
• DB entry has a link to the task's source file, so by looking in the DB any Todo can be located.
• Todos are removed from database when removed from markdown file with dd

Installation

1. Install https://github.com/sysid/vimania with your favourite VIM plugin manager
2. Install python requirements.txt into <vimplugins>/vimania/pythonx
3. Install CLI interface: make install (requires pipx)

Example with Plug: Plug 'https://github.com/sysid/vimania-todos.git', {'do': 'pip install -r pythonx/requirements.txt --target pythonx'}

• vim needs to be configured with python support.
• pip must be found in path

CLI interface

• vimania provides a CLI interface with full-text search capabilities to your todo database:

vimania-todos -h
vimania-todos search

The CLI interface is identical to the twbm interface.

Insert Todos convenience method:

I recommend configuring two UltiSnips snippets:

snippet todo "todo for Vimania"
- [ ] ${1:todo}
endsnippet

Dependency

Optional: twbm for seamless bookmark manager integration UltiSnips for easy uri and todo creation

Configuration

Vimenia needs to know, where your Todos database is located: TW_VIMANIA_DB_URL="sqlite:///$HOME/vimania/todos.db"

Implementation Details

Architecture

Todo Management Details

• Todos are recognized via the format: - [ ] todo
• On opening Vimania scans the markdown files and updates existing todos with the current state from the database
• On saving Vimania scans the markdown and saves new or updated todos to the database
• Vimania inserts a DB identifier ('%99%') into the markdown item in order to establish a durable link between DB and markdown item
• The identifier is hidden via VIM's conceal feature
• todo items are deleted by deleting (dd) in normal mode. This triggers a DB update
• todo items deleted by dd in visual mode are NOT delete from DB. This is useful to move tasks from one file to another. Otherwise, you always can move an item by just deleting it in one file and paste in to another file AND then remove the database id ('%99%'). So Vimania kust creates a new entry/link.

Example todo file

After saving the file, the identifiers have been added and the items are saved in DB:

-%1% [ ] purchase piano -%2% [ ] [AIMMS book](file:~/dev/pyomo/tutorial/AIMMS_modeling.pdf)
-%7% [ ] list repos ahead/behind remote

Caveat

• Deleting markdown todo items outside Vimenia will cause inconsistency between the DB and the markdown state.
• Always use dd to delete a markdown item in order to trigger the corresponding DB update
• Never change the identifier '%99%' manually.
• Todo items are always synced from the DB when opening a markdown file, so changes not written back to DB will be lost.

Markdown content other than todo items can be changed arbitrarily, of course.

Fixing inconsistent state

Todos in markdown can get out of sync if updates are made outside of vim, e.g. with another text editor. Don't worry, this can be fixed easily.

entry already in DB

• find the corresponding id in the DB
• add the id to the markdown item: -%99% [ ] markdown item

entry in DB but not in markdown

• you can safely delete the entry in the DB, unless you maintain on purpose todo items in the DB which do not have a counterpart in a markdown (I do).

Resetting everything (advanced)

Deleting/adding todo items outside the control of Vimania can cause an inconsistent state between the database on the markdown files. It is possible to re-synchronize the DB and the todo-lists by creating a new database and clearing the todo items fo their identifier:

1. Reset DB: cd pythonx/vimania-todos/db; rm todos.db; alembic upgrade head
2. Clean up existing markdown files:
   • find all affected markdown files: rg -t md -- '-%\d+%'
   • edit the markdown files and remove the allocated database-id to allow for re-init: sed -i 's/-%[0-9]\+%/-/' todo.md

Vimania Development

VIM needs to find vimania dependencies in pythonx.

VIM Interface

• cannot be tested within PyCharm, needs to be called from VIM.
• For python changes it is important to restart vim after every change in order to enforce proper reload: this is best automated with a Vader script: run_tests.sh testfile in tests directory.
• vimscript changes can be reloaded as usual

Testing

Python: pytest

make test

VIM: Vader

make test-vim

Smoke Test

• after installation with Plug run vader tests

Credits

This is inspired by and recommends to use UltiSnips.

Changelog

CHANGELOG.md