sponsor Vim development Vim logo Vim Book Ad

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

 script karma  Rating -1/1, Downloaded by 2383  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.