/kronos.vim

A simple task and time manager for vim.

Primary LanguageVim ScriptMIT LicenseMIT

Kronos.vim Build Status

A simple task and time manager for vim.

Introduction

Kronos is a simple task and time manager for vim, inspired by Taskwarrior and Timewarrior.

Taskwarrior and Timewarrior are very good and complete tools, but complex and not so easy to understand. Kronos aims to unify both tools in one, and to be more simple (focusing on what it's really needed).

Usage

Kronos comes with a unique command and its alias:

:Kronos <command> <args>
:K      <command> <args>

Here the list of all available commands with their alias:

:Kronos                        " Start the GUI
:Kronos l(ist)                 " List all tasks
:Kronos i(nfo)     <id>        " Show task informations
:Kronos del(ete)   <id>        " Delete a task
:Kronos a(dd)      <args>      " Add a new task
:Kronos u(pdate)   <id> <args> " Update a task
:Kronos sta(rt)    <id>        " Start a task
:Kronos sto(p)     <id>        " Stop a task
:Kronos t(oggle)   <id>        " Start or stop a task
:Kronos d(one)     <id>        " Mark as done a task
:Kronos w(orktime) <id>        " Show the total worktime for a task

Add

To add a new task:

:Kronos add <desc> <tags> <due>

A tag must start by + and should not contain any space. Eg:

:K a +tag +tag-2 +tag_3

A due must start by : and should contain numbers only. The full format of a valid due is :DDMMYY:HHMM but almost everything can be omitted. Here some example to understand better the concept:

  • <day> means the current day (day when the command is executed)
  • <month> means the current month
  • <year> means the current year

Full due:

:K a :100518:1200 " 10th of May 2018, 12h00

If minutes omitted, set to 00:

:K a :100518:12   " 10th of May 2018, 12h00

If hours omitted, set to 00:

:K a :100518      " 10th of May 2018, 00h00

If years omitted, try first the current year. If the final date is exceeded, try with the next year:

:K a :1005        " 10th of May <year> or <year>+1, 00h00

If months omitted, try first the current month. If the final date is exceeded, try with the next month:

:K a :10          " 10th of <month> or <month>+1 <year>, 00h00

If days omitted, try first the current day. If the final date is exceeded try with the next day:

:K a :            " <day> or <day>+1 of <month> <year>, 00h00
:K a ::8          " <day> or <day>+1 of <month> <year>, 08h00

All together:

" Command executed on 1st of March, 2018 at 21h21
:K a my awesome task +firstTask :3:18 +awesome

will result in:

{
  "desc": "my awesome task",
  "tags": ["firstTask", "awesome"],
  "due": "3rd of March 2018, 18h00"
}

The order is not important, tags can be everywhere, and due as well. The desc is the remaining of text present after removing tags and due. Both examples end up with the same result:

:K a my awesome task +firstTask :3:18 +awesome
:K a my +awesame awesome :3:18 +firstTask task

Update

To update a task:

:Kronos update <id> <desc> <tags> <due>

Same usage as kronos-add, except for tags. You can remove an existing tag by prefixing it with a -.

For eg., to remove oldtag and add newtag to task 42:

:K u 42 -oldtag +newtag

Worktime

To print the total worktime for a tag:

:Kronos worktime <tags>

Eg., to print the total worktime for tags tag1 and tag2:

:K w +tag1 +tag2

Mappings

To start the GUI mode:

:Kronos " or simply :K

There is 2 different types of buffer (filetype): klist and kinfo (for tasks list and task info). When you start the GUI mode, you arrive on the klist buffer.

klist

Action Mapping Info
Add <a> Args will be prompted (see kronos-add)
Show info <i> Open the kinfo buffer (see kronos-kinfo)
Update <u> Args will be prompted (see kronos-update)
Delete <Backspace>, <Del> Confirmation will be prompted
Start <s> Start the task under cursor
Stop <S> Stop the task under cursor
Toggle <Enter>, <t> Start or stop the task under cursor
Done <D> Mark task under cursor as done
Refresh <r> Refresh all the GUI
Toggle hide done <H> Show or hide done tasks
Quit <q>, <Esc> Quit the GUI mode

kinfo

Action Mapping Info
Quit <q>, <i>, <Escape> Quit the GUI info mode

Configuration

Hide done tasks by default:

g:kronos_hide_done = <boolean>

Default: 1

Path to the database file:

g:kronos_database = <path>

Default: <KRONOS_ROOT_DIR>/kronos.db

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

Vim code should be as clean as possible, variables use the lowercase abbreviation convention, functions use camel case and constants the uppercase snake case. 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 (via the script run-tests.sh)

Changelog

  • Jun. 24, 2018 - Add option to show or hide done tasks
  • Jun. 23, 2018 - Init changelog

Credits