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 ToggleDiffGutter
 214 ToggleRuler
 215 JumpLine
 216 ClearStatus
 217 ShellMode
 218 CommandMode
 219 Quit
 220 QuitAll
 221 AddTab
 222 PreviousTab
 223 NextTab
 224 NextSplit
 225 Unsplit
 226 VSplit
 227 HSplit
 228 PreviousSplit
 229 ToggleMacro
 230 PlayMacro
 231 Suspend (Unix only)
 232 ScrollUp
 233 ScrollDown
 234 SpawnMultiCursor
 235 SpawnMultiCursorUp
 236 SpawnMultiCursorDown
 237 SpawnMultiCursorSelect
 238 RemoveMultiCursor
 239 RemoveAllMultiCursors
 240 SkipMultiCursor
 241 None
 242 JumpToMatchingBrace
 243 Autocomplete
 244 ```
 245
 246 You can also bind some mouse actions (these must be bound to mouse buttons)
 247
 248 ```
 249 MousePress
 250 MouseMultiCursor
 251 ```
 252
 253 Here is the list of all possible keys you can bind:
 254
 255 ```
 256 Up
 257 Down
 258 Right
 259 Left
 260 UpLeft
 261 UpRight
 262 DownLeft
 263 DownRight
 264 Center
 265 PageUp
 266 PageDown
 267 Home
 268 End
 269 Insert
 270 Delete
 271 Help
 272 Exit
 273 Clear
 274 Cancel
 275 Print
 276 Pause
 277 Backtab
 278 F1
 279 F2
 280 F3
 281 F4
 282 F5
 283 F6
 284 F7
 285 F8
 286 F9
 287 F10
 288 F11
 289 F12
 290 F13
 291 F14
 292 F15
 293 F16
 294 F17
 295 F18
 296 F19
 297 F20
 298 F21
 299 F22
 300 F23
 301 F24
 302 F25
 303 F26
 304 F27
 305 F28
 306 F29
 307 F30
 308 F31
 309 F32
 310 F33
 311 F34
 312 F35
 313 F36
 314 F37
 315 F38
 316 F39
 317 F40
 318 F41
 319 F42
 320 F43
 321 F44
 322 F45
 323 F46
 324 F47
 325 F48
 326 F49
 327 F50
 328 F51
 329 F52
 330 F53
 331 F54
 332 F55
 333 F56
 334 F57
 335 F58
 336 F59
 337 F60
 338 F61
 339 F62
 340 F63
 341 F64
 342 CtrlSpace
 343 CtrlA
 344 CtrlB
 345 CtrlC
 346 CtrlD
 347 CtrlE
 348 CtrlF
 349 CtrlG
 350 CtrlH
 351 CtrlI
 352 CtrlJ
 353 CtrlK
 354 CtrlL
 355 CtrlM
 356 CtrlN
 357 CtrlO
 358 CtrlP
 359 CtrlQ
 360 CtrlR
 361 CtrlS
 362 CtrlT
 363 CtrlU
 364 CtrlV
 365 CtrlW
 366 CtrlX
 367 CtrlY
 368 CtrlZ
 369 CtrlLeftSq
 370 CtrlBackslash
 371 CtrlRightSq
 372 CtrlCarat
 373 CtrlUnderscore
 374 Backspace
 375 OldBackspace
 376 Tab
 377 Esc
 378 Escape
 379 Enter
 380 ```
 381
 382 You can also bind some mouse buttons (they may be bound to normal actions or
 383 mouse actions)
 384
 385 ```
 386 MouseLeft
 387 MouseMiddle
 388 MouseRight
 389 MouseWheelUp
 390 MouseWheelDown
 391 MouseWheelLeft
 392 MouseWheelRight
 393 ```
 394
 395 # Default keybinding configuration.
 396
 397 A select few keybindings are different on MacOS compared to other
 398 operating systems. This is because different OSes have different
 399 conventions for text editing defaults.
 400
 401 ```json
 402 {
 403     "Up":             "CursorUp",
 404     "Down":           "CursorDown",
 405     "Right":          "CursorRight",
 406     "Left":           "CursorLeft",
 407     "ShiftUp":        "SelectUp",
 408     "ShiftDown":      "SelectDown",
 409     "ShiftLeft":      "SelectLeft",
 410     "ShiftRight":     "SelectRight",
 411     "AltLeft":        "WordLeft",
 412     "AltRight":       "WordRight",
 413     "AltUp":          "MoveLinesUp",
 414     "AltDown":        "MoveLinesDown",
 415     "CtrlShiftRight": "SelectWordRight",
 416     "CtrlShiftLeft":  "SelectWordLeft",
 417     "AltLeft":        "StartOfLine",
 418     "AltRight":       "EndOfLine",
 419     "AltShiftRight":  "SelectWordRight", (Mac)
 420     "AltShiftLeft":   "SelectWordLeft", (Mac)
 421     "CtrlLeft":       "StartOfText", (Mac)
 422     "CtrlRight":      "EndOfLine", (Mac)
 423     "AltShiftLeft":   "SelectToStartOfLine",
 424     "CtrlShiftLeft":  "SelectToStartOfText", (Mac)
 425     "ShiftHome":      "SelectToStartOfLine",
 426     "AltShiftRight":  "SelectToEndOfLine",
 427     "CtrlShiftRight": "SelectToEndOfLine", (Mac)
 428     "ShiftEnd":       "SelectToEndOfLine",
 429     "CtrlUp":         "CursorStart",
 430     "CtrlDown":       "CursorEnd",
 431     "CtrlShiftUp":    "SelectToStart",
 432     "CtrlShiftDown":  "SelectToEnd",
 433     "Alt-{":          "ParagraphPrevious",
 434     "Alt-}":          "ParagraphNext",
 435     "Enter":          "InsertNewline",
 436     "CtrlH":          "Backspace",
 437     "Backspace":      "Backspace",
 438     "Alt-CtrlH":      "DeleteWordLeft",
 439     "Alt-Backspace":  "DeleteWordLeft",
 440     "Tab":            "Autocomplete|IndentSelection|InsertTab",
 441     "Backtab":        "OutdentSelection|OutdentLine",
 442     "CtrlO":          "OpenFile",
 443     "CtrlS":          "Save",
 444     "CtrlF":          "Find",
 445     "CtrlN":          "FindNext",
 446     "CtrlP":          "FindPrevious",
 447     "CtrlZ":          "Undo",
 448     "CtrlY":          "Redo",
 449     "CtrlC":          "Copy",
 450     "CtrlX":          "Cut",
 451     "CtrlK":          "CutLine",
 452     "CtrlD":          "DuplicateLine",
 453     "CtrlV":          "Paste",
 454     "CtrlA":          "SelectAll",
 455     "CtrlT":          "AddTab",
 456     "Alt,":           "PreviousTab",
 457     "Alt.":           "NextTab",
 458     "Home":           "StartOfLine",
 459     "End":            "EndOfLine",
 460     "CtrlHome":       "CursorStart",
 461     "CtrlEnd":        "CursorEnd",
 462     "PageUp":         "CursorPageUp",
 463     "PageDown":       "CursorPageDown",
 464     "CtrlPageUp":     "PreviousTab",
 465     "CtrlPageDown":   "NextTab",
 466     "CtrlG":          "ToggleHelp",
 467     "Alt-g":          "ToggleKeyMenu",
 468     "CtrlR":          "ToggleRuler",
 469     "CtrlL":          "command-edit:goto ",
 470     "Delete":         "Delete",
 471     "CtrlB":          "ShellMode",
 472     "CtrlQ":          "Quit",
 473     "CtrlE":          "CommandMode",
 474     "CtrlW":          "NextSplit",
 475     "CtrlU":          "ToggleMacro",
 476     "CtrlJ":          "PlayMacro",
 477     "Insert":         "ToggleOverwriteMode",
 478
 479     // Emacs-style keybindings
 480     "Alt-f": "WordRight",
 481     "Alt-b": "WordLeft",
 482     "Alt-a": "StartOfLine",
 483     "Alt-e": "EndOfLine",
 484
 485     // Integration with file managers
 486     "F2":  "Save",
 487     "F3":  "Find",
 488     "F4":  "Quit",
 489     "F7":  "Find",
 490     "F10": "Quit",
 491     "Esc": "Escape",
 492
 493     // Mouse bindings
 494     "MouseWheelUp":   "ScrollUp",
 495     "MouseWheelDown": "ScrollDown",
 496     "MouseLeft":      "MousePress",
 497     "MouseMiddle":    "PastePrimary",
 498     "Ctrl-MouseLeft": "MouseMultiCursor",
 499
 500     "Alt-n":        "SpawnMultiCursor",
 501     "AltShiftUp":   "SpawnMultiCursorUp",
 502     "AltShiftDown": "SpawnMultiCursorDown",
 503     "Alt-m":        "SpawnMultiCursorSelect",
 504     "Alt-p":        "RemoveMultiCursor",
 505     "Alt-c":        "RemoveAllMultiCursors",
 506     "Alt-x":        "SkipMultiCursor",
 507 }
 508 ```
 509
 510 ## Final notes
 511
 512 Note: On some old terminal emulators and on Windows machines, `CtrlH` should be
 513 used for backspace.
 514
 515 Additionally, alt keys can be bound by using `Alt-key`. For example `Alt-a` or
 516 `Alt-Up`. Micro supports an optional `-` between modifiers like `Alt` and
 517 `Ctrl` so `Alt-a` could be rewritten as `Alta` (case matters for alt bindings).
 518 This is why in the default keybindings you can see `AltShiftLeft` instead of
 519 `Alt-ShiftLeft` (they are equivalent).
 520
 521 Please note that terminal emulators are strange applications and micro only
 522 receives key events that the terminal decides to send. Some terminal emulators
 523 may not send certain events even if this document says micro can receive the
 524 event. To see exactly what micro receives from the terminal when you press a
 525 key, run the `> raw` command.