Change a key

This page shows how to rebind a key, remove one and add one in tt, with three lines of Lua. The spelling of a key and the list of contexts are on Key notation and contexts.

Where the keys are

The default keys are in keybind.lua, in the scripts folder of the root (~/.config/tilde/scripts). Tilde writes the file once, when it is missing, and never changes it again. Tilde runs it at every load of the scripts, before init.lua.

Write your changes in init.lua: a binding there replaces the default, and keybind.lua stays as Tilde wrote it, so the defaults are always there to read. You can also edit keybind.lua itself. An empty keybind.lua means no default keys at all.

Rebind, unbind and add

-- Rebind: J moves a page down in the list, as Ctrl-d does.
keys.bind("list", "J", "index.page-down")

-- Unbind: gg no longer goes to the first message. G and Home still work.
keys.unbind("list", "gg")

-- Add: Space, then q, quits. A function works as well as a command name.
keys.bind("global", "<leader>q", "app.quit", "quit")
keys.bind("list", "gx", function(args) log.info("gx pressed") end, "log gx")

keys.bind(context, lhs, rhs, description) takes:

• the context, which says where the key works (list is the list of messages);
• the keys, lhs, in key notation;
• rhs, the name of a command or a Lua function. The commands of tt are on tt commands and contexts;
• an optional description of the key.

keys.unbind(context, lhs) removes the binding of that context only. A binding of the same keys in global stays. A key that is not bound is ignored.

Binding a key again in the same context replaces the old binding. A function is called with a table of the words of the command. A count typed before the key is the first word, so 5j calls a function bound to j with args[1] equal to "5".

See the change

The scripts load when tt starts, so quit with :q and start tt again. You can also run :scripting.reload on the command line: a reload drops every binding and runs keybind.lua and init.lua again.

To find a mistake without opening tt, load the scripts from the shell:

tcli scripts

A key that cannot be parsed, a digit from 1 to 9 as the first key, or a command name with a space is a script error, and tcli scripts prints it with the line. The name of a command that does not exist is not checked when you bind it: pressing the key shows the message of the command in the bottom bar.

When keybind.lua fails

A Lua error in keybind.lua is reported like any script error, with the source keybind.lua. The lines before the faulty one stay bound. A file that cannot be run at all (a link that is refused, a directory with that name) is replaced by the copy built into the program.

Tilde then binds four keys if they are free, so you are never stuck:

• in global, : opens the command line and ? runs help.show_keys, which opens the list of the key bindings;
• in writing, Enter submits the line and Esc closes it.

init.lua still runs. Fix the line, or compare the file with the defaults, and load the scripts again.

Scripts in general are on Scripts, and the Lua side of the keys on Keys from Lua.