sponsor Vim development Vim logo Vim Book Ad

ttodo : Edit, view, sort, and filter todo.txt files

 script karma  Rating -1/1, Downloaded by 2654  Comments, bugs, improvements  Vim wiki

created by
Tom Link
script type
This plugin provides the |:Ttodo| command that allow easy filtering and viewing
of todo.txt files (see http://todotxt.com) via |tlib#input#List()|. The plugin

    - search across multiple todo.txt files
    - filter tasks with specific tags, lists etc.
    - subtasks (outlines of complex tasks)
    - hide tasks until a threshold date
    - recurring tasks.

Examples: >

    " Show all tasks; default map (|g:ttodo_nmap|): <Leader>1

    " Show important tasks; default map (|g:ttodo_nmap_important|): <Leader>!

    " Show tasks that are due in the next two weeks
    :Ttodo --due=2w

    " Show tasks with priorities A to C
    :Ttodo --pri=A-C

    " Show tasks matching @Test
    :Ttodo @Test

    " By default, |:Ttodo| scans the todo.txt files in |g:ttodo#dirs|. Users
    " can also scan loaded buffers.
    " Show tasks in the current buffer
    :Ttodo --bufname=%

    " Command-line options can be collected in preference sets (see
    " |g:ttodo#prefs|)
    :Ttodo --pref=work

In order to use this plugin as a ftplugin, users might also want to set
|g:ttodo_enable_ftdetect| to 1 in their |vimrc| file.

If filetype is ttodo, the following default keymaps are enabled:

    <cr> ................. Add a new task;
                           if |g:ttodo#ftplugin#add_at_eof| is true, add the
                           task at the end of file
    <c-cr> ............... Add a new task; copy any list and tags from the
                           current task;
                           if |g:ttodo#ftplugin#add_at_eof| is true, add the
                           task at the end of file
    <s-cr> ............... Add a new subtask
    <LocalLeader>tx ...... Mark "done"
    <LocalLeader>td ...... Mark due in N days
    <LocalLeader>tw ...... Mark due in N weeks
    <LocalLeader>tm ...... Mark due in N months
    <LocalLeader>ty ...... Set priority
    <LocalLeader>ta ...... Archive completed items
    <LocalLeader>tb ...... View, filter items in the current buffer
    <LocalLeader>tn ...... Add a note (the filename uses the first @list tag)
    <LocalLeader>ti ...... Add a hopefully unique ID (an Adler32 hash)

If filetype is ttodo, the following commands are supported:

    |:Ttodoarchive| ...... Archive completed tasks in the current buffer
    |:Ttodobuffer| ....... Show tasks in the current buffer only
    |:Ttodonote| ......... Add a new note to the task at the cursor
    |:Ttodosort| ......... Sort the tasks in the current buffer

As a ftplugin, ttodo supports the following syntax/extensions to todo.txt (see
also https://github.com/ginatrapani/todo.txt-cli/wiki/The-Todo.txt-Format):

    (A) DATE TASK .... A priority as upper case letter (at the beginning of the
    DATE TASK ........ A pending task
    x DATE DATE TASK . A completed task (with completion date)
    indented tasks ... A indented task is a subtask of the parent task; unless
                       `has_subtasks` is true, |:Ttodo| will only show tasks
                       with no open subtasks; this is similar to how the
                       outline addon handles subtasks (see also

A TASK may contain the following tags:

    @list ............ a "list" tag
    +keyword ......... a "keyword" tag
    h:1 .............. hidden task
    due:YYYY-MM-DD ... due dates
    rec:+Nx .......... When marking a task a "done", add a new task with a due
                       date in N d(ays), w(eeks), m(onths), y(ears); with the
                       leading '+' use the original due date; else use the
                       completion date; this is similar to how the Simpletask
                       Android app handles `rec` tags
    t:YYYY-MM-DD ..... Hide the tasks until the given date
    t:-Nd ............ Hide the tasks until N days before the due date

Other ftplugin for todo.txt files, which can be used in conjunction with the
ttodo plugin (if you don't want to use it's |ftplugin|), include:

    - https://github.com/freitass/todo.txt-vim
        - todo-txt.vim : Vim plugin for Todo.txt
          https://github.com/dbeniamine/todo.txt-vim or
    - https://github.com/mivok/vimtodo or
    - https://github.com/davidoc/todo.txt-vim
        - My fork: https://github.com/tomtom/todo.txt-vim-1
    - https://github.com/dsiroky/vim-todotxt
    - ...

Related work:
    - https://github.com/elentok/todo.vim
install details
To install the vimball, edit the vba file and type: >

    :so %

See :help vimball for details.

To install from github, please use
    1. git + a plugin loader like enable_vim, pathogen, vim-unbundle etc.
    2. a plugin manager like VAM, Vundle, NeoBundle, vim-plug etc.

The tlib_vim plugin is required:

Optional enhancement:
- https://github.com/tomtom/autolinker_vim for hyperlinking

Also available via git: http://github.com/tomtom/ttodo_vim


Please set |g:ttodo#dirs| in |vimrc| before using |:Ttodo|.

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
ttodo.zip 1.01 2022-07-22 7.0 Tom Link - s/@inbox/@Inbox/
- Allow for `due:today` shortcut
- list view: FIX invocation of some commands on multiple items
- g:ttodo#ftplugin#edit_note defaults to ''
- syntax: don't accidentally highlight tags, keywords etc. within words
- FIX #1: If g:ttodo#force_filetype evaluates to true, use `set ft=ttodo` instead of `setf ttodo`
- FIX #2: Remove leading whitespace when archiving a sub-task
- FIX #3: Use ttodo#IsValidDue(due) to validate the value of the `due` command-line flag
- FIX handling of --[no-]undated
- Support for rec:Nb business days
- g:ttodo#ftplugin#note_prefix defaults to 'root://'
- syntax/ttodo.vim: TtodoTag: Highlight only known tags
- ttodo#SetCreateDate(): Marking a recurring task as done updates the created date
- require tlib >= 1.22
- <c-cr> also copies notes
- FIX #4: docs for maps
- Misc improvments
- g:ttodo#file_pattern can be a list
- --files command-line option actually works; more checks if a file exists
- Support for @next lists
- Command & map to open todo files in the current working directory
- ttodo#ftplugin#MarkDone(): Don't inherit the @next list for recurrent items
- s:GetFiles(): use map(); etc.
- ftdetect: Also check for upper case TODO.TXT pattern
- FIX parsing of tags & lists; FIX linter warnings
- g:ttodo#ftplugin#new_subtask_copy_pri defaults to 0
- misc improvements
- Use tcomment#type#Define() instead of tcomment#DefineType() for tcomment >= 4.00
- Make the done filename configurable
- Misc improvements to "mark done" & "archive"
- Support for file-local options
SHA256 checksum: 6fcd0ebac1f0a01222ef9b836fd39843921f03a5eab4d93e3c30ec4ad1c4edf1
ttodo.vba 1.00 2016-01-26 7.0 Tom Link - g:ttodo#ftplugin#add_at_eof defaults to 1
- NEW map <localleader>t*
- g:ttodo_enable_ftdetect defaults to 1
- Completion for lists and tags
- Require tlib 1.18
- Command-line completion for Ttodonew
- :Ttodonew respects --pref argument
- ftplugin: lb fo=cql
- Cache each parsed tasks not tasks per file
- Highlight overdue due dates
- Task dependencies, --pending command-line option
- dep:IDs is a comma-separated list
- Sort moves overdue items to the top
- NEW ttodo#ftplugin#AddDep(), map: <LL>tD
- Fix has_lists/tags command-line flag
- s/tlib#type#DefSchema/tlib#type#Define/; require tlib >= 1.19
- ttodo#ftplugin#Archive(): Don't archive tasks with pending sub/tasks
- ttodo#ftplugin#Agent: Allow for "once" expressions as arguments
- g:ttodo#rewrite_gsub: FIX regexp
- NEW g:ttodo#ftplugin#rec_copy: copy recurring tasks when marking them as "done"
- ttodo#ftplugin#MarkDone(): Make sure to inc due date once
- NEW :Ttodogrep
- ttodo#NewTask: FIX handling of inboxfile arg
- Simplify g:ttodo#prefs
- g:ttodo#new_task: pri = C
- NEW ignore_lists, ignore_tags, ignore_pri arguments
- g:ttodo#prefs: important.due = 1w
- g:ttodo#sort_defaults.pri = I
- s:FilterTasks: FIX handling of undated
- NEW ttodo#InputNumber()
- ttodo#ftplugin#MarkDue: Accept count == -1
- NEW Ttodoinbox
- TtodoHidden syntax
- ttodo#ftplugin#MarkDone(): temporarily disallow for outlines with rec: tags; g:ttodo#ftplugin#rec_copy appends new task at the eof
MD5 checksum: a7a364b97ca3e05540974d05a42a797e
ttodo.vba 0.03 2015-11-24 7.0 Tom Link - ttodo#Show: copy(s:list_env)
- NEW :Ttodosort command
- Support for indented subtasks similar to the outline add-on; misc enhancements
- Support for tcomment
- Fix handling of subtasks; <s-cr> map for inserting subtasks; g:ttodo#viewer is a list
- NEW --encoding command-line option
- NEW --bufnr, --bufname command-line options
- Remove dependency on vikitasks plugin
- Use autocmd BufNewFile,BufRead done.txt
- Use <c-1>, <ll>t1 for setting the priority
- ttodo#GetFileTasks: Use tlib#eval#Extend(copy(parent.task), task)
- g:ttodo#viewer is a string; removed last traces of vikitasks
- Configure "hidden" tasks via g:ttodo#task_hide_rx
- NEW :Ttodotask; use y for SetPriority; misc enhancements
- Properly support file-specific args; improved support for subtasks; misc enh.s
- NEW g:ttodo#filesargs: A dictionary of {filename regexp: {additional args}}
- NEW --has_lists=, --has_tags= command-line options
- g:ttodo#sort: s/idx/lnum/
- s/Ttodotask/Ttodonew/
- Misc improvements to ftplugin
- s:GetFiles(): FIX type error
- s:FilterTasks(): Don't use g:ttodo#default_pri
- FIX Ttodosort
- Stop when sorting task outlines
- Warn if subtask has a due date after the parent's task due date
- ttodo#ftplugin#New(): FIX indentation
MD5 checksum: f3cbe1572df17ba026f84166d3857a4b
ttodo.vba 0.02 2015-11-09 7.0 Tom Link - :Ttodo -A, -R, -i, -x command line options; require tlib >= 1.16
- ttodo#CComplete(): use tlib#arg#Complete; misc
- NEW --sort command-line option; vikitask integration for manipulating todo.txt files; misc enh
- NEW own ftplugin; misc improvements
- Require vikitasks >= 1.02
- Use tlib#file#Globpath()
- various improvements
- s/TLibTrace/Tlibtrace/g
- version 0.01-151109
MD5 checksum: e6b8be03504c4a9d948ca4a38de683f3
ttodo.vba 0.01 2015-10-26 7.4 Tom Link Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
Vim at Github