GitHub/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim synced 2025-07-16 01:01:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: clipboard, eval #33223

Browse Source
This commit is contained in:
Justin M. Keyes
2025-04-05 06:01:40 -07:00
committed by GitHub
parent e8785c2e94
commit 57d99a515f
8 changed files with 144 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
runtime/doc/builtin.txt generated
View File

@ -11975,14 +11975,13 @@ windowsversion() *windowsversion()*
(`string`)
winheight({nr}) *winheight()*
The result is a Number, which is the height of window {nr}.
{nr} can be the window number or the |window-ID|.
When {nr} is zero, the height of the current window is
returned. When window {nr} doesn't exist, -1 is returned.
An existing window always has a height of zero or more.
This excludes any window toolbar line.
Gets the height of |window-ID| {nr} (zero for "current
window"), excluding any 'winbar' and 'statusline'. Returns -1
if window {nr} doesn't exist. An existing window always has
a height of zero or more.
Examples: >vim
echo "The current window has " .. winheight(0) .. " lines."
echo "Current window has " .. winheight(0) .. " lines."
<
Parameters: ~
@ -12149,18 +12148,21 @@ winsaveview() *winsaveview()*
(`vim.fn.winsaveview.ret`)
winwidth({nr}) *winwidth()*
The result is a Number, which is the width of window {nr}.
{nr} can be the window number or the |window-ID|.
When {nr} is zero, the width of the current window is
returned. When window {nr} doesn't exist, -1 is returned.
An existing window always has a width of zero or more.
Examples: >vim
echo "The current window has " .. winwidth(0) .. " columns."
Gets the width of |window-ID| {nr} (zero for "current
window"), including columns (|sign-column|, 'statuscolumn',
etc.). Returns -1 if window {nr} doesn't exist. An existing
window always has a width of zero or more.
Example: >vim
echo "Current window has " .. winwidth(0) .. " columns."
if winwidth(0) <= 50
50 wincmd |
endif
< For getting the terminal or screen size, see the 'columns'
option.
<
To get the buffer "viewport", use |getwininfo()|: >vim
:echo getwininfo(win_getid())[0].width - getwininfo(win_getid())[0].textoff
<
To get the Nvim screen size, see the 'columns' option.
Parameters: ~
• {nr} (`integer`)

4
runtime/doc/news.txt
View File

@ -135,9 +135,7 @@ OPTIONS
• 'completefuzzycollect' enables fuzzy collection of candidates for (some)
|ins-completion| modes.
• 'autowriteall' write all buffers upon receiving `SIGHUP`, `SIGQUIT` or `SIGTSTP`.
• 'winborder' add bold style.
• 'winborder' "bold" style.
• |g:clipboard| accepts a string name to force any builtin clipboard tool.
PERFORMANCE

8
runtime/doc/options.txt
View File

@ -7204,13 +7204,13 @@ A jump table for the options with a short description can be found at |Q_op|.
global
Defines the default border style of floating windows. The default value
is empty, which is equivalent to "none". Valid values include:
- "bold": Bold line box.
- "double": Double-line box.
- "none": No border.
- "single": A single line box.
- "double": A double line box.
- "rounded": Like "single", but with rounded corners ("╭" etc.).
- "shadow": Drop shadow effect, by blending with the background.
- "single": Single-line box.
- "solid": Adds padding by a single whitespace cell.
- "shadow": A drop shadow effect by blending with the background.
- "bold": A bold line box.
*'window'* *'wi'*
'window' 'wi' number (default screen height - 1)

161
runtime/doc/provider.txt
View File

@ -182,121 +182,112 @@ the "+" and/or "*" registers explicitly): >vim
See 'clipboard' for details and options.
*clipboard-tool*
The presence of a working clipboard tool implicitly enables the '+' and "*"
registers. Nvim looks for these clipboard tools, in order of priority:
The presence of a working clipboard tool implicitly enables the "+" and "*"
registers. Nvim supports these clipboard tools, in order of priority:
- |g:clipboard| (unless unset or `false`)
- pbcopy, pbpaste (macOS)
- wl-copy, wl-paste (if $WAYLAND_DISPLAY is set)
- waycopy, waypaste (if $WAYLAND_DISPLAY is set)
- xsel (if $DISPLAY is set)
- xclip (if $DISPLAY is set)
- lemonade (for SSH) https://github.com/pocke/lemonade
- doitclient (for SSH) https://www.chiark.greenend.org.uk/~sgtatham/doit/
- *win32yank* (Windows)
- putclip, getclip (Windows) https://cygwin.com/packages/summary/cygutils.html
- clip, powershell (Windows) https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/clip
- termux (via termux-clipboard-set, termux-clipboard-set)
- tmux (if $TMUX is set)
- |g:clipboard| : User override (if set to a dict or any string "name" below;
e.g. `g:clipboard="tmux"` forces tmux clipboard and skips auto-detection).
- "pbcopy" : pbcopy, pbpaste (macOS)
- "wl-copy" : wl-copy, wl-paste (if $WAYLAND_DISPLAY is set)
- "wayclip" : waycopy, waypaste (if $WAYLAND_DISPLAY is set)
- "xsel" : xsel (if $DISPLAY is set)
- "xclip" : xclip (if $DISPLAY is set)
- "lemonade" : lemonade (for SSH) https://github.com/pocke/lemonade
- "doitclient": doitclient (for SSH) https://www.chiark.greenend.org.uk/~sgtatham/doit/
- "win32yank" : *win32yank* (Windows)
- "putclip" : putclip, getclip (Windows) https://cygwin.com/packages/summary/cygutils.html
- "clip" : clip, powershell (Windows) https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/clip
- "termux" : termux (via termux-clipboard-set, termux-clipboard-set)
- "tmux" : tmux (if $TMUX is set)
- "osc52" : |clipboard-osc52| (if supported by your terminal)
*g:clipboard*
To configure a custom clipboard tool, set g:clipboard to a dictionary.
For example this configuration integrates the tmux clipboard: >vim
let g:clipboard = {
\ 'name': 'myClipboard',
\ 'copy': {
\ '+': ['tmux', 'load-buffer', '-'],
\ '*': ['tmux', 'load-buffer', '-'],
\ },
\ 'paste': {
\ '+': ['tmux', 'save-buffer', '-'],
\ '*': ['tmux', 'save-buffer', '-'],
\ },
\ 'cache_enabled': 1,
\ }
To configure a custom clipboard tool, set `g:clipboard` to a string name (from
the above |clipboard-tool| list), or dict (to explicitly specify the shell
commands or |lambda| functions).
If "cache_enabled" is |TRUE| then when a selection is copied Nvim will cache
the selection until the copy command process dies. When pasting, if the copy
process has not died the cached selection is applied.
g:clipboard can also use functions (see |lambda|) instead of strings.
For example this configuration uses the g:foo variable as a fake clipboard:
>vim
let g:clipboard = {
\ 'name': 'myClipboard',
\ 'copy': {
\ '+': {lines, regtype -> extend(g:, {'foo': [lines, regtype]}) },
\ '*': {lines, regtype -> extend(g:, {'foo': [lines, regtype]}) },
\ },
\ 'paste': {
\ '+': {-> get(g:, 'foo', [])},
\ '*': {-> get(g:, 'foo', [])},
\ },
\ }
The "copy" function stores a list of lines and the register type. The "paste"
function returns the clipboard as a `[lines, regtype]` list, where `lines` is
a list of lines and `regtype` is a register type conforming to |setreg()|.
Nvim also supports setting g:clipboard to a string to use a builtin clipboard provider:
Example: set to "osc52" to force OSC52, skipping auto-detection of terminal
support: >vim
- "tmux" - Use tmux clipboard
- "xclip" - Use xclip for X11 clipboard
- "xsel" - Use xsel for X11 clipboard
- "wl-copy" - Use Wayland clipboard with wl-copy/wl-paste
- "wayclip" - Use Wayland clipboard with waycopy/waypaste
- "lemonade" - Use lemonade clipboard (for SSH)
- "doitclient" - Use doitclient clipboard (for SSH)
- "win32yank" - Use win32yank clipboard (for Windows)
- "clip" - Use clip/powershell clipboard (for Windows)
- "putclip" - Use putclip/getclip clipboard (for Windows/Cygwin)
- "termux" - Use Termux clipboard
- "pbcopy" - Use macOS clipboard
- "osc52" - Use OSC 52 sequence
let g:clipboard = 'osc52'
Example: >vim
let g:clipboard = 'tmux'
Example: set to "wayclip" to force waycopy/waypaste: >vim
This is equivalent to using the full dictionary configuration for tmux shown above.
let g:clipboard = 'wayclip'
Example: set to a dict which integrates the tmux clipboard: >vim
let g:clipboard = {
\ 'name': 'myClipboard',
\ 'copy': {
\ '+': ['tmux', 'load-buffer', '-'],
\ '*': ['tmux', 'load-buffer', '-'],
\ },
\ 'paste': {
\ '+': ['tmux', 'save-buffer', '-'],
\ '*': ['tmux', 'save-buffer', '-'],
\ },
\ 'cache_enabled': 1,
\ }
Example: set to a dict which uses g:foo as a fake clipboard: >vim
let g:clipboard = {
\ 'name': 'myClipboard',
\ 'copy': {
\ '+': {lines, regtype -> extend(g:, {'foo': [lines, regtype]}) },
\ '*': {lines, regtype -> extend(g:, {'foo': [lines, regtype]}) },
\ },
\ 'paste': {
\ '+': {-> get(g:, 'foo', [])},
\ '*': {-> get(g:, 'foo', [])},
\ },
\ }
<
*clipboard-wsl*
For Windows WSL, try this g:clipboard definition:
>vim
let g:clipboard = {
\ 'name': 'WslClipboard',
\ 'copy': {
\ '+': 'clip.exe',
\ '*': 'clip.exe',
\ },
\ 'paste': {
\ '+': 'powershell.exe -NoLogo -NoProfile -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
\ '*': 'powershell.exe -NoLogo -NoProfile -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
\ },
\ 'cache_enabled': 0,
\ }
\ 'name': 'WslClipboard',
\ 'copy': {
\ '+': 'clip.exe',
\ '*': 'clip.exe',
\ },
\ 'paste': {
\ '+': 'powershell.exe -NoLogo -NoProfile -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
\ '*': 'powershell.exe -NoLogo -NoProfile -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
\ },
\ 'cache_enabled': 0,
\ }
<
*clipboard-osc52*
Nvim bundles a clipboard provider that allows copying to the system clipboard
using OSC 52. OSC 52 is an Operating System Command control sequence that
causes the terminal emulator to write to or read from the system clipboard.
using OSC 52, an "Operating System Command" control-sequence that causes the
terminal emulator to write to or read from the system clipboard.
When Nvim is running in the |TUI|, it will automatically attempt to determine if
the host terminal emulator supports OSC 52. If it does, then Nvim will use OSC
52 for copying and pasting if no other |clipboard-tool| is found and when
'clipboard' is unset. NOTE: Using a terminal multiplexer (e.g. tmux) may
inhibit automatic OSC 52 support detection.
When Nvim is running in the |TUI|, it automatically detects host terminal
support for OSC 52. If successful, then Nvim will use OSC 52 for copying and
pasting if no other |clipboard-tool| is found and when 'clipboard' is unset.
NOTE: Using a terminal multiplexer (e.g. tmux) may inhibit automatic OSC 52
support detection.
*g:termfeatures*
To disable the automatic detection, set the "osc52" key of |g:termfeatures| to
|v:false| in the |config| file. Example: >lua
false early in your |config|. Example: >lua
local termfeatures = vim.g.termfeatures or {}
termfeatures.osc52 = false
vim.g.termfeatures = termfeatures
<
To force Nvim to always use the OSC 52 provider you can use the following
|g:clipboard| definition: >lua
To force Nvim to use the OSC 52 provider you can set |g:clipboard|: >lua
vim.g.clipboard = 'osc52'
@ -313,7 +304,7 @@ Which is equivalent to: >lua
},
}
<
Note that not all terminal emulators support reading from the system clipboard
Note: not all terminal emulators support reading from the system clipboard
(and even for those that do, users should be aware of the security
implications), so using OSC 52 for pasting may not be possible (and not
necessary, because you can |paste| instead using your system paste function).

