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`
  12
  13 If `~/.config/micro/bindings.json` does not exist, you can simply create it.
  14 Micro will know what to do with it.
  15
  16 You can use the alt keys + arrows to move word by word. Ctrl left and right move
  17 the cursor to the start and end of the line, and ctrl up and down move the
  18 cursor the start and end of the buffer.
  19
  20 You can hold shift with all of these movement actions to select while moving.
  21
  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
 123 ## Unbinding keys
 124
 125 It is also possible to disable any of the default key bindings by use of the
 126 `UnbindKey` action in the user's `bindings.json` file.
 127
 128
 129 ## Bindable actions and bindable keys
 130
 131 The list of default keybindings contains most of the possible actions and keys
 132 which you can use, but not all of them. Here is a full list of both.
 133
 134 Full list of possible actions:
 135
 136 ```
 137 CursorUp
 138 CursorDown
 139 CursorPageUp
 140 CursorPageDown
 141 CursorLeft
 142 CursorRight
 143 CursorStart
 144 CursorEnd
 145 SelectToStart
 146 SelectToEnd
 147 SelectUp
 148 SelectDown
 149 SelectLeft
 150 SelectRight
 151 WordRight
 152 WordLeft
 153 SelectWordRight
 154 SelectWordLeft
 155 MoveLinesUp
 156 MoveLinesDown
 157 DeleteWordRight
 158 DeleteWordLeft
 159 SelectLine
 160 SelectToStartOfLine
 161 SelectToEndOfLine
 162 InsertNewline
 163 InsertSpace
 164 Backspace
 165 Delete
 166 Center
 167 InsertTab
 168 Save
 169 SaveAll
 170 SaveAs
 171 Find
 172 FindNext
 173 FindPrevious
 174 Undo
 175 Redo
 176 Copy
 177 Cut
 178 CutLine
 179 DuplicateLine
 180 DeleteLine
 181 IndentSelection
 182 OutdentSelection
 183 Paste
 184 SelectAll
 185 OpenFile
 186 Start
 187 End
 188 PageUp
 189 PageDown
 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 RemoveMultiCursor
 219 RemoveAllMultiCursors
 220 SkipMultiCursor
 221 UnbindKey
 222 JumpToMatchingBrace
 223 ```
 224
 225 You can also bind some mouse actions (these must be bound to mouse buttons)
 226
 227 ```
 228 MousePress
 229 MouseMultiCursor
 230 ```
 231
 232 Here is the list of all possible keys you can bind:
 233
 234 ```
 235 Up
 236 Down
 237 Right
 238 Left
 239 UpLeft
 240 UpRight
 241 DownLeft
 242 DownRight
 243 Center
 244 PageUp
 245 PageDown
 246 Home
 247 End
 248 Insert
 249 Delete
 250 Help
 251 Exit
 252 Clear
 253 Cancel
 254 Print
 255 Pause
 256 Backtab
 257 F1
 258 F2
 259 F3
 260 F4
 261 F5
 262 F6
 263 F7
 264 F8
 265 F9
 266 F10
 267 F11
 268 F12
 269 F13
 270 F14
 271 F15
 272 F16
 273 F17
 274 F18
 275 F19
 276 F20
 277 F21
 278 F22
 279 F23
 280 F24
 281 F25
 282 F26
 283 F27
 284 F28
 285 F29
 286 F30
 287 F31
 288 F32
 289 F33
 290 F34
 291 F35
 292 F36
 293 F37
 294 F38
 295 F39
 296 F40
 297 F41
 298 F42
 299 F43
 300 F44
 301 F45
 302 F46
 303 F47
 304 F48
 305 F49
 306 F50
 307 F51
 308 F52
 309 F53
 310 F54
 311 F55
 312 F56
 313 F57
 314 F58
 315 F59
 316 F60
 317 F61
 318 F62
 319 F63
 320 F64
 321 CtrlSpace
 322 CtrlA
 323 CtrlB
 324 CtrlC
 325 CtrlD
 326 CtrlE
 327 CtrlF
 328 CtrlG
 329 CtrlH
 330 CtrlI
 331 CtrlJ
 332 CtrlK
 333 CtrlL
 334 CtrlM
 335 CtrlN
 336 CtrlO
 337 CtrlP
 338 CtrlQ
 339 CtrlR
 340 CtrlS
 341 CtrlT
 342 CtrlU
 343 CtrlV
 344 CtrlW
 345 CtrlX
 346 CtrlY
 347 CtrlZ
 348 CtrlLeftSq
 349 CtrlBackslash
 350 CtrlRightSq
 351 CtrlCarat
 352 CtrlUnderscore
 353 Backspace
 354 Tab
 355 Esc
 356 Escape
 357 Enter
 358 ```
 359
 360 You can also bind some mouse buttons (they may be bound to normal actions or
 361 mouse actions)
 362
 363 ```
 364 MouseLeft
 365 MouseMiddle
 366 MouseRight
 367 MouseWheelUp
 368 MouseWheelDown
 369 MouseWheelLeft
 370 MouseWheelRight
 371 ```
 372
 373 # Default keybinding configuration.
 374
 375 ```json
 376 {
 377     "Up":             "CursorUp",
 378     "Down":           "CursorDown",
 379     "Right":          "CursorRight",
 380     "Left":           "CursorLeft",
 381     "ShiftUp":        "SelectUp",
 382     "ShiftDown":      "SelectDown",
 383     "ShiftLeft":      "SelectLeft",
 384     "ShiftRight":     "SelectRight",
 385     "AltLeft":        "WordLeft",
 386     "AltRight":       "WordRight",
 387     "AltUp":          "MoveLinesUp",
 388     "AltDown":        "MoveLinesDown",
 389     "AltShiftRight":  "SelectWordRight",
 390     "AltShiftLeft":   "SelectWordLeft",
 391     "CtrlLeft":       "StartOfLine",
 392     "CtrlRight":      "EndOfLine",
 393     "CtrlShiftLeft":  "SelectToStartOfLine",
 394     "ShiftHome":      "SelectToStartOfLine",
 395     "CtrlShiftRight": "SelectToEndOfLine",
 396     "ShiftEnd":       "SelectToEndOfLine",
 397     "CtrlUp":         "CursorStart",
 398     "CtrlDown":       "CursorEnd",
 399     "CtrlShiftUp":    "SelectToStart",
 400     "CtrlShiftDown":  "SelectToEnd",
 401     "Alt-{":          "ParagraphPrevious",
 402     "Alt-}":          "ParagraphNext",
 403     "Enter":          "InsertNewline",
 404     "CtrlH":          "Backspace",
 405     "Backspace":      "Backspace",
 406     "Alt-CtrlH":      "DeleteWordLeft",
 407     "Alt-Backspace":  "DeleteWordLeft",
 408     "Tab":            "IndentSelection,InsertTab",
 409     "Backtab":        "OutdentSelection,OutdentLine",
 410     "CtrlO":          "OpenFile",
 411     "CtrlS":          "Save",
 412     "CtrlF":          "Find",
 413     "CtrlN":          "FindNext",
 414     "CtrlP":          "FindPrevious",
 415     "CtrlZ":          "Undo",
 416     "CtrlY":          "Redo",
 417     "CtrlC":          "Copy",
 418     "CtrlX":          "Cut",
 419     "CtrlK":          "CutLine",
 420     "CtrlD":          "DuplicateLine",
 421     "CtrlV":          "Paste",
 422     "CtrlA":          "SelectAll",
 423     "CtrlT":          "AddTab",
 424     "Alt,":           "PreviousTab",
 425     "Alt.":           "NextTab",
 426     "Home":           "StartOfLine",
 427     "End":            "EndOfLine",
 428     "CtrlHome":       "CursorStart",
 429     "CtrlEnd":        "CursorEnd",
 430     "PageUp":         "CursorPageUp",
 431     "PageDown":       "CursorPageDown",
 432     "CtrlG":          "ToggleHelp",
 433     "CtrlR":          "ToggleRuler",
 434     "CtrlL":          "JumpLine",
 435     "Delete":         "Delete",
 436     "CtrlB":          "ShellMode",
 437     "CtrlQ":          "Quit",
 438     "CtrlE":          "CommandMode",
 439     "CtrlW":          "NextSplit",
 440     "CtrlU":          "ToggleMacro",
 441     "CtrlJ":          "PlayMacro",
 442
 443     // Emacs-style keybindings
 444     "Alt-f": "WordRight",
 445     "Alt-b": "WordLeft",
 446     "Alt-a": "StartOfLine",
 447     "Alt-e": "EndOfLine",
 448
 449     // Integration with file managers
 450     "F1":  "ToggleHelp",
 451     "F2":  "Save",
 452     "F3":  "Find",
 453     "F4":  "Quit",
 454     "F7":  "Find",
 455     "F10": "Quit",
 456     "Esc": "Escape",
 457
 458     // Mouse bindings
 459     "MouseWheelUp":   "ScrollUp",
 460     "MouseWheelDown": "ScrollDown",
 461     "MouseLeft":      "MousePress",
 462     "MouseMiddle":    "PastePrimary",
 463     "Ctrl-MouseLeft": "MouseMultiCursor",
 464
 465     // Multiple cursors bindings
 466     "Alt-n": "SpawnMultiCursor",
 467     "Alt-p": "RemoveMultiCursor",
 468     "Alt-c": "RemoveAllMultiCursors",
 469     "Alt-x": "SkipMultiCursor",
 470 }
 471 ```
 472
 473 ## Final notes
 474
 475 Note: On some old terminal emulators and on Windows machines, `CtrlH` should be
 476 used for backspace.
 477
 478 Additionally, alt keys can be bound by using `Alt-key`. For example `Alt-a` or
 479 `Alt-Up`. Micro supports an optional `-` between modifiers like `Alt` and
 480 `Ctrl` so `Alt-a` could be rewritten as `Alta` (case matters for alt bindings).
 481 This is why in the default keybindings you can see `AltShiftLeft` instead of
 482 `Alt-ShiftLeft` (they are equivalent).