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