📖 zsh-vi-man
Smart man page lookup for zsh vi mode (now with emacs mode support!)
Press K (vi normal mode), Ctrl-X k (emacs mode), or Ctrl-K (vi insert mode) on any command or option to instantly open its man page
✨ Features
🎯 Smart Detection
Automatically finds the right man page for subcommands
git commit → man git-commit
docker run → man docker-run
|
🔍 Option Jumping
Opens man page directly at the option definition
grep -r → jumps to -r entry
ls --color → jumps to --color entry
|
🔗 Combined Options
Works with combined short options
rm -rf → finds both -r and -f
tar -xvf → finds -x, -v, -f
|
Handles options with values
--color=always → searches --color
--output=file.txt → searches --output
|
🔀 Complex Syntax Support
Detects correct command in pipelines, command substitutions & more
cat file | grep -i → opens man grep
if true && ! [ -e → opens man test at -e
printf "$(pwd; ls → opens man ls
|
Supports various man page styles
GNU: -R, -r, --recursive
jq: --slurp / -s:
find: -name, -type, -exec
|
📦 Installation
zinit
zinit light TunaCuma/zsh-vi-man
antidote
Add to your .zsh_plugins.txt:
TunaCuma/zsh-vi-man
oh-my-zsh
git clone https://github.com/TunaCuma/zsh-vi-man \
${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-vi-man
Then add to your .zshrc:
plugins=(... zsh-vi-man)
Manual
git clone https://github.com/TunaCuma/zsh-vi-man ~/.zsh-vi-man
echo 'source ~/.zsh-vi-man/zsh-vi-man.plugin.zsh' >> ~/.zshrc
🚀 Usage
Vi Normal Mode (Default)
- Type a command (e.g.,
ls -la or git commit --amend)
- Press
Escape to enter vi normal mode
- Move cursor to any word
- Press
K to open the man page
Emacs Mode / Vi Insert Mode
Without leaving insert mode or if using emacs mode:
- Emacs mode: Press
Ctrl-X then k
- Vi insert mode: Press
Ctrl-K
Examples
| Command |
Cursor On |
Result |
ls -la |
ls |
Opens man ls |
ls -la |
-la |
Opens man ls, jumps to -l |
git commit --amend |
commit |
Opens man git-commit |
grep --color=auto |
--color=auto |
Opens man grep, jumps to --color |
cat file | sort -r |
-r |
Opens man sort, jumps to -r |
find . -name "*.txt" |
-name |
Opens man find, jumps to -name |
⚙️ Configuration
Set these variables before sourcing the plugin:
# Vi normal mode key (default: K)
ZVM_MAN_KEY='?'
# Emacs mode key sequence (default: ^Xk, i.e., Ctrl-X k)
ZVM_MAN_KEY_EMACS='^X^K' # Example: Ctrl-X Ctrl-K
# Vi insert mode key (default: ^K, i.e., Ctrl-K)
ZVM_MAN_KEY_INSERT='^H' # Example: Ctrl-H
# Enable/disable emacs mode binding (default: true)
ZVM_MAN_ENABLE_EMACS=false
# Enable/disable vi insert mode binding (default: true)
ZVM_MAN_ENABLE_INSERT=false
# Use a different pager (default: less)
ZVM_MAN_PAGER='nvim'
Troubleshooting
Keybindings not working?
If keybindings don’t work after sourcing the plugin, try running:
zvm_man_rebind
This can happen if:
- Your plugin manager loads plugins before setting up keymaps
- You call
bindkey -e or bindkey -v after the plugin loads
- Another plugin resets your keybindings
For persistent issues, add this to your .zshrc after sourcing the plugin:
# Ensure zsh-vi-man bindings are set
zvm_man_rebind
Key Binding Examples
| Key Notation |
Description |
^K |
Ctrl-K |
^Xk |
Ctrl-X then k |
^X^K |
Ctrl-X then Ctrl-K |
\ek |
Alt-k (or Escape then k) |
For special keys, use zsh notation: ^[ for Escape, ^? for Backspace, etc.
🔌 Integration with zsh-vi-mode
This plugin works seamlessly with zsh-vi-mode. It automatically detects zsh-vi-mode and hooks into its lazy keybindings system.
For best results, source this plugin after zsh-vi-mode:
source /path/to/zsh-vi-mode.zsh
source /path/to/zsh-vi-man.zsh
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
# Run tests
zsh test_patterns.zsh
# Test locally
source ./zsh-vi-man.plugin.zsh
📄 License
MIT License - see LICENSE for details.
评论