tmux-navigator

URL: https://github.com/christoomey/vim-tmux-navigator/

Maintainers: Matt Sturgeon


When combined with a set of tmux key bindings, the plugin will allow you to navigate seamlessly between vim splits and tmux panes using a consistent set of hotkeys.

WARNING: to work correctly, you must configure tmux separately.

Usage

This plugin provides the following mappings which allow you to move between vim splits and tmux panes seamlessly.

  • <ctrl-h> => Left
  • <ctrl-j> => Down
  • <ctrl-k> => Up
  • <ctrl-l> => Right
  • <ctrl-\> => Previous split

To use alternative key mappings, see plugins.tmux-navigator.settings.no_mappings.

Configure tmux

There are two main ways to configure tmux. Either install the tmuxPlugins.vim-tmux-navigator plugin or add a snippet to your tmux config:

  # Smart pane switching with awareness of vim splits.
  # See: https://github.com/christoomey/vim-tmux-navigator
  is_vim="ps -o state= -o comm= -t '#{pane_tty}' \
    | grep -iqE '^[^TXZ ]+ +(\\S+\\/)?g?(view|l?n?vim?x?|fzf)(diff)?$'"

  bind-key -n 'C-h' if-shell "$is_vim" 'send-keys C-h'  'select-pane -L'
  bind-key -n 'C-j' if-shell "$is_vim" 'send-keys C-j'  'select-pane -D'
  bind-key -n 'C-k' if-shell "$is_vim" 'send-keys C-k'  'select-pane -U'
  bind-key -n 'C-l' if-shell "$is_vim" 'send-keys C-l'  'select-pane -R'

  # Forwarding <C-\\> needs different syntax, depending on tmux version
  tmux_version='$(tmux -V | sed -En "s/^tmux ([0-9]+(.[0-9]+)?).*/\1/p")'
  if-shell -b '[ "$(echo "$tmux_version < 3.0" | bc)" = 1 ]' \
    "bind-key -n 'C-\\' if-shell \"$is_vim\" 'send-keys C-\\'  'select-pane -l'"
  if-shell -b '[ "$(echo "$tmux_version >= 3.0" | bc)" = 1 ]' \
    "bind-key -n 'C-\\' if-shell \"$is_vim\" 'send-keys C-\\\\'  'select-pane -l'"

  bind-key -T copy-mode-vi 'C-h' select-pane -L
  bind-key -T copy-mode-vi 'C-j' select-pane -D
  bind-key -T copy-mode-vi 'C-k' select-pane -U
  bind-key -T copy-mode-vi 'C-l' select-pane -R
  bind-key -T copy-mode-vi 'C-\' select-pane -l

See the upstream docs for more info.

plugins.tmux-navigator.enable

Whether to enable vim-tmux-navigator.

Type: boolean

Default: false

Example: true

Declared by:

plugins.tmux-navigator.package

The vim-tmux-navigator package to use.

Type: package

Default: pkgs.vimPlugins.vim-tmux-navigator

Declared by: