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 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
  18 move 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.
  26 Each 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         "Ctrl-y": "Undo",
  34         "Ctrl-z": "Redo"
  35 }
  36 ```
  37
  38 **Note:** The syntax `<Modifier><key>` is equivalent to `<Modifier>-<key>`. In
  39 addition, Ctrl-Shift bindings are not supported by terminals, and are the same
  40 as simply Ctrl bindings. This means that `CtrlG`, `Ctrl-G`, and `Ctrl-g` all
  41 mean the same thing. However, for Alt this is not the case: `AltG` and `Alt-G`
  42 mean `Alt-Shift-g`, while `Alt-g` does not require the Shift modifier.
  43
  44 In addition to editing your `~/.config/micro/bindings.json`, you can run
  45 `>bind <keycombo> <action>` For a list of bindable actions, see below.
  46
  47 You can also chain commands when rebinding. For example, if you want Alt-s to
  48 save and quit you can bind it like so:
  49
  50 ```json
  51 {
  52     "Alt-s": "Save,Quit"
  53 }
  54 ```
  55
  56 Each action will return a success flag. Actions can be chained such that
  57 the chain only continues when there are successes, or failures, or either.
  58 The `,` separator will always chain to the next action. The `|` separator
  59 will abort the chain if the action preceding it succeeds, and the `&` will
  60 abort the chain if the action preceding it fails. For example, in the default
  61 bindings, tab is bound as
  62
  63 ```
  64 "Tab": "Autocomplete|IndentSelection|InsertTab"
  65 ```
  66
  67 This means that if the `Autocomplete` action is successful, the chain will
  68 abort. Otherwise, it will try `IndentSelection`, and if that fails too, it
  69 will execute `InsertTab`.
  70
  71 ## Binding commands
  72
  73 You can also bind a key to execute a command in command mode (see
  74 `help commands`). Simply prepend the binding with `command:`. For example:
  75
  76 ```json
  77 {
  78     "Alt-p": "command:pwd"
  79 }
  80 ```
  81
  82 **Note for macOS**: By default, macOS terminals do not forward alt events and
  83 instead insert unicode characters. To fix this, do the following:
  84
  85 * iTerm2: select `Esc+` for `Left Option Key` in `Preferences->Profiles->Keys`.
  86 * Terminal.app: Enable `Use Option key as Meta key` in `Preferences->Profiles->Keyboard`.
  87
  88 Now when you press `Alt-p` the `pwd` command will be executed which will show
  89 your working directory in the infobar.
  90
  91 You can also bind an "editable" command with `command-edit:`. This means that
  92 micro won't immediately execute the command when you press the binding, but
  93 instead just place the string in the infobar in command mode. For example,
  94 you could rebind `Ctrl-g` to `> help`:
  95
  96 ```json
  97 {
  98     "Ctrl-g": "command-edit:help "
  99 }
 100 ```
 101
 102 Now when you press `Ctrl-g`, `help` will appear in the command bar and your
 103 cursor will be placed after it (note the space in the json that controls the
 104 cursor placement).
 105
 106 ## Binding raw escape sequences
 107
 108 Only read this section if you are interested in binding keys that aren't on the
 109 list of supported keys for binding.
 110
 111 One of the drawbacks of using a terminal-based editor is that the editor must
 112 get all of its information about key events through the terminal. The terminal
 113 sends these events in the form of escape sequences often (but not always)
 114 starting with `0x1b`.
 115
 116 For example, if micro reads `\x1b[1;5D`, on most terminals this will mean the
 117 user pressed CtrlLeft.
 118
 119 For many key chords though, the terminal won't send any escape code or will
 120 send an escape code already in use. For example for `CtrlBackspace`, my
 121 terminal sends `\u007f` (note this doesn't start with `0x1b`), which it also
 122 sends for `Backspace` meaning micro can't bind `CtrlBackspace`.
 123
 124 However, some terminals do allow you to bind keys to send specific escape
 125 sequences you define. Then from micro you can directly bind those escape
 126 sequences to actions. For example, to bind `CtrlBackspace` you can instruct
 127 your terminal to send `\x1bctrlback` and then bind it in `bindings.json`:
 128
 129 ```json
 130 {
 131     "\u001bctrlback": "DeleteWordLeft"
 132 }
 133 ```
 134
 135 Here are some instructions for sending raw escapes in different terminals
 136
 137 ### iTerm2
 138
 139 In iTerm2, you can do this in  `Preferences->Profiles->Keys` then click the
 140 `+`, input your keybinding, and for the `Action` select `Send Escape Sequence`.
 141 For the above example your would type `ctrlback` into the box (the `\x1b`) is
 142 automatically sent by iTerm2.
 143
 144 ### Linux using loadkeys
 145
 146 You can do this in linux using the loadkeys program.
 147
 148 Coming soon!
 149
 150 ## Unbinding keys
 151
 152 It is also possible to disable any of the default key bindings by use of the
 153 `None` action in the user's `bindings.json` file.
 154
 155 ## Bindable actions and bindable keys
 156
 157 The list of default keybindings contains most of the possible actions and keys
 158 which you can use, but not all of them. Here is a full list of both.
 159
 160 Full list of possible actions:
 161
 162 ```
 163 CursorUp
 164 CursorDown
 165 CursorPageUp
 166 CursorPageDown
 167 CursorLeft
 168 CursorRight
 169 CursorStart
 170 CursorEnd
 171 SelectToStart
 172 SelectToEnd
 173 SelectUp
 174 SelectDown
 175 SelectLeft
 176 SelectRight
 177 SelectToStartOfText
 178 SelectToStartOfTextToggle
 179 WordRight
 180 WordLeft
 181 SelectWordRight
 182 SelectWordLeft
 183 MoveLinesUp
 184 MoveLinesDown
 185 DeleteWordRight
 186 DeleteWordLeft
 187 SelectLine
 188 SelectToStartOfLine
 189 SelectToEndOfLine
 190 InsertNewline
 191 InsertSpace
 192 Backspace
 193 Delete
 194 Center
 195 InsertTab
 196 Save
 197 SaveAll
 198 SaveAs
 199 Find
 200 FindLiteral
 201 FindNext
 202 FindPrevious
 203 Undo
 204 Redo
 205 Copy
 206 CopyLine
 207 Cut
 208 CutLine
 209 DuplicateLine
 210 DeleteLine
 211 IndentSelection
 212 OutdentSelection
 213 OutdentLine
 214 IndentLine
 215 Paste
 216 SelectAll
 217 OpenFile
 218 Start
 219 End
 220 PageUp
 221 PageDown
 222 SelectPageUp
 223 SelectPageDown
 224 HalfPageUp
 225 HalfPageDown
 226 StartOfLine
 227 EndOfLine
 228 StartOfText
 229 StartOfTextToggle
 230 ParagraphPrevious
 231 ParagraphNext
 232 ToggleHelp
 233 ToggleDiffGutter
 234 ToggleRuler
 235 JumpLine
 236 ClearStatus
 237 ShellMode
 238 CommandMode
 239 Quit
 240 QuitAll
 241 AddTab
 242 PreviousTab
 243 NextTab
 244 NextSplit
 245 Unsplit
 246 VSplit
 247 HSplit
 248 PreviousSplit
 249 ToggleMacro
 250 PlayMacro
 251 Suspend (Unix only)
 252 ScrollUp
 253 ScrollDown
 254 SpawnMultiCursor
 255 SpawnMultiCursorUp
 256 SpawnMultiCursorDown
 257 SpawnMultiCursorSelect
 258 RemoveMultiCursor
 259 RemoveAllMultiCursors
 260 SkipMultiCursor
 261 None
 262 JumpToMatchingBrace
 263 Autocomplete
 264 ```
 265
 266 The `StartOfTextToggle` and `SelectToStartOfTextToggle` actions toggle between
 267 jumping to the start of the text (first) and start of the line.
 268
 269 You can also bind some mouse actions (these must be bound to mouse buttons)
 270
 271 ```
 272 MousePress
 273 MouseMultiCursor
 274 ```
 275
 276 Here is the list of all possible keys you can bind:
 277
 278 ```
 279 Up
 280 Down
 281 Right
 282 Left
 283 UpLeft
 284 UpRight
 285 DownLeft
 286 DownRight
 287 Center
 288 PageUp
 289 PageDown
 290 Home
 291 End
 292 Insert
 293 Delete
 294 Help
 295 Exit
 296 Clear
 297 Cancel
 298 Print
 299 Pause
 300 Backtab
 301 F1
 302 F2
 303 F3
 304 F4
 305 F5
 306 F6
 307 F7
 308 F8
 309 F9
 310 F10
 311 F11
 312 F12
 313 F13
 314 F14
 315 F15
 316 F16
 317 F17
 318 F18
 319 F19
 320 F20
 321 F21
 322 F22
 323 F23
 324 F24
 325 F25
 326 F26
 327 F27
 328 F28
 329 F29
 330 F30
 331 F31
 332 F32
 333 F33
 334 F34
 335 F35
 336 F36
 337 F37
 338 F38
 339 F39
 340 F40
 341 F41
 342 F42
 343 F43
 344 F44
 345 F45
 346 F46
 347 F47
 348 F48
 349 F49
 350 F50
 351 F51
 352 F52
 353 F53
 354 F54
 355 F55
 356 F56
 357 F57
 358 F58
 359 F59
 360 F60
 361 F61
 362 F62
 363 F63
 364 F64
 365 CtrlSpace
 366 Ctrl-a
 367 Ctrl-b
 368 Ctrl-c
 369 Ctrl-d
 370 Ctrl-e
 371 Ctrl-f
 372 Ctrl-g
 373 Ctrl-h
 374 Ctrl-i
 375 Ctrl-j
 376 Ctrl-k
 377 Ctrl-l
 378 Ctrl-m
 379 Ctrl-n
 380 Ctrl-o
 381 Ctrl-p
 382 Ctrl-q
 383 Ctrl-r
 384 Ctrl-s
 385 Ctrl-t
 386 Ctrl-u
 387 Ctrl-v
 388 Ctrl-w
 389 Ctrl-x
 390 Ctrl-y
 391 Ctrl-z
 392 CtrlLeftSq
 393 CtrlBackslash
 394 CtrlRightSq
 395 CtrlCarat
 396 CtrlUnderscore
 397 Backspace
 398 OldBackspace
 399 Tab
 400 Esc
 401 Escape
 402 Enter
 403 ```
 404
 405 You can also bind some mouse buttons (they may be bound to normal actions or
 406 mouse actions)
 407
 408 ```
 409 MouseLeft
 410 MouseMiddle
 411 MouseRight
 412 MouseWheelUp
 413 MouseWheelDown
 414 MouseWheelLeft
 415 MouseWheelRight
 416 ```
 417
 418 ## Key sequences
 419
 420 Key sequences can be bound by specifying valid keys one after another in brackets, such
 421 as `<Ctrl-x><Ctrl-c>`.
 422
 423 # Default keybinding configuration.
 424
 425 A select few keybindings are different on MacOS compared to other
 426 operating systems. This is because different OSes have different
 427 conventions for text editing defaults.
 428
 429 ```json
 430 {
 431     "Up":             "CursorUp",
 432     "Down":           "CursorDown",
 433     "Right":          "CursorRight",
 434     "Left":           "CursorLeft",
 435     "ShiftUp":        "SelectUp",
 436     "ShiftDown":      "SelectDown",
 437     "ShiftLeft":      "SelectLeft",
 438     "ShiftRight":     "SelectRight",
 439     "AltLeft":        "WordLeft", (Mac)
 440     "AltRight":       "WordRight", (Mac)
 441     "AltUp":          "MoveLinesUp",
 442     "AltDown":        "MoveLinesDown",
 443     "CtrlShiftRight": "SelectWordRight",
 444     "CtrlShiftLeft":  "SelectWordLeft",
 445     "AltLeft":        "StartOfTextToggle",
 446     "AltRight":       "EndOfLine",
 447     "AltShiftRight":  "SelectWordRight", (Mac)
 448     "AltShiftLeft":   "SelectWordLeft", (Mac)
 449     "CtrlLeft":       "StartOfText", (Mac)
 450     "CtrlRight":      "EndOfLine", (Mac)
 451     "AltShiftLeft":   "SelectToStartOfTextToggle",
 452     "CtrlShiftLeft":  "SelectToStartOfTextToggle", (Mac)
 453     "ShiftHome":      "SelectToStartOfTextToggle",
 454     "AltShiftRight":  "SelectToEndOfLine",
 455     "CtrlShiftRight": "SelectToEndOfLine", (Mac)
 456     "ShiftEnd":       "SelectToEndOfLine",
 457     "CtrlUp":         "CursorStart",
 458     "CtrlDown":       "CursorEnd",
 459     "CtrlShiftUp":    "SelectToStart",
 460     "CtrlShiftDown":  "SelectToEnd",
 461     "Alt-{":          "ParagraphPrevious",
 462     "Alt-}":          "ParagraphNext",
 463     "Enter":          "InsertNewline",
 464     "Ctrl-h":          "Backspace",
 465     "Backspace":      "Backspace",
 466     "Alt-CtrlH":      "DeleteWordLeft",
 467     "Alt-Backspace":  "DeleteWordLeft",
 468     "Tab":            "Autocomplete|IndentSelection|InsertTab",
 469     "Backtab":        "OutdentSelection|OutdentLine",
 470     "Ctrl-o":          "OpenFile",
 471     "Ctrl-s":          "Save",
 472     "Ctrl-f":          "Find",
 473     "Ctrl-n":          "FindNext",
 474     "Ctrl-p":          "FindPrevious",
 475     "Ctrl-z":          "Undo",
 476     "Ctrl-y":          "Redo",
 477     "Ctrl-c":          "CopyLine|Copy",
 478     "Ctrl-x":          "Cut",
 479     "Ctrl-k":          "CutLine",
 480     "Ctrl-d":          "DuplicateLine",
 481     "Ctrl-v":          "Paste",
 482     "Ctrl-a":          "SelectAll",
 483     "Ctrl-t":          "AddTab",
 484     "Alt-,":           "PreviousTab",
 485     "Alt-.":           "NextTab",
 486     "Home":           "StartOfText",
 487     "End":            "EndOfLine",
 488     "CtrlHome":       "CursorStart",
 489     "CtrlEnd":        "CursorEnd",
 490     "PageUp":         "CursorPageUp",
 491     "PageDown":       "CursorPageDown",
 492     "CtrlPageUp":     "PreviousTab",
 493     "CtrlPageDown":   "NextTab",
 494     "Ctrl-g":          "ToggleHelp",
 495     "Alt-g":          "ToggleKeyMenu",
 496     "Ctrl-r":          "ToggleRuler",
 497     "Ctrl-l":          "command-edit:goto ",
 498     "Delete":         "Delete",
 499     "Ctrl-b":          "ShellMode",
 500     "Ctrl-q":          "Quit",
 501     "Ctrl-e":          "CommandMode",
 502     "Ctrl-w":          "NextSplit",
 503     "Ctrl-u":          "ToggleMacro",
 504     "Ctrl-j":          "PlayMacro",
 505     "Insert":         "ToggleOverwriteMode",
 506
 507     // Emacs-style keybindings
 508     "Alt-f": "WordRight",
 509     "Alt-b": "WordLeft",
 510     "Alt-a": "StartOfLine",
 511     "Alt-e": "EndOfLine",
 512
 513     // Integration with file managers
 514     "F2":  "Save",
 515     "F3":  "Find",
 516     "F4":  "Quit",
 517     "F7":  "Find",
 518     "F10": "Quit",
 519     "Esc": "Escape",
 520
 521     // Mouse bindings
 522     "MouseWheelUp":   "ScrollUp",
 523     "MouseWheelDown": "ScrollDown",
 524     "MouseLeft":      "MousePress",
 525     "MouseMiddle":    "PastePrimary",
 526     "Ctrl-MouseLeft": "MouseMultiCursor",
 527
 528     "Alt-n":        "SpawnMultiCursor",
 529     "AltShiftUp":   "SpawnMultiCursorUp",
 530     "AltShiftDown": "SpawnMultiCursorDown",
 531     "Alt-m":        "SpawnMultiCursorSelect",
 532     "Alt-p":        "RemoveMultiCursor",
 533     "Alt-c":        "RemoveAllMultiCursors",
 534     "Alt-x":        "SkipMultiCursor",
 535 }
 536 ```
 537
 538 ## Pane type bindings
 539
 540 Keybindings can be specified for different pane types as well. For example, to
 541 make a binding that only affects the command bar, use the `command` subgroup:
 542
 543 ```
 544 {
 545     "command": {
 546         "Ctrl-w": "WordLeft"
 547     }
 548 }
 549 ```
 550
 551 The possible pane types are `buffer` (normal buffer), `command` (command bar),
 552 and `terminal` (terminal pane). The defaults for the command and terminal panes
 553 are given below:
 554
 555 ```
 556 {
 557     "terminal": {
 558         "<Ctrl-q><Ctrl-q>": "Exit",
 559         "<Ctrl-e><Ctrl-e>": "CommandMode",
 560         "<Ctrl-w><Ctrl-w>": "NextSplit"
 561     },
 562
 563     "command": {
 564         "Up":             "HistoryUp",
 565         "Down":           "HistoryDown",
 566         "Right":          "CursorRight",
 567         "Left":           "CursorLeft",
 568         "ShiftUp":        "SelectUp",
 569         "ShiftDown":      "SelectDown",
 570         "ShiftLeft":      "SelectLeft",
 571         "ShiftRight":     "SelectRight",
 572         "AltLeft":        "StartOfTextToggle",
 573         "AltRight":       "EndOfLine",
 574         "AltUp":          "CursorStart",
 575         "AltDown":        "CursorEnd",
 576         "AltShiftRight":  "SelectWordRight",
 577         "AltShiftLeft":   "SelectWordLeft",
 578         "CtrlLeft":       "WordLeft",
 579         "CtrlRight":      "WordRight",
 580         "CtrlShiftLeft":  "SelectToStartOfTextToggle",
 581         "ShiftHome":      "SelectToStartOfTextToggle",
 582         "CtrlShiftRight": "SelectToEndOfLine",
 583         "ShiftEnd":       "SelectToEndOfLine",
 584         "CtrlUp":         "CursorStart",
 585         "CtrlDown":       "CursorEnd",
 586         "CtrlShiftUp":    "SelectToStart",
 587         "CtrlShiftDown":  "SelectToEnd",
 588         "Enter":          "ExecuteCommand",
 589         "CtrlH":          "Backspace",
 590         "Backspace":      "Backspace",
 591         "OldBackspace":   "Backspace",
 592         "Alt-CtrlH":      "DeleteWordLeft",
 593         "Alt-Backspace":  "DeleteWordLeft",
 594         "Tab":            "CommandComplete",
 595         "Backtab":        "CycleAutocompleteBack",
 596         "Ctrl-z":         "Undo",
 597         "Ctrl-y":         "Redo",
 598         "Ctrl-c":         "CopyLine|Copy",
 599         "Ctrl-x":         "Cut",
 600         "Ctrl-k":         "CutLine",
 601         "Ctrl-v":         "Paste",
 602         "Home":           "StartOfTextToggle",
 603         "End":            "EndOfLine",
 604         "CtrlHome":       "CursorStart",
 605         "CtrlEnd":        "CursorEnd",
 606         "Delete":         "Delete",
 607         "Ctrl-q":         "AbortCommand",
 608         "Ctrl-e":         "EndOfLine",
 609         "Ctrl-a":         "StartOfLine",
 610         "Ctrl-w":         "DeleteWordLeft",
 611         "Insert":         "ToggleOverwriteMode",
 612         "Ctrl-b":         "WordLeft",
 613         "Ctrl-f":         "WordRight",
 614         "Ctrl-d":         "DeleteWordLeft",
 615         "Ctrl-m":         "ExecuteCommand",
 616         "Ctrl-n":         "HistoryDown",
 617         "Ctrl-p":         "HistoryUp",
 618         "Ctrl-u":         "SelectToStart",
 619
 620         // Emacs-style keybindings
 621         "Alt-f": "WordRight",
 622         "Alt-b": "WordLeft",
 623         "Alt-a": "StartOfText",
 624         "Alt-e": "EndOfLine",
 625
 626         // Integration with file managers
 627         "F10": "AbortCommand",
 628         "Esc": "AbortCommand",
 629
 630         // Mouse bindings
 631         "MouseWheelUp":   "HistoryUp",
 632         "MouseWheelDown": "HistoryDown",
 633         "MouseLeft":      "MousePress",
 634         "MouseMiddle":    "PastePrimary"
 635     }
 636 }
 637 ```
 638
 639 ## Final notes
 640
 641 Note: On some old terminal emulators and on Windows machines, `Ctrl-h` should be
 642 used for backspace.
 643
 644 Additionally, alt keys can be bound by using `Alt-key`. For example `Alt-a` or
 645 `Alt-Up`. Micro supports an optional `-` between modifiers like `Alt` and
 646 `Ctrl` so `Alt-a` could be rewritten as `Alta` (case matters for alt bindings).
 647 This is why in the default keybindings you can see `AltShiftLeft` instead of
 648 `Alt-ShiftLeft` (they are equivalent).
 649
 650 Please note that terminal emulators are strange applications and micro only
 651 receives key events that the terminal decides to send. Some terminal emulators
 652 may not send certain events even if this document says micro can receive the
 653 event. To see exactly what micro receives from the terminal when you press a
 654 key, run the `> raw` command.