📖 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
🔀 Pipe Support Detects correct command in pipelines cat file | grep -i → opens man grep tree | less -N → opens man less	🛠️ 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)

1. Type a command (e.g., ls -la or git commit --amend)
2. Press Escape to enter vi normal mode
3. Move cursor to any word
4. 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