zsh-system-clipboard

Zsh plugin that adds key bindings support for ZLE (Zsh Line Editor) clipboard operations for vi emulation keymaps. It works under Linux, macOS and Android (via Termux).

By default, ZLE has its own clipboard buffer. So, using keys like y inside ZLE's normal mode for yanking operations will not send that yanked text to system clipboard. It will live inside ZLE and using C-v won't paste that text in another program. This plugin synchronizes your system clipboard with ZLE buffers while it's not overriding anything. You can still use ZLE's " register if you want to.

It also supports synchronizing to tmux' (or tmate's) clipboard instead of the system's clipboard . See Options section for more details.

Installation

Using Plugin Managers

Use your favorite plugin manager, e.g. zplug:

zplug "kutsan/zsh-system-clipboard"

Manually

Clone this repository somewhere,

git clone https://github.com/kutsan/zsh-system-clipboard ${ZSH_CUSTOM:-~/.zsh}/plugins/zsh-system-clipboard

Source the zsh-system-clipboard.zsh file in your ~/.zshrc.

source "${ZSH_CUSTOM:-~/.zsh}/plugins/zsh-system-clipboard/zsh-system-clipboard.zsh"

The script zsh-system-clipboard.zsh parses the output of bindkey -M vicmd, bindkey -M emacs, bindkey -M visual in order to rebind your keys (along with the default ones) the ZLE widgets functions that copy from and paste to the system clipboard. This means that you should put all of your bindings before sourcing zsh-system-clipboard.zsh in your ~/.zshrc.

Note: widget functions that replace builtin functions for the emacs keymap are not yet written (see #12).

Options

ZSH_SYSTEM_CLIPBOARD_METHOD

Sets the clipboard method to either of these options:

method value	meaning
tmux/tmate	Use Tmux/Tmate's buffer as a clipboard - useful on systems without X / wayland
xsc	Use xsel with 'CLIPBOARD' selection.
xsp	Use xsel with 'PRIMARY' selection.
xcc	Use xclip with 'CLIPBOARD' selection.
xcp	Use xclip with 'PRIMARY' selection.
wlc	Use wl-clipboard with 'CLIPBOARD' selection.
wlp	Use wl-clipboard with 'PRIMARY' selection.
pb	Use pbcopy and pbpaste on Darwin - method used by default on OSx.
termux	Use Termux:API - method used by default on Android's termux

If you'd like to change the current clipboard method without restarting your shell - you can run this command:

# Needed only for the first time of course. If you don't set XDG_CONFIG_HOME,
# use simply ~/.config .
mkdir -p ${XDG_CONFIG_HOME:-$HOME/.config}/zsh-system-clipboard
# Here _method_ is any method explained above in the first column.
echo _method_ > ${XDG_CONFIG_HOME:-$HOME/.config}/zsh-system-clipboard/method

Here's an example use-case: You use Tmux inside a Windows Subsystem for Linux (WSL), and you access that Tmux session remotely, also when the Windows host is locked after you left the station. You may experience after it is locked that clip.exe is being denied access to the system clipboard. However, you still want to be able to copy and paste from Tmux's buffers to & from your editor seamlessly with the + / * buffers. You can do that by:

echo tmux > ${XDG_CONFIG_HOME:-$HOME/.config}/zsh-system-clipboard/method

And then in Neovim, even in already open sessions you can run:

let g:clipboard = 'tmux'

Particularly in this example, with Neovim, this will continue to copy your Neovim selections to the Wayland clipboard, if it is available.

ZSH_SYSTEM_CLIPBOARD_DISABLE_DEFAULT_MAPS

If set to a non-empty value, it disables the default bindings zsh-system-clipboard uses. Why would you want to do that?

zsh-system-clipboard modifies your key bindings by reading them in their current state and binds them to their corresponding widgets we implemented which change the system clipboard along the way. This variable enables you to bind the default bindings your way. This is useful if you wish e.g to use the same default bindings but with a certain prefix.

This is the function that's inside zsh-system-clipboard.zsh which actually binds the default keys:

function () {
  local binded_keys i parts key cmd keymap
  for keymap in vicmd visual emacs; do
    binded_keys=(${(f)"$(bindkey -M $keymap)"})
    for (( i = 1; i < ${#binded_keys[@]}; ++i )); do
      parts=("${(z)binded_keys[$i]}")
      key="${parts[1]}"
      cmd="${parts[2]}"
      if (( $+functions[zsh-system-clipboard-$keymap-$cmd] )); then
        eval bindkey -M $keymap $key zsh-system-clipboard-$keymap-$cmd
      fi
    done
  done
}

You can change the line eval bindkey -M $keymap $key zsh-system-clipboard-$keymap-$cmd this way:

        eval bindkey -M $keymap \"\ \"$key zsh-system-clipboard-$keymap-$cmd

And to make this change useful, unbind the single " " with:

bindkey -ar " "

This setup will force you to use space to actually use the system clipboard - whether it's paste or copy.

API

The plugin itself provides a separate cross-platform clipboard API for internal widgets. You can use this API as a standalone function.

To set system clipboard buffer:

zsh-system-clipboard-set "example text"

To get system clipboard buffer to stdout:

zsh-system-clipboard-get

It will show pretty-printed errors via stderr or stdout if something went wrong.

Additional mappings

zsh-system-clipboard emulates all of zsh's standard mappings but with system clipboard support. Some default zle commands are not mapped by default both by us and both by ZSH. However we have the binding zsh-system-clipboard-vicmd-vi-yank-eol which emulates vi-yank-eol which copies text from cursor to the end of the line but we don't map it to anything, no matter what is $ZSH_SYSTEM_CLIPBOARD_DISABLE_DEFAULT_MAPS. To use it, add to your ~/.zshrc:

# Bind Y to yank until end of line
bindkey -M vicmd Y zsh-system-clipboard-vicmd-vi-yank-eol

Thanks

Special thanks to Doron Behar (@doronbehar) for their interests, suggestions, time and pull requests.

Similar Projects

• zsh-vi-more/evil-registers

License

GPL-3.0