8
runtime/lua/vim/_meta/options.lua generated
View File

@ -7889,13 +7889,13 @@ vim.wo.winbl = vim.wo.winblend
--- Defines the default border style of floating windows. The default value
--- is empty, which is equivalent to "none". Valid values include:
--- - "bold": Bold line box.
--- - "double": Double-line box.
--- - "none": No border.
--- - "single": A single line box.
--- - "double": A double line box.
--- - "rounded": Like "single", but with rounded corners ("╭" etc.).
--- - "shadow": Drop shadow effect, by blending with the background.
--- - "single": Single-line box.
--- - "solid": Adds padding by a single whitespace cell.
--- - "shadow": A drop shadow effect by blending with the background.
--- - "bold": A bold line box.
---
--- @type ''|'double'|'single'|'shadow'|'rounded'|'solid'|'bold'|'none'
vim.o.winborder = ""

34
runtime/lua/vim/_meta/vimfn.lua generated
View File

@ -10881,14 +10881,13 @@ function vim.fn.wincol() end
--- @return string
function vim.fn.windowsversion() end
--- The result is a Number, which is the height of window {nr}.
--- {nr} can be the window number or the |window-ID|.
--- When {nr} is zero, the height of the current window is
--- returned. When window {nr} doesn't exist, -1 is returned.
--- An existing window always has a height of zero or more.
--- This excludes any window toolbar line.
--- Gets the height of |window-ID| {nr} (zero for "current
--- window"), excluding any 'winbar' and 'statusline'. Returns -1
--- if window {nr} doesn't exist. An existing window always has
--- a height of zero or more.
---
--- Examples: >vim
--- echo "The current window has " .. winheight(0) .. " lines."
--- echo "Current window has " .. winheight(0) .. " lines."
--- <
---
--- @param nr integer
@ -11040,18 +11039,21 @@ function vim.fn.winrestview(dict) end
--- @return vim.fn.winsaveview.ret
function vim.fn.winsaveview() end
--- The result is a Number, which is the width of window {nr}.
--- {nr} can be the window number or the |window-ID|.
--- When {nr} is zero, the width of the current window is
--- returned. When window {nr} doesn't exist, -1 is returned.
--- An existing window always has a width of zero or more.
--- Examples: >vim
--- echo "The current window has " .. winwidth(0) .. " columns."
--- Gets the width of |window-ID| {nr} (zero for "current
--- window"), including columns (|sign-column|, 'statuscolumn',
--- etc.). Returns -1 if window {nr} doesn't exist. An existing
--- window always has a width of zero or more.
---
--- Example: >vim
--- echo "Current window has " .. winwidth(0) .. " columns."
--- if winwidth(0) <= 50
--- 50 wincmd |
--- endif
--- <For getting the terminal or screen size, see the 'columns'
--- option.
--- <
--- To get the buffer "viewport", use |getwininfo()|: >vim
--- :echo getwininfo(win_getid())[0].width - getwininfo(win_getid())[0].textoff
--- <
--- To get the Nvim screen size, see the 'columns' option.
---
--- @param nr integer
--- @return integer

38
src/nvim/eval.lua
View File

@ -13185,16 +13185,14 @@ M.funcs = {
args = 1,
base = 1,
desc = [=[
The result is a Number, which is the height of window {nr}.
{nr} can be the window number or the |window-ID|.
When {nr} is zero, the height of the current window is
returned. When window {nr} doesn't exist, -1 is returned.
An existing window always has a height of zero or more.
This excludes any window toolbar line.
Examples: >vim
echo "The current window has " .. winheight(0) .. " lines."
<
Gets the height of |window-ID| {nr} (zero for "current
window"), excluding any 'winbar' and 'statusline'. Returns -1
if window {nr} doesn't exist. An existing window always has
a height of zero or more.
Examples: >vim
echo "Current window has " .. winheight(0) .. " lines."
<
]=],
name = 'winheight',
params = { { 'nr', 'integer' } },
@ -13377,19 +13375,21 @@ M.funcs = {
args = 1,
base = 1,
desc = [=[
The result is a Number, which is the width of window {nr}.
{nr} can be the window number or the |window-ID|.
When {nr} is zero, the width of the current window is
returned. When window {nr} doesn't exist, -1 is returned.
An existing window always has a width of zero or more.
Examples: >vim
echo "The current window has " .. winwidth(0) .. " columns."
Gets the width of |window-ID| {nr} (zero for "current
window"), including columns (|sign-column|, 'statuscolumn',
etc.). Returns -1 if window {nr} doesn't exist. An existing
window always has a width of zero or more.
Example: >vim
echo "Current window has " .. winwidth(0) .. " columns."
if winwidth(0) <= 50
50 wincmd |
endif
<For getting the terminal or screen size, see the 'columns'
option.
<
To get the buffer "viewport", use |getwininfo()|: >vim
:echo getwininfo(win_getid())[0].width - getwininfo(win_getid())[0].textoff
<
To get the Nvim screen size, see the 'columns' option.
]=],
name = 'winwidth',
params = { { 'nr', 'integer' } },

8
src/nvim/options.lua
View File

@ -10263,13 +10263,13 @@ local options = {
desc = [=[
Defines the default border style of floating windows. The default value
is empty, which is equivalent to "none". Valid values include:
- "bold": Bold line box.
- "double": Double-line box.
- "none": No border.
- "single": A single line box.
- "double": A double line box.
- "rounded": Like "single", but with rounded corners ("╭" etc.).
- "shadow": Drop shadow effect, by blending with the background.
- "single": Single-line box.
- "solid": Adds padding by a single whitespace cell.
- "shadow": A drop shadow effect by blending with the background.
- "bold": A bold line box.
]=],
full_name = 'winborder',
scope = { 'global' },