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