clikan.sh command line kanban

This shell script provides an interactive command line interface for manipulating files with Markdown formatted lists.

Each list item corresponds to a card of personal kanban system. The three possible list bullets -*+ are used as indicators of status wait/backlog, doing, and done/archived.

The script permits displaying and status changes of the items, addition of a new item as "waiting", direct edition of the lists ("kanban" files) and of the configuration file defining kanbans and some script parameters.

In addition, it will display as "doing" each list item of the pattern - ...(MM-DD)... where MM-DD corresponds to the current month and day.

Installation

Only the script clikanban.sh must be installed somewhere, where it can be executed either directly, or as argument to sh or another reasonable shell. Currently no arguments are processed.

The script currently requires the standard (POSIX conformal) tools sed grep ed cat mktemp cp date for correct function; they should be available on any sane UNIX-like system.

Execution

The script will check for a configuration file and if necessary create one (see Configuration further below). It will scan the defined "kanban files" for "doing" items (with preceding '* ') and display them, then wait for input after a prompt.

A help screen is displayed if an empty command is given, and then also the configuration can be displayed by entering c.

Commands

In the list above, "N" is a number from the last displayed selection list; if none is given, the script asks for one. The numbers are not attributed to specific "cards" but to the items in the last displayed selection list (i.e the first "doing" and the first "waiting" card both have number 1, and it depends on the selection context, which one is referred to).

Be careful with the ek and the ec commands, as the syntax of the corresponding files must be preserved for the script to correctly work. Whitespace in general is no problem, though.

Cards/items do not have any kind of ID number; they are just text, and therefore some strange things may happen if the same entry exists in more than one "kanban file" — in particular, they will all change status (doing/waiting/done) together.

The d command will not only display items with a preceding * but also those with a pattern of .*(MM-DD)* where . may be any one of -*+ and * means any sequence of characters and MM is the current month and DD the current day. This permits to e.g use one "kanban file" as a calendar; in that case it should be given as last kanban entry, to not fill the screen only with calendar entries when using any of the d w a commands (see also example below).

Configuration

The script expects a configuration file named by the environment variable $CLIKANCONF or $HOME/.clikanconf as default. If there isn't any, the script will generate a new one, populated with all possible parameters at reasonable default values, and will also create an item list ("kanban file") with the name $HOME/clikanban.md with some dummy entries.

Please see the source or the generated configuration file for information about possible settings!

Note: if $HOME/clikanban.md already exists, the script will save a backup copy as $HOME/clikanban.md.bak in case something went wrong with the configuration file.

In addition, it uses the contents of $VISUAL or $EDITOR when needing to launch a text editor, or ed as default. (Yay, ed !)

Example

We assume a first start with no environment variables set.

$ ./clikan.sh
 no config found, generating default config file /home/username/.clikanconf
 and default kanban file /home/username/clikanban.md
 (this should happen only once at first use)

   doing
1: learn to use clikan

Default config and kanban files have been generated. Let's see the waiting, the archived/done, and again the "doing" cards:

|< w

   waiting/todo/backlog
1: improve clikan
|< a

   archived/done
1: install clikan
|< d

   doing
1: learn to use clikan

Now let's assume we know everything, so card 1 is done:

|< done 1

   doing
|< w

   waiting/todo/backlog
1: improve clikan

We've seen there is waiting work, so let's do it:

|< do 1

   doing
1: improve clikan

Now we check for the target kanban ...

|< k
1: /home/username/clikanban.md
choice? (default: /home/username/clikanban.md)


   doing
1: improve clikan

... do a manual editing session on it ...

|< ek
calling /bin/ed /home/username/clikanban.md ...
158
1z
# my kanban file

+ learn to use clikan
* improve clikan
+ install clikan

### titles work as comments
# might be a future card you don't yet want in waiting

... change one entry ...

?improve
* improve clikan
s/improve/test/p
* test clikan

... and save it, quit, and we're back at our script:

w
155
q
welcome back

Verifying the entry indeed has been changed:

|< d

   doing
1: test clikan

Now let's add a new card:

|< n
enter new card for target /home/username/clikanban.md :
give feedback to clikan developer

   doing
1: test clikan

The new card has been added to the waiting/backlog list:

|< w

   waiting/todo/backlog
1: give feedback to clikan developer

Just hitting RETURN at the prompt shows the help/usage page:

|<
./clikan.sh : command line kanban
  (2017-06-22 Y.Bonetti)
configuration file: /home/username/.clikanconf
for help about commands, just hit RETURN
to show configuration, enter 'c'

We want to see the configuration, then quit:

c
 CLIKANCONF=
 configfile=/home/username/.clikanconf
 editor=/bin/ed
 maxshow=15
 configfile contents:
    # configuration file for ./clikan.sh
    # (autogenerated at Don Jun 22 17:18:26 CEST 2017)
    # file name can be defined by env.var CLIKANCONF
    #
    #  prompt is displayed when waiting for command
    prompt |<
    #  maxshow defines the maximum number of cards/lines to be displayed
    maxshow 15
    #  kanban defines a kanban file, may be given several times
    # kanban /some/path/to/jobkanban.txt
    # kanban /another/path/to/privatekanban.md
    kanban /home/username/clikanban.md

   doing
1: test clikan
|< q

(2017-June YB)