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