README.md

Kronos.vim

A simple task and time manager for vim.

Table of contents

• Introduction
• Usage
  • Add
  • Update
  • Worktime
  • Context
• Mappings
  • List
  • Info
• Configuration
  • Context
  • Hide done tasks
  • Database
  • Gist sync
• License
• Bugs
• Contributing
• Changelog
• Credits

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) <tags>      " Show the total worktime for a task
:Kronos c(ontext)  <tags>      " Define a context by tags

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

Context

To define a context by tags:

:Kronos context <tags>

Eg., to define a context for tag project1 :

:K c project1

Only tasks with tag project1 will be displayed in the list.

If a new task is added with a context set, it will automatically get the tag project1 .

To clear the context, just enter an empty one.

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

kinfo

Configuration

Context

Define a context by default:

g:kronos_context = <string[]>

Default: []

Hide done tasks by default:

g:kronos_hide_done = <boolean>

Default: 1

Database

Path to the database file:

g:kronos_database = <path>

Default: <KRONOS_ROOT_DIR>/kronos.db

Gist sync

Enable Gist sync feature:

g:kronos_gist_sync = <boolean>

This option will synchronize your local database with a secret Gist, so it can be used by other clients, or just act as a backup.

The first time you activate this option, you will need to restart Vim, and a GitHub token will be prompted. To get one, go to this page, click on Generate new token, and check gist scope:

Token description: kronos
Select scopes
  [X] gist         Create gists

This feature requires Vim 8+, with +job option. A port to Neovim is not planed yet, feel free to contribute.

Default: 0

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

• 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 very good Taskwarrior wrapper for vim