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