Repository files navigation

A small lightweight vim plugin to effectively handle your todo lists. Create todo items, add priorities and other attributes, mark them as complete or cancelled, and archive them. Adjust the look to your own liking.

The todo file is just a plain text document, so you can use it everywhere and use any tool to edit it.

Any file with one of the following extensions will be interpreted as atasks file by vim:

• *.TODO
• *.todo
• *.todolist
• *.taskpaper
• *.tasks

A file calledTODO is also valid.

Currently all tasks need to be associated with a project. You can create a project by having a single line end in:. It will be highlighted¹. An example would beMy Things:.

Once you have a project, you can start adding tasks to it by using the<localleader>n or<localleader>N mappings, the former adds a task below the cursor, the latter above it. A task consists of an indented line according to the project's depth i.e. according to how nested it is followed by a marker☐,✓, or✘. The local leader is a key that should be used together with buffer local mappings, essentially filetype specific mappings. You can have the local leader be the space bar by adding the following line to yourvimrc:

let maplocalleader="\<space>"

You can add any custom tag to a task by starting them with an@, such as@important or setting a value like@due(tuesday). Priority attributes (low,medium,high, andcritical) are supported in a special way by provided mappings, and a special syntax highlighting, seeSetting task priority.

You can mark a task aslow,medium,high, orcritical priority. You can toggle the priority by using the same mapping that was used to set the initial priority, or you can immediately change the priority by using the mapping for a different priority.

The priority levels are highlighted in a conspicuous manner¹.

• <localleader> ml marks a task as low priority
• <localleader> mm marks a task as medium priority
• <localleader> mh marks a task as high priority
• <localleader> mc marks a task as critical priority

You can use the following mapping<localleader>S to sort all tasks in the document by priority per project.

To quickly turn a line into a task or vice versa you can use the following mapping:<localleader>t or<localleader>T. The latter also removes any attributes that are present.

Once you've created a task, you can optionally put itin-progress by executing<localleader>b. This can help remind you which tasks you were working on and when you started them. It accomplishes the latter by automatically adding astarted attribute with the current time according to the specified date format. For technical reasons it also adds a unix timestamp. This is required to be able to calculate the amount of time that has passed when marking a task as done or cancelled (seeworked attribute). Ideally this woulnd't be necessary, but vim doesn't provide an api to parse a string back to a{time}.

Once you've completed the task, you can mark it asdone orcancelled by the following 2 mappings respectively:<localleader>d and<localleader>x. This will replace the checkbox by a checkmark✓ in the former case, or by a cancellation mark✘.

Once you complete a task, 2 attributes are added by default.project with as value a list of all the projects the task belong to, anddone with as value the current timestamp. This timestamp can be customized by configuring the following in yourvimrc:

let g:TasksDateFormat = '%Y-%m-%d %H:%M'

As hinted at before, you can easily nest projects. A task is only associated with all its ancestors projects, not its siblings.

Below are the settings that you can currently customize together with their defaults:

• let g:TasksMarkerBase = '☐'
• let g:TasksMarkerInProgress = '»'
• let g:TasksMarkerDone = '✔'
• let g:TasksMarkerCancelled = '✘'
• let g:TasksDateFormat = '%Y-%m-%d %H:%M'
• let g:TasksAttributeMarker = '@'
• let g:TasksArchiveSeparator = '＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿'

Below are all the exposed functions with their default bindings:

• (TasksNewTaskUp):

  • <localleader>n
  • Create a new task below current line.

• (TasksNewTaskDown):

  • <localleader>N
  • Create a new task above current line.

• (TaskBeginTask):

  • <localleader>b
  • Toggle current task between any status and thein-progress status.
    • This adds thestarted attribute when the task isin-progress
    • This adds theworked attribute when the task is no longer in progress.

• (TasksCompleteTask):

  • <localleader>d
  • Toggle current task between any status and thecomplete status.

• (TasksCancelTask):

  • <localleader>x
  • Toggle current task between any status and thecancelled status.

• (TasksArchiveTasks):

  • <localleader>a
  • Archive completed (done, orcancelled) tasks.

• (TasksMarkPriorityLow):

  • <localleader>ml
  • Mark task as low priority.

• (TasksMarkPriorityMedium):

  • <localleader>mm
  • Mark task as medium priority.

• (TasksMarkPriorityHigh):

  • <localleader>mh
  • Mark task as high priority.

• (TasksMarkPriorityCritical):

  • <localleader>mc
  • Mark a task as critical priority.

• (TasksSortTasks):

  • <localleader>S
  • Sort tasks based on their priority.

• (TasksToggleTask):

  • <localleader>t
  • Transform a task into a regular line and vice versa without deleting any existing attributes.

• (TasksToggleAndClearTask):

  • <localleader>T
  • Transform a task into a regular line and vice versa while also deleting any existing attributes.

To define your own mappings, you have 2 options. Modify yourvimrc or add a filetasks.vim inside theafter directory (.vim/after/ftplugin):

• vimrc:

  augroup tasks        autocmd!        au Filetype tasks silent! nmap <buffer> <localleader>tu <Plug>(TasksNewTaskUp)        au Filetype tasks silent! nmap <buffer> <localleader>td <Plug>(TasksNewTaskDown)augroup END

• .vim/after/ftplugin/tasks.vim (orvimfiles/after/ftplugin/tasks.vim on windows)

  silent! nmap <buffer> <localleader>tu <Plug>(TasksNewTaskUp)silent! nmap <buffer> <localleader>td <Plug>(TasksNewTaskDown)

Anything marked with ¹ in the previous sections will hopefully be configurable in the future.

Place this in your.vimrc:

Plugin 'crispydrone/vim-tasks'

... then run the following in Vim:

:source %:PluginInstall

For Vundle version < 0.10.2, replace Plugin with Bundle above.

Place this in your.vimrc:

NeoBundle 'crispydrone/vim-tasks'

... then run the following in Vim:

:source %:NeoBundleInstall

Place this in your.vimrc:

Plug 'crispydrone/vim-tasks'

... then run the following in Vim:

:source %:PlugInstall

Run the following in a terminal:

cd ~/.vim/bundlegit clone https://github.com/crispydrone/vim-tasks

• Fixed issue wheresyntax/tasks.vim could load beforeplugin/tasks.vim

• Fixed issue where a task that's on the last line of a file that doesn't end in a new line wouldn't get archived