aboutsummaryrefslogtreecommitdiffstats
path: root/doc/aerc-binds.5.scd
blob: de8f436c19f0c43791b1c99aa21115019c060ee6 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
AERC-BINDS(5)

# NAME

aerc-binds - key bindings configuration file format for *aerc*(1)

# SYNOPSIS

The _binds.conf_ file is used for configuring keybindings used in the aerc
interactive client. It is expected to be in your XDG config home plus _aerc_,
which defaults to _~/.config/aerc/binds.conf_. If the file does not exist, the
built-in default will be installed. An alternate file can be specified via the
_--binds-conf_ command line argument, see *aerc*(1).

This file is written in the ini format with key bindings defined as:

	*<key sequence>* = _<command>_

Where *<key sequence>* is the keystrokes pressed (in order) to invoke this
keybinding, and _<command>_ specifies keystrokes that aerc will simulate when
the keybinding is invoked. Generally this is used to execute commands, for
example:

	*rq* = _:reply -q<Enter>_

Pressing *r*, then *q*, will simulate typing in _:reply -q<Enter>_, and execute
*:reply -q* accordingly. It is also possible to invoke keybindings recursively
in a similar fashion.

You may configure different keybindings for different contexts by writing them
into different *[sections]* of the ini file.

# CONTEXTS

The available contexts are:

*[messages]*
	keybindings for the message list

*[view]*
	keybindings for the message viewer

*[view::passthrough]*
	keybindings for the viewer, when in key passthrough mode
	(toggled with *:toggle-key-passthrough*)

*[compose]*
	keybindings for the message composer

*[compose::editor]*
	keybindings for the composer, when the editor is focused

*[compose::review]*
	keybindings for the composer, when reviewing the email before it's sent

	To customize the description shown on the review screen, add a comment
	(" # ") at the end of the keybinding.

	Example:

		p = :postpone<Enter> # I'll work on it later

*[terminal]*
	keybindings for terminal tabs

You may also configure account specific key bindings for each context:

*[context:account=*_AccountName_*]*
	keybindings for this context and account, where _AccountName_ is a
	regular expression that matches the account name you provided in _accounts.conf_.

Folder and context-specific bindings can be configured for message lists:

*[messages:folder=*_FolderName_*]*++
*[compose:folder=*_FolderName_*]*++
*[compose::editor:folder=*_FolderName_*]*++
*[compose::review:folder=*_FolderName_*]*
	keybindings under this section will be specific to the folder that
	matches the regular expression _FolderName_.
	Keybindings from a folder specifier will take precedence over account specifiers

Examples:

```
[messages:account=Mailbox]
c = :cf path:mailbox/** and<space>

[compose::editor:account=Mailbox2]

[compose::editor:folder=aerc]
y = :send -t aerc

[messages:folder=Drafts]
<Enter> = :recall<Enter>

[messages:folder=Archive/\d+/.*]
gi = :cf Inbox<Enter>
...
```

You may also configure global keybindings by placing them at the beginning of
the file, before specifying any context-specific sections.

Parent keybindings can be erased in the context ones by specifying an "empty"
binding:

```
[compose::review]
a = :attach<space>
d = :deatch<space>

[compose::review:account=no-attachments]
a =
d =
```

# SPECIAL OPTIONS

In addition of user defined key sequences, the following special options are
available in each binding context:

*$noinherit* = _true_|_false_
	If set to _true_, global keybindings will not be effective in this context.

	Default: _false_

*$ex* = _<key-stroke>_
	This can be set to a keystroke which will bring up the command input in this
	context.

	Default: _:_

*$complete* = _<key-stroke>_
	This can be set to a keystroke which will trigger command completion in
	this context for text inputs that support it.

	Default: _<tab>_

	Note: automatic command completion is disabled when simulating
	keystrokes and re-enabled at the end. When *[ui].completion-min-chars*
	is set to _manual_ (see *aerc-config*(5)), it is possible to end
	a keybinding with the completion key to explicitly display the
	completion menu. E.g.:

		*o* = _:cf<space><tab>_

# SUPPORTED KEYS

In addition to letters and some characters (e.g. *a*, *RR*, *gu*, *?*, *!*,
etc.), special keys may be specified in *<angle brackets>*. The syntax for
modified or special keys is:

	<C-A-S-key>

Where C is control, A is alt, S is shift, and key is the named key or character.

Valid key names are:

[[ *Name*
:- *Description*
|  *<space>*
:  " "
|  *<semicolon>*
:  ;
|  *<tab>*
:  Tab
|  *<enter>*
:  Enter
|  *<up>*
:  Up arrow
|  *<down>*
:  Down arrow
|  *<right>*
:  Right arrow
|  *<left>*
:  Left arrow
|  *<pgup>*
:  Page Up
|  *<pgdn>*
:  Page Down
|  *<home>*
:  Home
|  *<end>*
:  End
|  *<insert>*
:  Insert
|  *<delete>*
:  Delete
|  *<backspace>*
:  Backspace
|  *<exit>*
:  Exit
|  *<cancel>*
:  Cancel
|  *<print>*
:  Print screen
|  *<pause>*
:  Pause
|  *<backtab>*
:  Shift+Tab
|  *<esc>*
:  Escape

# SEE ALSO

*aerc*(1) *aerc-config*(5)

# AUTHORS

Originally created by Drew DeVault and maintained by Robin Jarry who is assisted
by other open source contributors. For more information about aerc development,
see _https://sr.ht/~rjarry/aerc/_.