⚠️ Project archived. Have a look at unfog, its successor.

Kronos.vim

A simple task and time manager.

Table of contents

• Requirements
• Usage
  • Create
  • Read
  • Update
  • Start/stop
  • Done
  • Hide done tasks
  • Context
  • Sort
  • Worktime
  • Delete
• Backend
• Import
• Mappings
• Contributing
• Changelog
• Credits

Requirements

• VIM v8+ or NVIM v0.3.4+ (not tested on lower versions)
• Python v3.3+ (check it with :echo has('python3') and :!python3 --version)

Usage

:Kronos

Then you can create, read, update, delete tasks using Vim mapping. The table will automatically readjust when you save the buffer (:w).

Create

To create a task, you can:

• Write or copy a full table line: |id|desc|tags|active|due|
• Follow the Kronos format: <desc> <tags> <due>

A tag should start by a +. You can add as many tags as you need.

A due should start by a :. There is 3 kinds of due:

• The absolute due: :DDMMYY:HHMM, which correspond to a specific date.
• The approximative due, which is a partial absolute, for eg. :DD, ::HH, :DDM:M. Kronos will try to find the closest date matching this due.
• The relative due, which is relative to the actual date. For eg. :1y, :2mo, :4h. Available units: y, mo, w, d, h, m.
  Note: unit order should be respected, from the biggest to the smallest. 2y4mo24m is valid, 3m4d is not.

Here some use cases:

Note: the date format is DD/MM/YYYY HH:MM

Read

To show focused task details, press <K>:

Update

To update a task, just edit the cell and save:

For the due field, you need to use the Kronos due format (:18, :20:1230, 2w...).

Start/stop

To start/stop a task, press <Enter>:

Done

To mark a task as done, delete the line:

Hide done tasks

To show/hide done tasks, press <gh> (for go hide):

Context

The context filters tasks by a list of tags. Once set up:

• You will see only tasks containing at least one tag of your context
• When you create a task, all tags in your context will be assigned to it

To set up a context, press gc (for go to context), and type all tags you want in your context (separated by spaces). Typing an empty context removes it:

Sort

You can sort tasks by pressing gs (for ascending) or gS (for descending). The sort depends on the position of the cursor. For eg, if it's in the ID column, it will sort the ids.

Note: once the tasks sorted, the buffer will be considered as modified, no matter the result.

Worktime

The worktime allows you to check how much time you spent on one or many tags, grouped by day. Press gw (for go to worktime), and type the tags you want to calculate the total worktime:

You can also add a beginning date with >DDMMYY:HHMM and a ending date with <DDMMYY:HHMM. (they can be absolute dues or approximative dues, but not relative dues). Here some valid options:

• tag1 tag2 >18 <20: worktime for tag1, tag2 between the 18th and the 20th of the current month
• tag1 >:10 : worktime for tag1 starting at 10AM of the current day
• tag2 <18:22 : worktime for tag2 ending at 10PM of the 18th of the current month

Delete

To delete a task, delete the line when done tasks are shown:

Backend

By default, Kronos stores tasks in a file (/path/to/vim/pluggins/kronos.vim/.database). You can define an additionnal backend (for now, only Taskwarrior is available):

let g:kronos_backend = 'file' | 'taskwarrior'

This way, tasks will be synchronized with Taskwarrior. It means you can manage basic actions with Kronos, and manage advanced ones with Taskwarrior CLI.

Note: the synchronization is only from Kronos to Taskwarrior. To synchronize from Taskwarrior to Kronos, check the import section below.

Import

If you want to import your Taskwarrior tasks into Kronos, you can use the import.py script at the root folder of the plugin. Usage:

./import.py taskwarrior ./path/to/your/backlog.data

Note: this will erase the current database

Mappings

Here the default mappings:

You can customize them:

nmap <cr>   <plug>(kronos-toggle)
nmap K      <plug>(kronos-info)
nmap gc     <plug>(kronos-context)
nmap gs     <plug>(kronos-sort-asc)
nmap gS     <plug>(kronos-sort-desc)
nmap gh     <plug>(kronos-hide-done)
nmap gw     <plug>(kronos-worktime)
nmap <c-n>  <plug>(kronos-next-cell)
nmap <c-p>  <plug>(kronos-prev-cell)
nmap dic    <plug>(kronos-delete-in-cell)
nmap cic    <plug>(kronos-change-in-cell)
nmap vic    <plug>(kronos-visual-in-cell)

Contributing

Git commit messages follow the Angular Convention, but contain only a subject.

Use imperative, present tense: “change” not “changed” nor “changes”
Don't capitalize first letter
No dot (.) at the end

Code should be as clean as possible, variables and functions use the snake case convention. A line should never contain more than 80 characters.

Tests should be added for each new functionality. Be sure to run tests before proposing a pull request.

Changelog

• Jul. 24, 2019 - Add tasks sorting
• Jul. 23, 2019 - Add option to use Taskwarrior as backend
• May. 14, 2019 - Add relative due + rewrite datetime part in python3
• May. 13, 2019 - Add custom mapping
• May. 12, 2019 - Add script to import tasks from taskwarrior (thanks to KevCui)
• May. 11, 2019 - Remove sync support due to too many complications
• Dec. 31, 2018 - Worktime is now calculated also per day
• Dec. 26, 2018 - Refactor interface (Vimwiki like)
• Oct. 18, 2018 - Refactor code to match the Kronos protocol
• Jul. 05, 2018 - Add context by tags
• Jun. 26, 2018 - Implement Gist sync feature
• Jun. 25, 2018 - Add ability to mark tasks as undone
• Jun. 24, 2018 - Add option to show or hide done tasks
• Jun. 23, 2018 - Init changelog

Credits

• Taskwarrior, a task manager
• Timewarrior, a time manager
• vim-taskwarrior, a Taskwarrior wrapper for vim
• Vimwiki