runtime/help/copypaste.md

   1 Copy and paste are essential features in micro but can be
   2 confusing to get right especially when running micro over SSH
   3 because there are multiple methods. This help document will explain
   4 the various methods for copying and pasting, how they work,
   5 and the best methods for doing so over SSH.
   6
   7 # OSC 52 (terminal clipboard)
   8
   9 If possible, setting the `clipboard` option to `terminal` will give
  10 best results because it will work over SSH and locally. However, there
  11 is limited support among terminal emulators for the terminal clipboard
  12 (which uses the OSC 52 protocol to communicate clipboard contents).
  13 Here is a list of terminal emulators and their status:
  14
  15 * Kitty: supported, but only writing is enabled by default. To enable
  16   reading, add `read-primary` and `read-clipboard` to the
  17   `clipboard_control` option.
  18
  19 * iTerm2: only copying (writing to clipboard) is supported. Must be enabled in
  20   `Preferences->General-> Selection->Applications in terminal may access clipboard`.
  21   You can use Command-v to paste.
  22
  23 * `st`: supported.
  24
  25 * `rxvt-unicode`: not natively supported, but there is a Perl extension
  26    [here](http://anti.teamidiot.de/static/nei/*/Code/urxvt/).
  27
  28 * `xterm`: supported, but disabled by default. It can be enabled by putting
  29    the following in `.Xresources` or `.Xdefaults`:
  30    `XTerm*disallowedWindowOps: 20,21,SetXprop`.
  31
  32 * `gnome-terminal`: does not support OSC 52.
  33
  34 * `alacritty`: supported.
  35
  36 * `foot`: supported.
  37
  38 **Summary:** If you want copy and paste to work over SSH, then you
  39 should set `clipboard` to `terminal`, and make sure your terminal
  40 supports OSC 52.
  41
  42 # Pasting
  43
  44 ## Recommendations (TL;DR)
  45
  46 The recommended method of pasting is the following:
  47
  48 * If you are not working over SSH, use the micro keybinding (Ctrl-v
  49   by default) to perform pastes. If on Linux, install `xclip` or
  50   `xsel` beforehand.
  51
  52 * If you are working over SSH, use the terminal keybinding
  53   (Ctrl-Shift-v or Command-v) to perform pastes. If your terminal
  54   does not support bracketed paste, when performing a paste first
  55   enable the `paste` option, and when finished disable the option.
  56
  57 ## Micro paste events
  58
  59 Micro is an application that runs within the terminal. This means
  60 that the terminal sends micro events, such as key events, mouse
  61 events, resize events, and paste events. Micro's default keybinding
  62 for paste is Ctrl-v. This means that when micro receives the key
  63 event saying Ctrl-v has been pressed from the terminal, it will
  64 attempt to access the system clipboard and effect a paste. The
  65 system clipboard will be accessed through `pbpaste` on MacOS
  66 (installed by default), `xclip` or `xsel` on Linux (these
  67 applications must be installed by the user) or a system call on
  68 Windows.
  69
  70 ## Terminal paste events
  71
  72 For certain keypresses, the terminal will not send an event to
  73 micro and will instead do something itself. In this document,
  74 such keypresses will be called "terminal keybindings." Often
  75 there will be a terminal keybinding for pasting and copying. On
  76 MacOS these are Command-v and Command-c and on Linux Ctrl-Shift-v
  77 and Ctrl-Shift-c. When the terminal keybinding for paste is
  78 executed, your terminal will access the system clipboard, and send
  79 micro either a paste event or a list of key events (one key for each
  80 character in the paste), depending on whether or not your terminal
  81 supports sending paste events (called bracketed paste).
  82
  83 If your terminal supports bracketed paste, then it will send a paste
  84 event and everything will work well. However, if your terminal
  85 sends a list of key events, this can cause issues because micro
  86 will think you manually entered each character and may add closing
  87 brackets or automatic indentation, which will mess up the pasted
  88 text. To avoid this, you can temporarily enable the `paste` option
  89 while you perform the paste. When paste option is on, micro will
  90 aggregate lists of multiple key events into larger paste events.
  91 It is a good idea to disable the `paste` option during normal use
  92 as occasionally if you are typing quickly, the terminal will send
  93 the key events as lists of characters that were in fact manually
  94 entered.
  95
  96 ## Pasting over SSH
  97
  98 When working over SSH, micro is running on the remote machine and
  99 your terminal is running on your local machine. Therefore if you
 100 would like to paste, using Ctrl-v (micro's keybinding) will not
 101 work because when micro attempts to access the system clipboard,
 102 it will access the remote machine's clipboard rather than the local
 103 machine's clipboard. On the other hand, the terminal keybinding
 104 for paste will access your local clipboard and send the text over
 105 the network as a paste event, which is what you want.
 106
 107 # Copying
 108
 109 # Recommendations (TL;DR)
 110
 111 The recommended method of copying is the following:
 112
 113 * If you are not working over SSH, use the micro keybinding (Ctrl-c by
 114   default) to perform copies. If on Linux, install `xclip` or `xsel`
 115   beforehand.
 116
 117 * If you are working over SSH, use the terminal keybinding
 118   (Ctrl-Shift-c or Command-c) to perform copies. You must first disable
 119   the `mouse` option to perform a terminal selection, and you may wish
 120   to disable line numbers and diff indicators (`ruler` and `diffgutter`
 121   options) and close other splits. This method will only be able to copy
 122   characters that are displayed on the screen (you will not be able to
 123   copy more than one page's worth of characters).
 124
 125 Copying follows a similar discussion to the one above about pasting.
 126 The primary difference is before performing a copy, the application
 127 doing the copy must be told what text needs to be copied.
 128
 129 Micro has a keybinding (Ctrl-c) for copying and will access the system
 130 clipboard to perform the copy. The text that micro will copy into is
 131 the text that is currently selected in micro (usually such text is
 132 displayed with a white background). When the `mouse` option is enabled,
 133 the mouse can be used to select text, as well as other keybindings,
 134 such as ShiftLeft, etc...
 135
 136 The terminal also has a keybinding (Ctrl-Shift-c or Command-c) to perform
 137 a copy, and the text that it copies is the text selected by the terminal's
 138 selection (*not* micro's selection). To select text with the terminal
 139 selection, micro's mouse support must first be disabled by turning the
 140 `mouse` option off. The terminal, unlike micro, has no sense of different
 141 buffers/splits and what the different characters being displayed are. This
 142 means that for copying multiple lines using the terminal selection, you
 143 should first disable line numbers and diff indicators (turn off the `ruler`
 144 and `diffgutter` options), otherwise they might be part of your selection
 145 and copied.