📖 zsh-vi-man

March 2, 2026 · View on GitHub

📖 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

📝 Value Extraction

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

🛠️ Multiple Formats

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.

Made with ❤️ by Tuna Cuma