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