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