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