1Copy and paste are essential features in micro but can be 2confusing to get right especially when running micro over SSH 3because there are multiple methods. This help document will explain 4the various methods for copying and pasting, how they work, 5and the best methods for doing so over SSH. 6 7# OSC 52 (terminal clipboard) 8 9If possible, setting the `clipboard` option to `terminal` will give 10best results because it will work over SSH and locally. However, there 11is limited support among terminal emulators for the terminal clipboard 12(which uses the OSC 52 protocol to communicate clipboard contents). 13Here 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 39should set `clipboard` to `terminal`, and make sure your terminal 40supports OSC 52. 41 42# Pasting 43 44## Recommendations (TL;DR) 45 46The 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 59Micro is an application that runs within the terminal. This means 60that the terminal sends micro events, such as key events, mouse 61events, resize events, and paste events. Micro's default keybinding 62for paste is Ctrl-v. This means that when micro receives the key 63event saying Ctrl-v has been pressed from the terminal, it will 64attempt to access the system clipboard and effect a paste. The 65system clipboard will be accessed through `pbpaste` on MacOS 66(installed by default), `xclip` or `xsel` on Linux (these 67applications must be installed by the user) or a system call on 68Windows. 69 70## Terminal paste events 71 72For certain keypresses, the terminal will not send an event to 73micro and will instead do something itself. In this document, 74such keypresses will be called "terminal keybindings." Often 75there will be a terminal keybinding for pasting and copying. On 76MacOS these are Command-v and Command-c and on Linux Ctrl-Shift-v 77and Ctrl-Shift-c. When the terminal keybinding for paste is 78executed, your terminal will access the system clipboard, and send 79micro either a paste event or a list of key events (one key for each 80character in the paste), depending on whether or not your terminal 81supports sending paste events (called bracketed paste). 82 83If your terminal supports bracketed paste, then it will send a paste 84event and everything will work well. However, if your terminal 85sends a list of key events, this can cause issues because micro 86will think you manually entered each character and may add closing 87brackets or automatic indentation, which will mess up the pasted 88text. To avoid this, you can temporarily enable the `paste` option 89while you perform the paste. When paste option is on, micro will 90aggregate lists of multiple key events into larger paste events. 91It is a good idea to disable the `paste` option during normal use 92as occasionally if you are typing quickly, the terminal will send 93the key events as lists of characters that were in fact manually 94entered. 95 96## Pasting over SSH 97 98When working over SSH, micro is running on the remote machine and 99your terminal is running on your local machine. Therefore if you 100would like to paste, using Ctrl-v (micro's keybinding) will not 101work because when micro attempts to access the system clipboard, 102it will access the remote machine's clipboard rather than the local 103machine's clipboard. On the other hand, the terminal keybinding 104for paste will access your local clipboard and send the text over 105the network as a paste event, which is what you want. 106 107# Copying 108 109# Recommendations (TL;DR) 110 111The 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 125Copying follows a similar discussion to the one above about pasting. 126The primary difference is before performing a copy, the application 127doing the copy must be told what text needs to be copied. 128 129Micro has a keybinding (Ctrl-c) for copying and will access the system 130clipboard to perform the copy. The text that micro will copy into is 131the text that is currently selected in micro (usually such text is 132displayed with a white background). When the `mouse` option is enabled, 133the mouse can be used to select text, as well as other keybindings, 134such as ShiftLeft, etc... 135 136The terminal also has a keybinding (Ctrl-Shift-c or Command-c) to perform 137a copy, and the text that it copies is the text selected by the terminal's 138selection (*not* micro's selection). To select text with the terminal 139selection, micro's mouse support must first be disabled by turning the 140`mouse` option off. The terminal, unlike micro, has no sense of different 141buffers/splits and what the different characters being displayed are. This 142means that for copying multiple lines using the terminal selection, you 143should first disable line numbers and diff indicators (turn off the `ruler` 144and `diffgutter` options), otherwise they might be part of your selection 145and copied. 146