runtime/help/keybindings.md

   1 # Keybindings
   2
   3 Micro has a plethora of hotkeys that make it easy and powerful to use and all
   4 hotkeys are fully customizable to your liking.
   5
   6 Custom keybindings are stored internally in micro if changed with the `> bind`
   7 command or you can also be added in the file `~/.config/micro/bindings.json` as
   8 discussed below. For a list of the default keybindings in the json format used
   9 by micro, please see the end of this file. For a more user-friendly list with
  10 explanations of what the default hotkeys are and what they do, please see
  11 `> help defaultkeys` (a json formatted list of default keys is included
  12 at the end of this document).
  13
  14 If `~/.config/micro/bindings.json` does not exist, you can simply create it.
  15 Micro will know what to do with it.
  16
  17 You can use the alt keys + arrows to move word by word. Ctrl left and right move
  18 the cursor to the start and end of the line, and ctrl up and down move the
  19 cursor the start and end of the buffer.
  20
  21 You can hold shift with all of these movement actions to select while moving.
  22
  23 ## Rebinding keys
  24
  25 The bindings may be rebound using the `~/.config/micro/bindings.json` file. Each
  26 key is bound to an action.
  27
  28 For example, to bind `Ctrl-y` to undo and `Ctrl-z` to redo, you could put the
  29 following in the `bindings.json` file.
  30
  31 ```json
  32 {
  33         "CtrlY": "Undo",
  34         "CtrlZ": "Redo"
  35 }
  36 ```
  37
  38 In addition to editing your `~/.config/micro/bindings.json`, you can run
  39 `>bind <keycombo> <action>` For a list of bindable actions, see below.
  40
  41 You can also chain commands when rebinding. For example, if you want Alt-s to
  42 save and quit you can bind it like so:
  43
  44 ```json
  45 {
  46     "Alt-s": "Save,Quit"
  47 }
  48 ```
  49
  50 Each action will return a success flag. Actions can be chained such that
  51 the chain only continues when there are successes, or failures, or either.
  52 The `,` separator will always chain to the next action. The `|` separator
  53 will abort the chain if the action preceding it succeeds, and the `&` will
  54 abort the chain if the action preceding it fails. For example, in the default
  55 bindings, tab is bound as
  56
  57 ```
  58 "Tab": "Autocomplete|IndentSelection|InsertTab"
  59 ```
  60
  61 This means that if the `Autocomplete` action is successful, the chain will abort.
  62 Otherwise, it will try `IndentSelection`, and if that fails too, it will
  63 execute `InsertTab`.
  64
  65 ## Binding commands
  66
  67 You can also bind a key to execute a command in command mode (see
  68 `help commands`). Simply prepend the binding with `command:`. For example:
  69
  70 ```json
  71 {
  72     "Alt-p": "command:pwd"
  73 }
  74 ```
  75
  76 Now when you press `Alt-p` the `pwd` command will be executed which will show
  77 your working directory in the infobar.
  78
  79 You can also bind an "editable" command with `command-edit:`. This means that
  80 micro won't immediately execute the command when you press the binding, but
  81 instead just place the string in the infobar in command mode. For example,
  82 you could rebind `CtrlG` to `> help`:
  83
  84 ```json
  85 {
  86     "CtrlG": "command-edit:help "
  87 }
  88 ```
  89
  90 Now when you press `CtrlG`, `help` will appear in the command bar and your cursor will
  91 be placed after it (note the space in the json that controls the cursor placement).
  92
  93 ## Binding raw escape sequences
  94
  95 Only read this section if you are interested in binding keys that aren't on the
  96 list of supported keys for binding.
  97
  98 One of the drawbacks of using a terminal-based editor is that the editor must
  99 get all of its information about key events through the terminal. The terminal
 100 sends these events in the form of escape sequences often (but not always)
 101 starting with `0x1b`.
 102
 103 For example, if micro reads `\x1b[1;5D`, on most terminals this will mean the
 104 user pressed CtrlLeft.
 105
 106 For many key chords though, the terminal won't send any escape code or will send
 107 an escape code already in use. For example for `CtrlBackspace`, my terminal
 108 sends `\u007f` (note this doesn't start with `0x1b`), which it also sends for
 109 `Backspace` meaning micro can't bind `CtrlBackspace`.
 110
 111 However, some terminals do allow you to bind keys to send specific escape
 112 sequences you define. Then from micro you can directly bind those escape
 113 sequences to actions. For example, to bind `CtrlBackspace` you can instruct your
 114 terminal to send `\x1bctrlback` and then bind it in `bindings.json`:
 115
 116 ```json
 117 {
 118     "\u001bctrlback": "DeleteWordLeft"
 119 }
 120 ```
 121
 122 Here are some instructions for sending raw escapes in different terminals
 123
 124 ### iTerm2
 125
 126 In iTerm2, you can do this in  `Preferences->Profiles->Keys` then click the `+`,
 127 input your keybinding, and for the `Action` select `Send Escape Sequence`. For
 128 the above example your would type `ctrlback` into the box (the `\x1b`) is
 129 automatically sent by iTerm2.
 130
 131 ### Linux using loadkeys
 132
 133 You can do this in linux using the loadkeys program.
 134
 135 Coming soon!
 136
 137 ## Unbinding keys
 138
 139 It is also possible to disable any of the default key bindings by use of the
 140 `None` action in the user's `bindings.json` file.
 141
 142 ## Bindable actions and bindable keys
 143
 144 The list of default keybindings contains most of the possible actions and keys
 145 which you can use, but not all of them. Here is a full list of both.
 146
 147 Full list of possible actions:
 148
 149 ```
 150 CursorUp
 151 CursorDown
 152 CursorPageUp
 153 CursorPageDown
 154 CursorLeft
 155 CursorRight
 156 CursorStart
 157 CursorEnd
 158 SelectToStart
 159 SelectToEnd
 160 SelectUp
 161 SelectDown
 162 SelectLeft
 163 SelectRight
 164 WordRight
 165 WordLeft
 166 SelectWordRight
 167 SelectWordLeft
 168 MoveLinesUp
 169 MoveLinesDown
 170 DeleteWordRight
 171 DeleteWordLeft
 172 SelectLine
 173 SelectToStartOfLine
 174 SelectToEndOfLine
 175 InsertNewline
 176 InsertSpace
 177 Backspace
 178 Delete
 179 Center
 180 InsertTab
 181 Save
 182 SaveAll
 183 SaveAs
 184 Find
 185 FindNext
 186 FindPrevious
 187 Undo
 188 Redo
 189 Copy
 190 Cut
 191 CutLine
 192 DuplicateLine
 193 DeleteLine
 194 IndentSelection
 195 OutdentSelection
 196 Paste
 197 SelectAll
 198 OpenFile
 199 Start
 200 End
 201 PageUp
 202 PageDown
 203 SelectPageUp
 204 SelectPageDown
 205 HalfPageUp
 206 HalfPageDown
 207 StartOfLine
 208 EndOfLine
 209 ParagraphPrevious
 210 ParagraphNext
 211 ToggleHelp
 212 ToggleRuler
 213 JumpLine
 214 ClearStatus
 215 ShellMode
 216 CommandMode
 217 Quit
 218 QuitAll
 219 AddTab
 220 PreviousTab
 221 NextTab
 222 NextSplit
 223 Unsplit
 224 VSplit
 225 HSplit
 226 PreviousSplit
 227 ToggleMacro
 228 PlayMacro
 229 Suspend (Unix only)
 230 ScrollUp
 231 ScrollDown
 232 SpawnMultiCursor
 233 SpawnMultiCursorSelect
 234 RemoveMultiCursor
 235 RemoveAllMultiCursors
 236 SkipMultiCursor
 237 None
 238 JumpToMatchingBrace
 239 Autocomplete
 240 ```
 241
 242 You can also bind some mouse actions (these must be bound to mouse buttons)
 243
 244 ```
 245 MousePress
 246 MouseMultiCursor
 247 ```
 248
 249 Here is the list of all possible keys you can bind:
 250
 251 ```
 252 Up
 253 Down
 254 Right
 255 Left
 256 UpLeft
 257 UpRight
 258 DownLeft
 259 DownRight
 260 Center
 261 PageUp
 262 PageDown
 263 Home
 264 End
 265 Insert
 266 Delete
 267 Help
 268 Exit
 269 Clear
 270 Cancel
 271 Print
 272 Pause
 273 Backtab
 274 F1
 275 F2
 276 F3
 277 F4
 278 F5
 279 F6
 280 F7
 281 F8
 282 F9
 283 F10
 284 F11
 285 F12
 286 F13
 287 F14
 288 F15
 289 F16
 290 F17
 291 F18
 292 F19
 293 F20
 294 F21
 295 F22
 296 F23
 297 F24
 298 F25
 299 F26
 300 F27
 301 F28
 302 F29
 303 F30
 304 F31
 305 F32
 306 F33
 307 F34
 308 F35
 309 F36
 310 F37
 311 F38
 312 F39
 313 F40
 314 F41
 315 F42
 316 F43
 317 F44
 318 F45
 319 F46
 320 F47
 321 F48
 322 F49
 323 F50
 324 F51
 325 F52
 326 F53
 327 F54
 328 F55
 329 F56
 330 F57
 331 F58
 332 F59
 333 F60
 334 F61
 335 F62
 336 F63
 337 F64
 338 CtrlSpace
 339 CtrlA
 340 CtrlB
 341 CtrlC
 342 CtrlD
 343 CtrlE
 344 CtrlF
 345 CtrlG
 346 CtrlH
 347 CtrlI
 348 CtrlJ
 349 CtrlK
 350 CtrlL
 351 CtrlM
 352 CtrlN
 353 CtrlO
 354 CtrlP
 355 CtrlQ
 356 CtrlR
 357 CtrlS
 358 CtrlT
 359 CtrlU
 360 CtrlV
 361 CtrlW
 362 CtrlX
 363 CtrlY
 364 CtrlZ
 365 CtrlLeftSq
 366 CtrlBackslash
 367 CtrlRightSq
 368 CtrlCarat
 369 CtrlUnderscore
 370 Backspace
 371 OldBackspace
 372 Tab
 373 Esc
 374 Escape
 375 Enter
 376 ```
 377
 378 You can also bind some mouse buttons (they may be bound to normal actions or
 379 mouse actions)
 380
 381 ```
 382 MouseLeft
 383 MouseMiddle
 384 MouseRight
 385 MouseWheelUp
 386 MouseWheelDown
 387 MouseWheelLeft
 388 MouseWheelRight
 389 ```
 390
 391 # Default keybinding configuration.
 392
 393 ```json
 394 {
 395     "Up":             "CursorUp",
 396     "Down":           "CursorDown",
 397     "Right":          "CursorRight",
 398     "Left":           "CursorLeft",
 399     "ShiftUp":        "SelectUp",
 400     "ShiftDown":      "SelectDown",
 401     "ShiftLeft":      "SelectLeft",
 402     "ShiftRight":     "SelectRight",
 403     "AltLeft":        "WordLeft",
 404     "AltRight":       "WordRight",
 405     "AltUp":          "MoveLinesUp",
 406     "AltDown":        "MoveLinesDown",
 407     "AltShiftRight":  "SelectWordRight",
 408     "AltShiftLeft":   "SelectWordLeft",
 409     "CtrlLeft":       "StartOfLine",
 410     "CtrlRight":      "EndOfLine",
 411     "CtrlShiftLeft":  "SelectToStartOfLine",
 412     "ShiftHome":      "SelectToStartOfLine",
 413     "CtrlShiftRight": "SelectToEndOfLine",
 414     "ShiftEnd":       "SelectToEndOfLine",
 415     "CtrlUp":         "CursorStart",
 416     "CtrlDown":       "CursorEnd",
 417     "CtrlShiftUp":    "SelectToStart",
 418     "CtrlShiftDown":  "SelectToEnd",
 419     "Alt-{":          "ParagraphPrevious",
 420     "Alt-}":          "ParagraphNext",
 421     "Enter":          "InsertNewline",
 422     "CtrlH":          "Backspace",
 423     "Backspace":      "Backspace",
 424     "Alt-CtrlH":      "DeleteWordLeft",
 425     "Alt-Backspace":  "DeleteWordLeft",
 426     "Tab":            "Autocomplete|IndentSelection|InsertTab",
 427     "Backtab":        "OutdentSelection|OutdentLine",
 428     "CtrlO":          "OpenFile",
 429     "CtrlS":          "Save",
 430     "CtrlF":          "Find",
 431     "CtrlN":          "FindNext",
 432     "CtrlP":          "FindPrevious",
 433     "CtrlZ":          "Undo",
 434     "CtrlY":          "Redo",
 435     "CtrlC":          "Copy",
 436     "CtrlX":          "Cut",
 437     "CtrlK":          "CutLine",
 438     "CtrlD":          "DuplicateLine",
 439     "CtrlV":          "Paste",
 440     "CtrlA":          "SelectAll",
 441     "CtrlT":          "AddTab",
 442     "Alt,":           "PreviousTab",
 443     "Alt.":           "NextTab",
 444     "Home":           "StartOfLine",
 445     "End":            "EndOfLine",
 446     "CtrlHome":       "CursorStart",
 447     "CtrlEnd":        "CursorEnd",
 448     "PageUp":         "CursorPageUp",
 449     "PageDown":       "CursorPageDown",
 450     "CtrlPageUp":     "PreviousTab",
 451     "CtrlPageDown":   "NextTab",
 452     "CtrlG":          "ToggleHelp",
 453     "Alt-g":          "ToggleKeyMenu",
 454     "CtrlR":          "ToggleRuler",
 455     "CtrlL":          "command-edit:goto ",
 456     "Delete":         "Delete",
 457     "CtrlB":          "ShellMode",
 458     "CtrlQ":          "Quit",
 459     "CtrlE":          "CommandMode",
 460     "CtrlW":          "NextSplit",
 461     "CtrlU":          "ToggleMacro",
 462     "CtrlJ":          "PlayMacro",
 463     "Insert":         "ToggleOverwriteMode",
 464
 465     // Emacs-style keybindings
 466     "Alt-f": "WordRight",
 467     "Alt-b": "WordLeft",
 468     "Alt-a": "StartOfLine",
 469     "Alt-e": "EndOfLine",
 470
 471     // Integration with file managers
 472     "F2":  "Save",
 473     "F3":  "Find",
 474     "F4":  "Quit",
 475     "F7":  "Find",
 476     "F10": "Quit",
 477     "Esc": "Escape",
 478
 479     // Mouse bindings
 480     "MouseWheelUp":   "ScrollUp",
 481     "MouseWheelDown": "ScrollDown",
 482     "MouseLeft":      "MousePress",
 483     "MouseMiddle":    "PastePrimary",
 484     "Ctrl-MouseLeft": "MouseMultiCursor",
 485
 486     "Alt-n": "SpawnMultiCursor",
 487     "Alt-m": "SpawnMultiCursorSelect",
 488     "Alt-p": "RemoveMultiCursor",
 489     "Alt-c": "RemoveAllMultiCursors",
 490     "Alt-x": "SkipMultiCursor"
 491 }
 492 ```
 493
 494 ## Final notes
 495
 496 Note: On some old terminal emulators and on Windows machines, `CtrlH` should be
 497 used for backspace.
 498
 499 Additionally, alt keys can be bound by using `Alt-key`. For example `Alt-a` or
 500 `Alt-Up`. Micro supports an optional `-` between modifiers like `Alt` and
 501 `Ctrl` so `Alt-a` could be rewritten as `Alta` (case matters for alt bindings).
 502 This is why in the default keybindings you can see `AltShiftLeft` instead of
 503 `Alt-ShiftLeft` (they are equivalent).
 504
 505 Please note that terminal emulators are strange applications and micro only receives
 506 key events that the terminal decides to send. Some terminal emulators may not
 507 send certain events even if this document says micro can receive the event. To see
 508 exactly what micro receives from the terminal when you press a key, run the `> raw`
 509 command.