tobira.nvim
Open the next door in your Vim journey โ personalized command discovery based on your actual usage
๐ป A better and friendly vi(vim) mode plugin for ZSH.
git clone https://github.com/jeffreytse/zsh-vi-mode.gitjeffreytse/zsh-vi-mode
๐ป A better and friendly vi(vim) mode plugin for ZSH.
ZSH plugin for Agnosticism.
๐ง Check out my new project โ Grimoire: a free, open-source package manager for best practices โ 1000+ skills across 26 domains (engineering, law, finance, design, health, and more), each sourced from a real institution or study. Install once, and your AI routes to the right skill automatically. โญ Star it if you find it useful!
Maybe you have experienced the default Vi mode in Zsh, after turning on the default Vi mode, you gradually found that it had many problems, some features were not perfect or non-existent, and some behaviors even were different from the native Vi(Vim) mode.
Although the default Vi mode was a bit embarrassing and unpleasant, you kept on using it and gradually lost your interest on it after using for a period of time. Eventually, you disappointedly gave up.
You never think of the Vi mode for a long time, one day you accidentally discovered this plugin, you read here and realize that this plugin is to solve the above problems and make you fall in love to Vi mode again. A smile suddenly appeared on your face like regaining a good life.
If winter comes, can spring be far behind?
gx.vv.10p and 4fa.ZSH: >= 5.1.0
Bundle zsh-vi-mode in your .zshrc
antigen bundle jeffreytse/zsh-vi-mode
Load zsh-vi-mode as a plugin in your .zshrc
zplug "jeffreytse/zsh-vi-mode"
Include the load command in your .zshrc
zgen load jeffreytse/zsh-vi-mode
Include the load command in your .zshrc
zinit ice depth=1 zinit light jeffreytse/zsh-vi-mode
Note: the use of depth=1 ice is optional, other types of ice are neither
recommended nor officially supported by this plugin.
Clone zsh-vi-mode into your custom plugins repo
git clone https://github.com/jeffreytse/zsh-vi-mode \ $ZSH_CUSTOM/plugins/zsh-vi-mode
Then load as a plugin in your .zshrc
plugins+=(zsh-vi-mode)
Keep in mind that plugins need to be added before oh-my-zsh.sh is sourced.
Add zsh-vi-mode to your plugins file (e.g. ~/.zsh_plugins.txt)
jeffreytse/zsh-vi-mode
Load zsh-vi-mode as a plugin in your .zshrc
plug "jeffreytse/zsh-vi-mode"
Load zsh-vi-mode as a plugin in your .zimrc
zmodule jeffreytse/zsh-vi-mode
For Homebrew users, you can install it through the following command
brew install zsh-vi-mode
Then source it in your .zshrc (or .bashrc)
source $(brew --prefix)/opt/zsh-vi-mode/share/zsh-vi-mode/zsh-vi-mode.plugin.zsh
For Arch Linux users, you can install it through the following command
yay -S zsh-vi-mode
or the latest update (unstable)
yay -S zsh-vi-mode-git
Then source it in your .zshrc (or .bashrc)
source /usr/share/zsh/plugins/zsh-vi-mode/zsh-vi-mode.plugin.zsh
For users of Nix, as of e7e3480530b34a9fe8cb52963ec2cf66e6707e15 you can source the plugin through the following configuration
programs = {
zsh = {
interactiveShellInit = ''
source ${pkgs.zsh-vi-mode}/share/zsh-vi-mode/zsh-vi-mode.plugin.zsh
'';
};
};
Or if you prefer home-manager:
home-manager.users.[your username] = { pkgs, ... }: {
programs = {
zsh = {
initExtra = ''
source ${pkgs.zsh-vi-mode}/share/zsh-vi-mode/zsh-vi-mode.plugin.zsh
'';
};
};
};
You can also use home-manager's built-in "plugin" feature:
home-manager.users.[your username] = { pkgs, ... }: {
programs = {
zsh = {
plugins = [
{
name = "vi-mode";
src = pkgs.zsh-vi-mode;
file = "share/zsh-vi-mode/zsh-vi-mode.plugin.zsh";
}
];
};
};
};
Available in dm9pZCAq overlay
eselect repository enable dm9pZCAq emerge --sync dm9pZCAq emerge app-shells/zsh-vi-mode
Then source it in your .zshrc (or .bashrc)
source /usr/share/zsh/site-contrib/zsh-vi-mode/zsh-vi-mode.plugin.zsh
Clone this repository somewhere ($HOME/.zsh-vi-mode for example)
git clone https://github.com/jeffreytse/zsh-vi-mode.git $HOME/.zsh-vi-mode
Then source it in your .zshrc (or .bashrc)
source $HOME/.zsh-vi-mode/zsh-vi-mode.plugin.zsh
Use ESC or CTRL-[ to enter Normal mode.
But some people may like the custom escape key such as jj, jk and so on,
if you want to custom the escape key, you can learn more from here.
ctrl-p : Previous command in historyctrl-n : Next command in history/ : Search backward in historyn : Repeat the last /Normal mode is indicated with block style cursor, and Insert mode with
beam style cursor by default.
In Normal mode you can use vv to edit current command line in an editor
(e.g. vi/vim/nvim...), because it is bound to the Visual mode.
You can change the editor by ZVM_VI_EDITOR option, by default it is
$EDITOR.
$ : To the end of the line^ : To the first non-blank character of the line0 : To the first character of the linew : [count] words forwardW : [count] WORDS forwarde : Forward to the end of word [count] inclusiveE : Forward to the end of WORD [count] inclusiveb : [count] words backwardB : [count] WORDS backwardt{char} : Till before [count]'th occurrence of {char} to the rightT{char} : Till before [count]'th occurrence of {char} to the leftf{char} : To [count]'th occurrence of {char} to the rightF{char} : To [count]'th occurrence of {char} to the left; : Repeat latest f, t, F or T [count] times, : Repeat latest f, t, F or T in opposite directioni : Insert text before the cursorI : Insert text before the first character in the linea : Append text after the cursorA : Append text at the end of the lineo : Insert new command line below the current oneO : Insert new command line above the current oneThere are 2 kinds of keybinding mode for surround operating, default is
classic mode, you can choose the mode by setting ZVM_VI_SURROUND_BINDKEY
option.
classic mode (verb->s->surround)S" : Add " for visual selectionys" : Add " for visual selectioncs"' : Change " to 'ds" : Delete "s-prefix mode (s->verb->surround)sa" : Add " for visual selectionsd" : Delete "sr"' : Change " to 'Note that key sequences must be pressed in fairly quick succession to avoid a timeout. You may extend this timeout with the ZVM_KEYTIMEOUT option.
vi" : Select the text object inside the quotesva( : Select the text object including the bracketsThen you can do any operation for the selection:
vi" -> S[ or sa[ => "object" -> "[object]"va" -> S[ or sa[ => "object" -> ["object"]di( or vi( -> dca( or va( -> cyi( or vi( -> yIn normal mode, typing ctrl-a will increase to the next keyword, and typing
ctrl-x will decrease to the next keyword. The keyword can be at the cursor,
or to the right of the cursor (on the same line). The keyword could be as
below:
For example:
9 => 10aa99bb => aa100bbaa100bc => aa101bc0xDe => 0xdf0Xdf => 0Xe00b101 => 0b1100B11 => 0B101true => falseyes => noon => offT => FFri => SatOct => NovMonday => TuesdayJanuary => February+ => -++ => --== => !=!== => ===&& => ||and => or100 => 99aa100bb => aa99bb0 => -10xdE0 => 0xDDF0xffFf0 => 0xfffef0xfffF0 => 0xFFFEF0x0 => 0xffffffffffffffff0Xf => 0Xe0b100 => 0b0100B100 => 0B011True => FalseOn => OffSun => SatJan => DecMonday => SundayAugust => July/ => *++ => --== => !=!== => ===|| => &&or => andzsh-vi-mode can integrate with your system clipboard. This feature is disabled
by default. Therefore, you can't automatically copy to the system clipboard when
you stroke yy, yw and so on, but only allowed to paste from it. If you want
to enable this feature, you can set the option:
Enable:
ZVM_SYSTEM_CLIPBOARD_ENABLED=true
Auto-detection:
pbcopy and pbpastewl-copy and wl-paste -nxclip or xselOverride commands:
ZVM_CLIPBOARD_COPY_CMD='xclip -selection clipboard' ZVM_CLIPBOARD_PASTE_CMD='xclip -selection clipboard -o'
Keybindings:
gp paste clipboard after cursor, gP before cursorgp/gP replace selection with clipboardNote: p/P keep using ZLE's CUTBUFFER; gp/gP use the system clipboard.
Behavior:
WSL (Windows Subsystem for Linux):
# Using Windows clipboard ZVM_SYSTEM_CLIPBOARD_ENABLED=true ZVM_CLIPBOARD_COPY_CMD='clip.exe' ZVM_CLIPBOARD_PASTE_CMD='powershell.exe -NoProfile -Command Get-Clipboard'
or using win32yank:
ZVM_CLIPBOARD_COPY_CMD='win32yank.exe -i --crlf' ZVM_CLIPBOARD_PASTE_CMD='win32yank.exe -o --lf'
OSC 52 is an escape sequence that allows copying text to the clipboard over SSH or in tmux sessions without requiring X11 forwarding or other clipboard tools.
Enable OSC 52:
ZVM_SYSTEM_CLIPBOARD_ENABLED=true ZVM_CLIPBOARD_USE_OSC52=true
By default, the plugin automatically detects if you're in a tmux session (via the $TMUX variable) and wraps the escape sequence accordingly. You can control this behavior:
# Always use tmux wrapping (even if not in tmux) ZVM_CLIPBOARD_OSC52_TMUX=true # Never use tmux wrapping (even if in tmux) ZVM_CLIPBOARD_OSC52_TMUX=false # Auto-detect (default behavior, check $TMUX variable) ZVM_CLIPBOARD_OSC52_TMUX=
Note: OSC 52 requires your terminal emulator and tmux (if used) to support clipboard integration. Most modern terminals support this feature.
In Normal mode, you can use gx to open the URL or file path under the cursor.
http://, https://, ftp://, file://), it will open in your default web browser.The plugin automatically detects whether the text under the cursor is a URL or a file path and opens it accordingly using your system's default opener:
openxdg-openYou can override the default open command by setting the ZVM_OPEN_CMD option.
Also, you can set the ZVM_OPEN_URL_CMD and ZVM_OPEN_FILE_CMD options to
specify different commands for opening URLs and files respectively.
Overriding commands example:
# Override the default open command ZVM_OPEN_CMD='xdg-open' # Override the open command for URLs ZVM_OPEN_URL_CMD='firefox' # Override the open command for URLs on macOS ZVM_OPEN_URL_CMD='open -a "Safari"' # Override the open command for files ZVM_OPEN_FILE_CMD='code' # Open files with Visual Studio Code # Override the open command for files on macOS ZVM_OPEN_FILE_CMD='open -a "Visual Studio Code"' # Override the open command for files on Windows ZVM_OPEN_FILE_CMD='powershell.exe -Command "Start-Process code"' # Override the open command for files on Windows using cmd ZVM_OPEN_FILE_CMD='start code'
For Windows users, you can create a script for opening on Windows, for example,
a script /usr/local/bin/xdg-open with content:
#!/usr/bin/env bash
# A Linux-like "xdg-open" command for WSL
# Supports: http, https, ftp, ftps, file URLs, local files and directories
if [ $# -eq 0 ]; then
echo "Usage: open <file|dir|url>"
exit 1
fi
for target in "$@"; do
# If it is a URL (http, https, ftp, ftps, file)
if [[ "$target" =~ ^(https?|ftps?|file):// ]]; then
explorer.exe "$target"
continue
fi
# Otherwise, treat as regular file or directory paths
if [ -e "$target" ]; then
win_path=$(wslpath -w "$target")
explorer.exe "$win_path"
else
echo "open: $target not found"
fi
done
And add executive permission:
sudo chmod +x /usr/local/bin/xdg-open
Then set the ZVM_OPEN_CMD option:
ZVM_OPEN_CMD='/usr/local/bin/xdg-open'
Or you can use cygstart if you are using Cygwin:
ZVM_OPEN_CMD='cygstart'
Or set the cygstart command as a alias as below:
# Add a open alias to your .zshrc for Windows users open='cygstart'
You can use below options to custom the escape key which could better match
your flavor, such as jj or jk and so on.
ZVM_VI_ESCAPE_BINDKEY: The vi escape key in all modes (default is ^[
=> ESC)ZVM_VI_INSERT_ESCAPE_BINDKEY: The vi escape key in insert mode (default
is $ZVM_VI_ESCAPE_BINDKEY)ZVM_VI_VISUAL_ESCAPE_BINDKEY: The vi escape key in visual mode (default
is $ZVM_VI_ESCAPE_BINDKEY)ZVM_VI_OPPEND_ESCAPE_BINDKEY: The vi escape key in operator pending mode
(default is $ZVM_VI_ESCAPE_BINDKEY)For example:
# Only changing the escape key to `jk` in insert mode, we still # keep using the default keybindings `^[` in other modes ZVM_VI_INSERT_ESCAPE_BINDKEY=jk
This plugin has supported to choose the readkey engine for reading and
processing the key events. It easy to do by the ZVM_READKEY_ENGINEoption,
currently the below engines are supported:
ZVM_READKEY_ENGINE_NEX: It is a better readkey engine to replace ZLE (Beta).ZVM_READKEY_ENGINE_ZLE: It is Zsh's default readkey engine (ZLE).ZVM_READKEY_ENGINE_DEFAULT: It is the default engine of this plugin
(It's the NEX engine now).The NEX is a better engine for reading and handling the key events than the Zsh's ZLE engine, currently the NEX engine is still at beta stage, you can change back to Zsh's ZLE engine if you want.
For example:
# Change to Zsh's default readkey engine ZVM_READKEY_ENGINE=$ZVM_READKEY_ENGINE_ZLE
You can use ZVM_KEYTIMEOUT option to adjust the key input timeout for
waiting for next key, default is 0.4 seconds.
The escape key is a special case, it can be used standalone. NEX engine waits for a period after receiving the escape character, to determine whether it is standalone or part of an escape sequence. While waiting, additional key presses make the escape key behave as a meta key. If no other key presses come in, it is handled as a standalone escape.
For the NEX engine, we can use ZVM_ESCAPE_KEYTIMEOUT option to adjust
the waiting timeout for the escape key, default is 0.03 seconds.
Since there are some config options relied to some variables defined in
the plugin, however, some not. We need to provide an unified config entry
function. The name of entry function is stored in an option called
ZVM_CONFIG_FUNC and default value is zvm_config, you can change to
others for fitting your flavor.
If this config function exists, it will be called automatically, you can do some configurations in this aspect before you source this plugin. For example:
function zvm_config() {
ZVM_LINE_INIT_MODE=$ZVM_MODE_INSERT
ZVM_VI_INSERT_ESCAPE_BINDKEY=jk
}
source ~/zsh-vi-mode.zsh
This plugin has provided a mechanism to execute extra commands, and now you have the below aspects for executing something:
zvm_before_init_commands=() zvm_after_init_commands=() zvm_before_select_vi_mode_commands=() zvm_after_select_vi_mode_commands=() zvm_before_lazy_keybindings_commands=() zvm_after_lazy_keybindings_commands=()
Since the default initialization mode, this plugin
will overwrite the previous key bindings, this causes the key bindings of
other plugins (i.e. fzf, zsh-autocomplete, etc.) to fail.
You can solve the compatibility issue as below:
# Append a command directly
zvm_after_init_commands+=('[ -f ~/.fzf.zsh ] && source ~/.fzf.zsh')
or
# Define an init function and append to zvm_after_init_commands
function my_init() {
[ -f ~/.fzf.zsh ] && source ~/.fzf.zsh
}
zvm_after_init_commands+=(my_init)
or
# The plugin will auto execute this zvm_after_init function
function zvm_after_init() {
[ -f ~/.fzf.zsh ] && source ~/.fzf.zsh
}
or if you are using the zinit:
# For postponing loading `fzf` zinit ice lucid wait zinit snippet OMZP::fzf
By default, the lazy keybindings feature is enabled, all
the keybindings of normal and visual mode should be executed by the
zvm_after_lazy_keybindings_commands. For example:
# The plugin will auto execute this zvm_after_lazy_keybindings function
function zvm_after_lazy_keybindings() {
bindkey -M vicmd 's' your_normal_widget
bindkey -M visual 'n' your_visual_widget
}
This plugin has two functions for you to define custom widgets and keybindings. In case of unnecessary problems, it is better to use them, especially when you meet the key conflicts.
To define a custom widget, you should:
# If [your_custom_widget] were ignored, it will be the same with <your_custom_widget> zvm_define_widget <your_custom_widget> [your_custom_function]
To define a keybinding, you should:
zvm_bindkey <keymap> <keys> <widget>
For example:
# Your custom widget
function my_custom_widget() {
echo 'Hello, ZSH!'
}
# The plugin will auto execute this zvm_after_lazy_keybindings function
function zvm_after_lazy_keybindings() {
# Here we define the custom widget
zvm_define_widget my_custom_widget
# In normal mode, press Ctrl-E to invoke this widget
zvm_bindkey vicmd '^E' my_custom_widget
}
This plugin has provided a ZVM_MODE variable for you to retrieve
current vi mode and better show the indicator.
And currently the below modes are supported:
ZVM_MODE_NORMAL ZVM_MODE_INSERT ZVM_MODE_VISUAL ZVM_MODE_VISUAL_LINE ZVM_MODE_REPLACE
For updating the vi mode indicator, we should add our commands to
zvm_after_select_vi_mode_commands. For example:
# The plugin will auto execute this zvm_after_select_vi_mode function
function zvm_after_select_vi_mode() {
case $ZVM_MODE in
$ZVM_MODE_NORMAL)
# Something you want to do...
;;
$ZVM_MODE_INSERT)
# Something you want to do...
;;
$ZVM_MODE_VISUAL)
# Something you want to do...
;;
$ZVM_MODE_VISUAL_LINE)
# Something you want to do...
;;
$ZVM_MODE_REPLACE)
# Something you want to do...
;;
esac
}
This plugin has provided some options for users to custom the cursor style for better terminal compatibility.
ZVM_CURSOR_STYLE_ENABLED
option (Default is true)# Disable the cursor style feature ZVM_CURSOR_STYLE_ENABLED=false
# The prompt cursor in normal mode ZVM_NORMAL_MODE_CURSOR # The prompt cursor in insert mode ZVM_INSERT_MODE_CURSOR # The prompt cursor in visual mode ZVM_VISUAL_MODE_CURSOR # The prompt cursor in visual line mode ZVM_VISUAL_LINE_MODE_CURSOR # The prompt cursor in operator pending mode ZVM_OPPEND_MODE_CURSOR
ZVM_CURSOR_USER_DEFAULT ZVM_CURSOR_BLOCK ZVM_CURSOR_UNDERLINE ZVM_CURSOR_BEAM ZVM_CURSOR_BLINKING_BLOCK ZVM_CURSOR_BLINKING_UNDERLINE ZVM_CURSOR_BLINKING_BEAM
ZVM_INSERT_MODE_CURSOR=$ZVM_CURSOR_BEAM ZVM_NORMAL_MODE_CURSOR=$ZVM_CURSOR_BLOCK ZVM_OPPEND_MODE_CURSOR=$ZVM_CURSOR_UNDERLINE
# The plugin will auto execute this zvm_config function
zvm_config() {
# Retrieve default cursor styles
local ncur=$(zvm_cursor_style $ZVM_NORMAL_MODE_CURSOR)
local icur=$(zvm_cursor_style $ZVM_INSERT_MODE_CURSOR)
# Append your custom color for your cursor
ZVM_INSERT_MODE_CURSOR=$icur'\e\e]12;red\a'
ZVM_NORMAL_MODE_CURSOR=$ncur'\e\e]12;#008800\a'
}
We can use ZVM_TERM option to set the term type for plugin to handle
terminal escape sequences, default is $TERM. It could be xterm-256color,
alacritty-256color, st-256color, etc. It's important for some
terminal emulators to show cursor properly.
You can use ZVM_VI_HIGHLIGHT_BACKGROUND, ZVM_VI_HIGHLIGHT_FOREGROUND
and ZVM_VI_HIGHLIGHT_EXTRASTYLE to change the highlight behaviors (
surrounds, visual-line, etc.), the color value could be a color name or
a hex color value.
For example:
ZVM_VI_HIGHLIGHT_FOREGROUND=green # Color name ZVM_VI_HIGHLIGHT_FOREGROUND=#008800 # Hex value ZVM_VI_HIGHLIGHT_BACKGROUND=red # Color name ZVM_VI_HIGHLIGHT_BACKGROUND=#ff0000 # Hex value ZVM_VI_HIGHLIGHT_EXTRASTYLE=bold,underline # bold and underline
You can set the command line initial mode by the ZVM_LINE_INIT_MODE
option.
Currently the below modes are supported:
ZVM_MODE_LAST : Starting with last mode (Default).ZVM_MODE_INSERT : Starting with insert mode.ZVM_MODE_NORMAL : Starting with normal mode.For example:
# Always starting with insert mode for each command line ZVM_LINE_INIT_MODE=$ZVM_MODE_INSERT
This plugin has supported the lazy keybindings feature, and it is enabled
by default. To disable it, you can set the option ZVM_LAZY_KEYBINDINGS
to false before this plugin is loaded. This feature will postpone all
the keybindings of normal and visual mode to the first time you enter
the normal mode.
It can greatly improve the startup speed, especially you open the terminal and just want to execute a simple command.
In order to prevent various problems related to keybindings caused by the plugin sourcing sequence, and also keep the same functionality for this plugin, the initialization of this plugin was postponed to the first command line starting.
However, almost all plugins are initialized when the script is sourced.
Therefore, this plugin provides an option ZVM_INIT_MODE to change the
initialization mode.
For example:
# Do the initialization when the script is sourced (i.e. Initialize instantly) ZVM_INIT_MODE=sourcing
Issues and Pull Requests are greatly appreciated. If you've never contributed to an open source project before I'm more than happy to walk you through how to create a pull request.
You can start by opening an issue describing the problem that you're looking to resolve and we'll go from there.
This theme is licensed under the MIT license ยฉ Jeffrey Tse.
more like this
Open the next door in your Vim journey โ personalized command discovery based on your actual usage
MTT File Manager is a Rust-based Windows file manager with tabbed navigation, rich media previews, deep system integratโฆ
search projects, people, and tags