awesomewm-mirrors
/
awesomewm-vim-tmux-navigator
mirror of https://github.com/intrntbrn/awesomewm-vim-tmux-navigator.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

update readme

This commit is contained in:
BZ 2023-09-24 21:24:36 +02:00
parent de36b7cb00
commit 4d7e4055c7
1 changed files with 156 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

226
README.md
View File

@ -1,128 +1,214 @@
AwesomeWM - Vim - Tmux Navigator # AwesomeWM - Vim - Tmux Navigator
==================
<p align="center"> <p align="center">
<img src="https://user-images.githubusercontent.com/1234183/112910543-d9c5be80-90f3-11eb-840a-8c1d549c76ff.gif"> <img src="https://user-images.githubusercontent.com/1234183/112910543-d9c5be80-90f3-11eb-840a-8c1d549c76ff.gif">
</p> </p>
Usually vim and tmux have their own dedicated keybinds for navigation. Usually vim and tmux have their own dedicated keybinds for navigation.
Christoomey's plugin [vim-tmux-navigator](https://github.com/christoomey/vim-tmux-navigator) allows you to the use the same keybinds for vim and tmux. Christoomey's plugin [vim-tmux-navigator](https://github.com/christoomey/vim-tmux-navigator) allows you to the use the same keybinds for both of them.
This might be sufficient for floating wm users, but when using a tiling wm like awesomewm we can do better and add another layer. This might be sufficient for floating wm users, but when using a tiling wm like awesomewm we can do better and add another layer.
`awesomewm-vim-tmux-navigator` lets you navigate seamlessly between system windows, vim splits and tmux panes by only using your awesomewm navigation keybinds (e.g. <kbd>Mod4+hjkl</kbd>). `awesomewm-vim-tmux-navigator` lets you navigate seamlessly between system windows, (n)vim splits and tmux panes by only using your awesomewm navigation keybinds (e.g. <kbd>Mod4+hjkl</kbd>).
Every vim split and tmux pane is treated like a standalone system window, allowing you to forget your vim/tmux specific navigation hotkeys. Every split and pane is treated like a standalone system window, allowing you to forget your vim/tmux specific navigation hotkeys.
How does it work ## 💡 How does it work?
------------
It essentially works by sending the correct keypresses based on the context. It essentially works by emulating the correct keypresses based on the context.
Therefore the plugin has to detect whether the current focused application is vim, tmux or any other system window. Therefore the plugin has to detect whether the current focused application is vim, tmux, vim inside tmux (etc.) or any other system window.
The plugin offers two methods of determining the focused application: The plugin offers two methods of determining the focused application:
1. By using dynamic titles. The plugin tries to change the title (`WM_NAME`) of your terminal in order to differentitate between applications. However, not every shell-terminal-stack supports dynamic titles or is configured correctly out of the box. Minimal configurations are provided for `zsh` and `bash`. 1. By using dynamic titles. The plugin tries to change the title of your terminal in order to differentiate between applications. However, not every shell-terminal-stack supports dynamic titles or is configured correctly out of the box.
2. By using `pstree`. This should theoretically work on every setup, but it might perform slower due to having an extra process to spawn. This method can be enabled by setting the `experimental` flag. 2. By using `pstree`. This should theoretically work on every setup, but it might perform slightly slower due to having an extra process to spawn.
By default the plugin uses awesomewm's builtin implementation (`root.fake_input`) to emulate keypresses.
Installation ## 📦 Installation
------------
The configuration of vim or tmux is optional if you only use one of them.
### awesomewm:
Clone the repo:
### AwesomeWM
Clone the repo.
``` ```
git clone https://github.com/intrntbrn/awesomewm-vim-tmux-navigator ~/.config/awesome/awesomewm-vim-tmux-navigator git clone https://github.com/intrntbrn/awesomewm-vim-tmux-navigator ~/.config/awesome/awesomewm-vim-tmux-navigator
``` ```
It's not recommended to change the path since it's hardcoded in other configuration files.
Add your preferred navigation (focus) keybinds to `rc.lua` (e.g. <kbd>Mod4</kbd>+<kbd>arrows</kbd> or <kbd>Mod4</kbd>+<kbd>hjkl</kbd>): Import and configure the module:
``` ```
require("awesomewm-vim-tmux-navigator") { require("awesomewm-vim-tmux-navigator")({
up = {"Up", "k"}, mod = "Mod4",
down = {"Down", "j"}, mod_keysym = "Super_L", -- comment out to autodetect
left = {"Left", "h"}, up = { "Up", "k" },
right = {"Right", "l"}, down = { "Down", "j" },
mod = "Mod4", left = { "Left", "h" },
mod_keysym = "Super_L", right = { "Right", "l" },
--experimental = true
tmux = {
mods = { "Control_L" },
up = "Up",
down = "Down",
left = "Left",
right = "Right",
},
vim = {
mods = { "Control_L" },
up = "k",
down = "j",
left = "h",
right = "l",
},
-- focus = require("awful").client.focus.global_bydirection,
-- debug = print,
-- dont_restore_mods = true, -- prevent sticky mods (see troubleshooting)
-- use_pstree = true, -- detect app by using pstree instead of dynamic titles
-- use_xdotool = true, -- emulate keypresses using xdotool instead of builtin
})
```
If the awesomewm navigation keybinds are already in use, you have to **remove them manually**
in your `rc.lua`.
The corresponding keysym names can be retrieved by running the terminal command `xev -event keyboard`.
If `mod_keysym` is nil the plugin tries to detect your modifier.
### vim:
This plugin replaces `christoomey/vim-tmux-navigator`. Therefore you have to
replace it in your plugin manager with `intrntbrn/awesomewm-vim-tmux-navigator`.
However, both plugins share the same keybind commands, so it's not necessary to
adjust already configured custom keybinds.
Custom keybinds have to match your awesomewm configuration.
lazy.nvim (lua):
```lua
{
"intrntbrn/awesomewm-vim-tmux-navigator",
event = "VeryLazy",
build = "git -C ~/.config/awesome/awesomewm-vim-tmux-navigator/ pull",
keys = {
{ mode = { "n" }, "<C-h>", ":TmuxNavigateLeft<CR>", { noremap = true, silent = true } },
{ mode = { "n" }, "<C-j>", ":TmuxNavigateDown<CR>", { noremap = true, silent = true } },
{ mode = { "n" }, "<C-k>", ":TmuxNavigateUp<CR>", { noremap = true, silent = true } },
{ mode = { "n" }, "<C-l>", ":TmuxNavigateRight<CR>", { noremap = true, silent = true } },
},
config = function()
vim.g.tmux_navigator_no_mappings = 1
-- vim.g.tmux_navigator_no_dynamic_title = 1
-- vim.g.tmux_navigator_save_on_switch = 1
-- vim.g.tmux_navigator_disable_when_zoomed = 1
-- vim.g.tmux_navigator_preserve_zoom = 1
end,
} }
``` ```
Please verify that `mod` and `mod_keysym` matches your actual awesomewm modifier key by using the terminal applications `xev` and `xmodmap`. <details><summary>vim-plug (VimL):</summary>
For instance you might press the right super key and have to specify "Super_R" as your `mod_keysym`, or "Mod1" and "Alt_L" if you prefer to use the alt key.
Don't forget to remove your previously used navigation keybinds (or other conflicting keybinds) in `rc.lua`. ```viml
Plug 'intrntbrn/awesomewm-vim-tmux-navigator', { do = 'git -C ~/.config/awesome/awesomewm-vim-tmux-navigator/ pull' }
If you like to use your own custom directional focus function, you can do this by defining `focus`. let g:tmux_navigator_no_mappings = 1
Default is `awful.client.focus.global_bydirection`. noremap <silent> <c-h> :<C-U>TmuxNavigateLeft<cr>
noremap <silent> <c-j> :<C-U>TmuxNavigateDown<cr>
### Vim noremap <silent> <c-k> :<C-U>TmuxNavigateUp<cr>
Install using your favorite package manager, e.g. `vim-plug`: noremap <silent> <c-l> :<C-U>TmuxNavigateRight<cr>
" let g:tmux_navigator_no_dynamic_title = 1
```vim " let g:tmux_navigator_save_on_switch = 1
Plug 'intrntbrn/awesomewm-vim-tmux-navigator' " let g:tmux_navigator_disable_when_zoomed = 1
" let g:tmux_navigator_preserve_zoom = 1
``` ```
Remove `christoomey/vim-tmux-navigator` if you are using it. </details>
**Options:** ### tmux:
`let g:tmux_navigator_insert_mode = 1` to enable navigator keybinds in insert mode Add the following to your `tmux.conf`:
### Tmux
Add the following to your `tmux.conf` at the very bottom.
```tmux ```tmux
# Set title suffix to "- TMUX" # smart pane switching with awareness of vim splits and awesomewm windows
is_vim="ps -o state= -o comm= -t '#{pane_tty}' | grep -iqE '^[^TXZ ]+ +(\\S+\\/)?g?(view|n?vim?x?)(diff)?$'"
bind-key -n 'C-Left' if-shell "$is_vim" { send-keys C-h } { if-shell -F '#{pane_at_left}' {run-shell 'awesome-client "awesome.emit_signal(\"navigator::focus\", \"left\")" ' } { select-pane -L } }
bind-key -n 'C-Right' if-shell "$is_vim" { send-keys C-l } { if-shell -F '#{pane_at_right}' {run-shell 'awesome-client "awesome.emit_signal(\"navigator::focus\", \"right\")" ' } { select-pane -R } }
bind-key -n 'C-Up' if-shell "$is_vim" { send-keys C-k } { if-shell -F '#{pane_at_top}' {run-shell 'awesome-client "awesome.emit_signal(\"navigator::focus\", \"up\")" ' } { select-pane -T } }
bind-key -n 'C-Down' if-shell "$is_vim" { send-keys C-j } { if-shell -F '#{pane_at_bottom}' {run-shell 'awesome-client "awesome.emit_signal(\"navigator::focus\", \"down\")" ' } { select-pane -D } }
bind-key -T copy-mode-vi 'C-Left' if-shell "$is_vim" { send-keys C-h } { if-shell -F '#{pane_at_left}' {run-shell 'awesome-client "awesome.emit_signal(\"navigator::focus\", \"left\")" ' } { select-pane -L } }
bind-key -T copy-mode-vi 'C-Right' if-shell "$is_vim" { send-keys C-l } { if-shell -F '#{pane_at_right}' {run-shell 'awesome-client "awesome.emit_signal(\"navigator::focus\", \"right\")" ' } { select-pane -R } }
bind-key -T copy-mode-vi 'C-Up' if-shell "$is_vim" { send-keys C-k } { if-shell -F '#{pane_at_top}' {run-shell 'awesome-client "awesome.emit_signal(\"navigator::focus\", \"up\")" ' } { select-pane -T } }
bind-key -T copy-mode-vi 'C-Down' if-shell "$is_vim" { send-keys C-j } { if-shell -F '#{pane_at_bottom}' {run-shell 'awesome-client "awesome.emit_signal(\"navigator::focus\", \"down\")" ' } { select-pane -D } }
# set title suffix to "- TMUX" (optional when using pstree method)
set-option -g set-titles on set-option -g set-titles on
set-option -g set-titles-string '#S: #W - TMUX' set-option -g set-titles-string '#S: #W - TMUX'
# Smart pane switching with awareness of vim splits and system windows
is_vim="ps -o state= -o comm= -t '#{pane_tty}' \
| grep -iqE '^[^TXZ ]+ +(\\S+\\/)?g?(view|n?vim?x?)(diff)?$'"
bind -n C-Left if-shell "$is_vim" "send-keys C-h" "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh left'"
bind -n C-Down if-shell "$is_vim" "send-keys C-j" "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh down'"
bind -n C-Up if-shell "$is_vim" "send-keys C-k" "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh up'"
bind -n C-Right if-shell "$is_vim" "send-keys C-l" "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh right'"
bind-key -T copy-mode-vi 'C-Left' "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh left'"
bind-key -T copy-mode-vi 'C-Down' "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh down'"
bind-key -T copy-mode-vi 'C-Up' "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh up'"
bind-key -T copy-mode-vi 'C-Right' "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh right'"
``` ```
Troubleshooting Custom keybinds have to match your awesomewm configuration.
---------------
1. Make sure there are no conflicting keybindings.
2. Check https://github.com/christoomey/vim-tmux-navigator#troubleshooting. ## ❓ Troubleshooting
3. Try to enable dynamic titles in your shell. Minimal configurations are provided for `zsh` and `bash`: ### Setup:
1. Enable debug mode:
```lua
debug = function(msg) require("naughty").notify({ text = msg }) end
```
2. Make sure there are no conflicting keybinds.
You can bypass conflicts in awesomewm by invoking the plugin from the terminal for verification:
```bash
echo "select a window" && sleep 2 && awesome-client 'awesome.emit_signal("navigator::navigate", "up")'
```
3. Verify if dynamic titles are working. The title of (n)vim and tmux
applications should end with "- (N)VIM" or "- TMUX" respectively.
If you don't have a titlebar, you can use the terminal command `xprop | grep WM_NAME`.
If dynamic titles are not working, set `use_pstree` to true or configure
your shell-terminal-stack correctly. Minimal configurations are provided for `zsh` and `bash`:
``` ```
echo "source ~/.config/awesome/awesomewm-vim-tmux-navigator/dynamictitles.zsh" >> ~/.zshrc echo "source ~/.config/awesome/awesomewm-vim-tmux-navigator/dynamictitles.zsh" >> ~/.zshrc
``` ```
or
``` ```
echo "source ~/.config/awesome/awesomewm-vim-tmux-navigator/dynamictitles.bash" >> ~/.bashrc echo "source ~/.config/awesome/awesomewm-vim-tmux-navigator/dynamictitles.bash" >> ~/.bashrc
``` ```
After a correct installation the title of a tmux session should end with "- TMUX" and "- VIM" or "- NVIM" for vim or nvim sessions respectively. 4. Check https://github.com/christoomey/vim-tmux-navigator#troubleshooting.
Check the title of the terminal client in your wm tasklist or by using the terminal application `xprop` (title is property `WM_NAME`).
In case your title does not change, your terminal and/or shell may not support dynamic titles. Try other. 5. Create an issue.
4. Set `experimental = true`. The experimental mode does not require dynamic titles, but might be a bit slower. ### Sticky Mods:
Integration In order to emulate keypresses in vim/tmux, the plugin needs to release your wm
--------------- modifier (e.g. <kbd>mod4</kbd>) temporarily and restore it afterwards.
This plugin can be used from everywhere and does not require any kind of import or reference. There is a race condition if the user was fast enough to release the modifier
during this operation resulting in _sticky_ mods. This issue is very unlikely to be ever solved.
Awesomewm: `awesome.emit_signal("navigator::navigate", "left")` Restoring mods can be disabled by setting the `dont_restore_mods` option.
Please note that you can't hold the modifier down for consecutive actions using
Shell: `echo 'awesome.emit_signal("navigator::navigate", "up")' | awesome-client` this option. However, this option works very well with combo-keybinds using custom keyboards (qmk similar software/firmware).
## 📡 API
- **navigate**: directional vim/tmux aware navigation
- **focus**: regular directional system window navigation
awesomewm:
````lua
w```
shell:
```bash
awesome-client 'awesome.emit_signal("navigator::navigate", "up")'
awesome-client 'awesome.emit_signal("navigator::focus", "down")'
````