micro/runtime/help/copypaste.md

Copy and paste are essential features in micro but can be confusing to get right especially when running micro over SSH because there are multiple methods. This help document will explain the various methods for copying and pasting, how they work, and the best methods for doing so over SSH.

OSC 52 (terminal clipboard)

If possible, setting the clipboard option to terminal will give best results because it will work over SSH and locally. However, there is limited support among terminal emulators for the terminal clipboard (which uses the OSC 52 protocol to communicate clipboard contents). Here is a list of terminal emulators and their status:

• Kitty: supported, but only writing is enabled by default. To enable reading, add read-primary and read-clipboard to the clipboard_control option.

• iTerm2: only copying (writing to clipboard) is supported. Must be enabled in Preferences->General-> Selection->Applications in terminal may access clipboard. You can use Command-v to paste.

• st: supported.

• rxvt-unicode: not natively supported, but there is a Perl extension here.

• xterm: supported, but disabled by default. It can be enabled by putting the following in .Xresources or .Xdefaults: XTerm*disallowedWindowOps: 20,21,SetXprop.

• gnome-terminal: does not support OSC 52.

• alacritty: supported. Since 0.13.0, reading has been disabled by default. To reenable it, set the terminal.osc52 option to CopyPaste.

• foot: supported.

• wezterm: only copying (writing to clipboard) is supported.

Summary: If you want copy and paste to work over SSH, then you should set clipboard to terminal, and make sure your terminal supports OSC 52.

Pasting

Recommendations (TL;DR)

The recommended method of pasting is the following:

• If you are not working over SSH, use the micro keybinding (Ctrl-v by default) to perform pastes. If on Linux, install xclip or xsel beforehand.

• If you are working over SSH, use the terminal keybinding (Ctrl-Shift-v or Command-v) to perform pastes. If your terminal does not support bracketed paste, when performing a paste first enable the paste option, and when finished disable the option.

Micro paste events

Micro is an application that runs within the terminal. This means that the terminal sends micro events, such as key events, mouse events, resize events, and paste events. Micro's default keybinding for paste is Ctrl-v. This means that when micro receives the key event saying Ctrl-v has been pressed from the terminal, it will attempt to access the system clipboard and effect a paste. The system clipboard will be accessed through pbpaste on MacOS (installed by default), xclip or xsel on Linux (these applications must be installed by the user) or a system call on Windows.

Terminal paste events

For certain keypresses, the terminal will not send an event to micro and will instead do something itself. In this document, such keypresses will be called "terminal keybindings." Often there will be a terminal keybinding for pasting and copying. On MacOS these are Command-v and Command-c and on Linux Ctrl-Shift-v and Ctrl-Shift-c. When the terminal keybinding for paste is executed, your terminal will access the system clipboard, and send micro either a paste event or a list of key events (one key for each character in the paste), depending on whether or not your terminal supports sending paste events (called bracketed paste).

If your terminal supports bracketed paste, then it will send a paste event and everything will work well. However, if your terminal sends a list of key events, this can cause issues because micro will think you manually entered each character and may add closing brackets or automatic indentation, which will mess up the pasted text. To avoid this, you can temporarily enable the paste option while you perform the paste. When paste option is on, micro will aggregate lists of multiple key events into larger paste events. It is a good idea to disable the paste option during normal use as occasionally if you are typing quickly, the terminal will send the key events as lists of characters that were in fact manually entered.

Pasting over SSH

When working over SSH, micro is running on the remote machine and your terminal is running on your local machine. Therefore if you would like to paste, using Ctrl-v (micro's keybinding) will not work because when micro attempts to access the system clipboard, it will access the remote machine's clipboard rather than the local machine's clipboard. On the other hand, the terminal keybinding for paste will access your local clipboard and send the text over the network as a paste event, which is what you want.

Copying

Recommendations (TL;DR)

The recommended method of copying is the following:

• If you are not working over SSH, use the micro keybinding (Ctrl-c by default) to perform copies. If on Linux, install xclip or xsel beforehand.

• If you are working over SSH, use the terminal keybinding (Ctrl-Shift-c or Command-c) to perform copies. You must first disable the mouse option to perform a terminal selection, and you may wish to disable line numbers and diff indicators (ruler and diffgutter options) and close other splits. This method will only be able to copy characters that are displayed on the screen (you will not be able to copy more than one page's worth of characters).

Copying follows a similar discussion to the one above about pasting. The primary difference is before performing a copy, the application doing the copy must be told what text needs to be copied.

Micro has a keybinding (Ctrl-c) for copying and will access the system clipboard to perform the copy. The text that micro will copy into is the text that is currently selected in micro (usually such text is displayed with a white background). When the mouse option is enabled, the mouse can be used to select text, as well as other keybindings, such as ShiftLeft, etc...

The terminal also has a keybinding (Ctrl-Shift-c or Command-c) to perform a copy, and the text that it copies is the text selected by the terminal's selection (not micro's selection). To select text with the terminal selection, micro's mouse support must first be disabled by turning the mouse option off. The terminal, unlike micro, has no sense of different buffers/splits and what the different characters being displayed are. This means that for copying multiple lines using the terminal selection, you should first disable line numbers and diff indicators (turn off the ruler and diffgutter options), otherwise they might be part of your selection and copied.