Skip to content

Commit

Permalink
docs: update readme and docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@ojroques
ojroques committed Nov 3, 2024
1 parent c37c9d9 commit dc23464
Show file tree
Hide file tree
Showing 2 changed files with 56 additions and 50 deletions.
98 changes: 52 additions & 46 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,52 +1,29 @@
# vim-oscyank

A Vim plugin to copy text to the system clipboard using the [ANSI
OSC52](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands)
A Vim plugin to copy text to the system clipboard using the
[ANSI OSC52](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands)
sequence.

The plugin wraps a piece of text inside an OSC52 sequence and writes it to Vim's
stderr. When your terminal detects the OSC52 sequence, it will copy the text
into the system clipboard.
The plugin wraps a piece of text inside an OSC52 sequence and writes it to Vim's stderr. When your
terminal detects the OSC52 sequence, it will copy the text into the system clipboard.

This is totally location-independent, you can copy text from anywhere including
from remote SSH sessions. The only requirement is that the terminal must support
the sequence. Here is a non-exhaustive list of the state of OSC52 integration in
popular terminal emulators:

| Terminal | OSC52 support |
|----------|:-------------:|
| [alacritty](https://github.com/alacritty/alacritty) | **yes** |
| [contour](https://github.com/contour-terminal/contour) | **yes** |
| [far2l](https://github.com/elfmz/far2l) | **yes** |
| [foot](https://codeberg.org/dnkl/foot) | **yes** |
| [gnome terminal](https://github.com/GNOME/gnome-terminal) (and other VTE-based terminals) | [not yet](https://gitlab.gnome.org/GNOME/vte/-/issues/2495) |
| [hterm](https://chromium.googlesource.com/apps/libapps/+/master/README.md) | [**yes**](https://chromium.googlesource.com/apps/libapps/+/master/nassh/doc/FAQ.md#Is-OSC-52-aka-clipboard-operations_supported) |
| [iterm2](https://iterm2.com/) | **yes** |
| [kitty](https://github.com/kovidgoyal/kitty) | **yes** |
| [konsole](https://konsole.kde.org/) | [not yet](https://bugs.kde.org/show_bug.cgi?id=372116) |
| [qterminal](https://github.com/lxqt/qterminal#readme) | [not yet](https://github.com/lxqt/qterminal/issues/839)
| [rxvt](http://rxvt.sourceforge.net/) | **yes** |
| [st](https://st.suckless.org/) | **yes** (but needs to be enabled, see [here](https://git.suckless.org/st/commit/a2a704492b9f4d2408d180f7aeeacf4c789a1d67.html)) |
| [terminal.app](https://en.wikipedia.org/wiki/Terminal_(macOS)) | no, but see [workaround](https://github.com/roy2220/osc52pty) |
| [tmux](https://github.com/tmux/tmux) | **yes** |
| [urxvt](http://software.schmorp.de/pkg/rxvt-unicode.html) | **yes** (with a script, see [here](https://github.com/ojroques/vim-oscyank/issues/4)) |
| [wezterm](https://github.com/wez/wezterm) | [**yes**](https://wezfurlong.org/wezterm/escape-sequences.html#operating-system-command-sequences) |
| [windows terminal](https://github.com/microsoft/terminal) | **yes** |
| [xterm.js](https://xtermjs.org/) (Hyper terminal) | [not yet](https://github.com/xtermjs/xterm.js/issues/3260) |
| [zellij](https://github.com/zellij-org/zellij/) | **yes** |

Feel free to add terminals to this list by submitting a pull request.
This is totally location-independent, you can copy text from anywhere including from remote SSH
sessions. The only requirement is that the terminal must support the sequence. You can find at the
end a non-exhaustive list of the state of OSC52 integration in popular terminal emulators.

## Installation
With [vim-plug](https://github.com/junegunn/vim-plug) for instance:
```vim
Plug 'ojroques/vim-oscyank', {'branch': 'main'}
```

**If you are using tmux**, run these steps first: [enabling OSC52 in
tmux](https://github.com/tmux/tmux/wiki/Clipboard#quick-summary). Then make sure
`set-clipboard` is set to `on`: `set -s set-clipboard on`. See `:h oscyank-tmux`
for more details.
**If you are using Tmux**, run these steps first:
[Enabling OSC52 in Tmux](https://github.com/tmux/tmux/wiki/Clipboard#quick-summary). Then make sure
`set-clipboard` is set to `on` in your Tmux config:
```
set -s set-clipboard on
````
See `:h oscyank-tmux` for more details.
## Usage
Add this to your Vim config:
Expand All @@ -56,15 +33,15 @@ nmap <leader>cc <leader>c_
vmap <leader>c <Plug>OSCYankVisual
```

Using these mappings:
* In normal mode, <kbd>\<leader\>c</kbd> is an operator that will copy the given
text to the clipboard.
With these mappings:
* In normal mode, <kbd>\<leader\>c</kbd> is an operator that will copy the given text to the
clipboard.
* In normal mode, <kbd>\<leader\>cc</kbd> will copy the current line.
* In visual mode, <kbd>\<leader\>c</kbd> will copy the current selection.

For Neovim, this plugin shouldn't be necessary anymore, since [Neovim contains native OSC 52 support since Neovim 10.0](https://github.com/neovim/neovim/pull/25872).
For older versions of Neovim, this plugin also works. However, you should instead check out [nvim-osc52](https://github.com/ojroques/nvim-osc52). Or
add this to your Neovim config:
Neovim 0.10+ natively supports OSC52 since [this PR](https://github.com/neovim/neovim/pull/25872)
was merged. See `:h clipboard-osc52` in Neovim. If you still wish to use this plugin, add this to
your Neovim config:
```lua
vim.keymap.set('n', '<leader>c', '<Plug>OSCYankOperator')
vim.keymap.set('n', '<leader>cc', '<leader>c_', {remap = true})
Expand All @@ -74,7 +51,7 @@ vim.keymap.set('v', '<leader>c', '<Plug>OSCYankVisual')
## Configuration
The available options with their default values are:
```vim
let g:oscyank_max_length = 0 " maximum length of a selection
let g:oscyank_max_length = 0 " maximum length of a selection, 0 for unlimited length
let g:oscyank_silent = 0 " disable message on successful copy
let g:oscyank_trim = 0 " trim surrounding whitespaces before copy
let g:oscyank_osc52 = "\x1b]52;c;%s\x07" " the OSC52 format string to use
Expand All @@ -87,8 +64,8 @@ The following commands are also available:
* `:OSCYank(text)`: copy text `text`
* `:OSCYankRegister(register)`: copy text from register `register`

For instance, to automatically copy text that was yanked into the unnamed register (`"`)
as well as `+` and `"` when the clipboard isn't working:
For instance, to automatically copy text that was yanked into the unnamed register (`"`) as well as
`+` and `"` when the clipboard isn't working:

```vim
if (!has('nvim') && !has('clipboard_working'))
Expand All @@ -109,3 +86,32 @@ if (!has('nvim') && !has('clipboard_working'))
augroup END
endif
```

## Terminal Support
| Terminal | OSC52 support |
|----------|:-------------:|
| [alacritty](https://github.com/alacritty/alacritty) | **yes** |
| [contour](https://github.com/contour-terminal/contour) | **yes** |
| [far2l](https://github.com/elfmz/far2l) | **yes** |
| [foot](https://codeberg.org/dnkl/foot) | **yes** |
| [gnome terminal](https://github.com/GNOME/gnome-terminal) (and other VTE-based terminals) | [not yet](https://gitlab.gnome.org/GNOME/vte/-/issues/2495) |
| [hterm](https://chromium.googlesource.com/apps/libapps/+/master/README.md) | [**yes**](https://chromium.googlesource.com/apps/libapps/+/master/nassh/doc/FAQ.md#Is-OSC-52-aka-clipboard-operations_supported) |
| [iterm2](https://iterm2.com/) | **yes** |
| [kitty](https://github.com/kovidgoyal/kitty) | **yes** |
| [konsole](https://konsole.kde.org/) | [not yet](https://bugs.kde.org/show_bug.cgi?id=372116) |
| [qterminal](https://github.com/lxqt/qterminal#readme) | [not yet](https://github.com/lxqt/qterminal/issues/839)
| [rxvt](http://rxvt.sourceforge.net/) | **yes** |
| [st](https://st.suckless.org/) | **yes** (but needs to be enabled, see [here](https://git.suckless.org/st/commit/a2a704492b9f4d2408d180f7aeeacf4c789a1d67.html)) |
| [terminal.app](https://en.wikipedia.org/wiki/Terminal_(macOS)) | no, but see [workaround](https://github.com/roy2220/osc52pty) |
| [tmux](https://github.com/tmux/tmux) | **yes** |
| [urxvt](http://software.schmorp.de/pkg/rxvt-unicode.html) | **yes** (with a script, see [here](https://github.com/ojroques/vim-oscyank/issues/4)) |
| [wezterm](https://github.com/wez/wezterm) | [**yes**](https://wezfurlong.org/wezterm/escape-sequences.html#operating-system-command-sequences) |
| [windows terminal](https://github.com/microsoft/terminal) | **yes** |
| [xterm.js](https://xtermjs.org/) (Hyper terminal) | [not yet](https://github.com/xtermjs/xterm.js/issues/3260) |
| [zellij](https://github.com/zellij-org/zellij/) | **yes** |

Feel free to add terminals to this list by submitting a pull request.

You can also check
[can-i-use-terminal.github.io](https://can-i-use-terminal.github.io/features/osc52copy.html) to see
if your terminal supports OSC52.
8 changes: 4 additions & 4 deletions doc/oscyank.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ License: BSD 2-Clause
==============================================================================
INTRODUCTION *oscyank-introduction*

A Vim / Neovim plugin to copy text to the system clipboard using the ANSI
OSC52 sequence.
A Vim plugin to copy text to the system clipboard using the ANSI OSC52
sequence.

The plugin wraps a piece of text inside an OSC52 sequence and writes it to
Vim's stderr. If the terminal supports OSC52, it will then copy the text into
Expand All @@ -25,8 +25,8 @@ Add these mappings to your Vim config:
vmap <leader>c <Plug>OSCYankVisual
<
With these mappings:
- In normal mode, <leader>c is an operator that will copy the given
text to the system clipboard.
- In normal mode, <leader>c is an operator that will copy the given text to
the system clipboard.
- In normal mode, <leader>cc will copy the current line.
- In visual mode, <leader>c will copy the current selection.

Expand Down

0 comments on commit dc23464

Please sign in to comment.