Creating and Installing Add ons

Todo.sh add-ons let you add new todo.sh actions or change (override) default actions. Visit the Todo.sh Add-on Directory to find browse available add-ons.

Installing Add-ons

Add-ons can be installed into the $HOME/.todo.actions.d directory or any other directory configured via $TODO_ACTIONS_DIR.

Create this directory with the following bash shell commands:

$ mkdir -p ~/.todo.actions.d

You must name add-ons after the action you want to add or override. For example, create a new "review" action by installing an add-on to .todo.actions.d/review.

After installing the add-on, you must make it executable.

For example:

$ chmod +x ~/.todo.actions.d/review

Alternatively, the add-on can also be placed in a subfolder with the same name as the action (e.g. .todo.actions.d/review/review); this allows you to directly check out separate Git repositories (or Git submodules) into your $TODO_ACTIONS_DIR directory.

Use the new or overridden action the normal todo.sh way.

For example:

$ todo.sh review

You can force todo.sh to use a default action instead of an overridden action by prefixing the action’s name with the word, "command".

For example:

$ todo.sh command ls

Creating Add-ons

Add-ons may be written in any programming language your operating system supports. The first command-line argument to the add-on will be the action called or the word "usage"; the remaining arguments, if any, will be those provided by the user. For example:

$ todo.sh _dummy_action foo bar
First argument: _dummy_action
Remaining arguments:
	* foo
	* bar

If the first argument is usage, you should provide a short usage message that will be displayed when the user calls todo.sh -h.

Todo.sh will also provide your script with several environmental variables including the following documented in todo.sh’s usage message:

• TODOTXT_PRESERVE_LINE_NUMBERS

• TODOTXT_VERBOSE

• TODOTXT_PLAIN

• TODOTXT_AUTO_ARCHIVE

• TODOTXT_FORCE

• TODOTXT_DATE_ON_ADD

and the following environmental variables not documented in the usage message:

• TODO_SH - name of the todo.sh script, use in the usage message

• TODO_FULL_SH - complete path to calling todo.sh script, use for invoking todo.sh

• TODOTXT_CFG_FILE - complete path to user’s todo.sh configuration file

• TODO_DIR - complete path to the todo.txt file

See here for a complete example add-on script.

Aliasing Add-ons

You may want to allow short aliases for those new commands (e.g. "pv" as alias for "projectview")

There is a small issue if you simply duplicate or symlink the add-on file: the corresponding help snippet will be duplicated as well in the output of the todo.sh help command. To avoid that, you can create aliases by creating short add-ons such as this example (replace projectview by the command you want to call with your alias):

#!/bin/bash
[ "$1" = "usage" ] && exit 0
shift
"$TODO_FULL_SH" projectview "$@"