mirror of
https://github.com/jabirali/tmux-tilish.git
synced 2026-09-10 07:06:18 -04:00
merge: use 'layout_keys' and 'refresh_hooks' settings
This commit is contained in:
Farzad Majidfayyaz
Jabir Ali Ouassou
parent
b705b2ef9e
commit
48fe1e4df4
107
README.md
107
README.md
|
|
@ -7,17 +7,17 @@
|
|||
---
|
||||
|
||||
This is a plugin that makes [`tmux`][6] behave more like a typical
|
||||
[dynamic window manager][7]. It is heavily inspired by [`i3wm`][8], and
|
||||
most keybindings are taken [directly from there][1]. However, I have made
|
||||
some adjustments to make these keybindings more consistent with `vim`:
|
||||
[dynamic window manager][7]. It is heavily inspired by [`i3wm`][8], and
|
||||
most keybindings are taken [directly from there][1]. However, I have made
|
||||
some adjustments to make these keybindings more consistent with `vim`:
|
||||
using <kbd>h</kbd><kbd>j</kbd><kbd>k</kbd><kbd>l</kbd> instead of
|
||||
<kbd>j</kbd><kbd>k</kbd><kbd>l</kbd><kbd>;</kbd> for directions, and
|
||||
using `vim`'s definitions of "split" and "vsplit". There is also an
|
||||
"easy mode" available for non-`vim` users, which uses arrow keys
|
||||
<kbd>j</kbd><kbd>k</kbd><kbd>l</kbd><kbd>;</kbd> for directions, and
|
||||
using `vim`'s definitions of "split" and "vsplit". There is also an
|
||||
"easy mode" available for non-`vim` users, which uses arrow keys
|
||||
instead of <kbd>h</kbd><kbd>j</kbd><kbd>k</kbd><kbd>l</kbd>.
|
||||
|
||||
The plugin has been verified to work on `tmux` v1.9, v2.6, v2.7, v2.9, and v3.0.
|
||||
Some features are only available on newer versions of `tmux` (currently v2.7+),
|
||||
The plugin has been verified to work on `tmux` v1.9, v2.6, v2.7, v2.9, and v3.0.
|
||||
Some features are only available on newer versions of `tmux` (currently v2.7+),
|
||||
but I hope to provide at least basic support for most `tmux` versions in active use.
|
||||
If you encounter any problems, please file an issue and I'll try to look into it.
|
||||
|
||||
|
|
@ -31,13 +31,13 @@ If you encounter any problems, please file an issue and I'll try to look into it
|
|||
Okay, so who is this plugin for anyway? You may be interested in this if:
|
||||
|
||||
- You're using or interested in using `tmux`, but find the default keybindings
|
||||
a bit clunky. This lets you try out an alternative keybinding paradigm,
|
||||
which uses a modifier key (<kbd>Alt</kbd>) instead of a prefix key
|
||||
a bit clunky. This lets you try out an alternative keybinding paradigm,
|
||||
which uses a modifier key (<kbd>Alt</kbd>) instead of a prefix key
|
||||
(<kbd>Ctrl</kbd> + <kbd>b</kbd>). The plugin also makes it easier to do
|
||||
automatic tiling via `tmux` layouts, as opposed to splitting panes manually.
|
||||
- You use `i3wm`, but also do remote work over `ssh` + `tmux`. This lets
|
||||
- You use `i3wm`, but also do remote work over `ssh` + `tmux`. This lets
|
||||
you use similar keybindings in both contexts.
|
||||
- You also use other platforms like Gnome, Mac, or WSL. You want to take
|
||||
- You also use other platforms like Gnome, Mac, or WSL. You want to take
|
||||
your `i3wm` muscle memory with you via `tmux`.
|
||||
- You're not really using `i3wm` anymore, but you did like how it handled
|
||||
terminals and workspaces. You'd like to keep working that way in terminals,
|
||||
|
|
@ -71,7 +71,7 @@ Just replace `main-vertical` with one of the layouts from the `tmux` `man` page:
|
|||
| fully tiled | `tiled` |
|
||||
|
||||
The words "split" and "vsplit" refer to the layouts you get in `vim` when
|
||||
running `:split` and `:vsplit`, respectively. (Unfortunately, what is called
|
||||
running `:split` and `:vsplit`, respectively. (Unfortunately, what is called
|
||||
a "vertical" and "horizontal" split varies between programs.)
|
||||
If you do not set this option, `tilish` will not autoselect any layout; you
|
||||
can still choose layouts manually using the keybindings listed below.
|
||||
|
|
@ -103,7 +103,7 @@ It is also recommended that you add the following to the top of your `tmux.conf`
|
|||
|
||||
The first line prevents e.g. <kbd>Esc</kbd> + <kbd>h</kbd> from triggering the
|
||||
<kbd>Alt</kbd> + <kbd>h</kbd> keybinding, preventing common misbehavior when
|
||||
using `vim` in `tmux`. This option is automatically set by [tmux-sensible][4], if
|
||||
using `vim` in `tmux`. This option is automatically set by [tmux-sensible][4], if
|
||||
you use that. The second line makes workspace numbers go from 1-10 instead of 0-9,
|
||||
which makes more sense on a keyboard where the number row starts at 1. However,
|
||||
`tilish` explicitly checks this setting when mapping keys, and works fine without it.
|
||||
|
|
@ -139,36 +139,57 @@ NOTE: a bunch of the following keys can be overridden through the options (see b
|
|||
| <kbd>Alt</kbd> + <kbd>Shift</kbd> + <kbd>e</kbd> | Exit (detach) `tmux` |
|
||||
| <kbd>Alt</kbd> + <kbd>Shift</kbd> + <kbd>c</kbd> | Reload config |
|
||||
|
||||
The <kbd>Alt</kbd> + <kbd>0</kbd> and <kbd>Alt</kbd> + <kbd>Shift</kbd> + <kbd>0</kbd>
|
||||
The <kbd>Alt</kbd> + <kbd>0</kbd> and <kbd>Alt</kbd> + <kbd>Shift</kbd> + <kbd>0</kbd>
|
||||
bindings are "smart": depending on `base-index`, they either act on workspace 0 or 10.
|
||||
|
||||
The following options can be used to override some keys mentioned in the above table (if they're not
|
||||
set, the default value will be used):
|
||||
- `set -g @tilish-split_vsplit "..."` (default <kbd>s</kbd>)
|
||||
- `set -g @tilish-split_only "..."` (default <kbd>S</kbd>)
|
||||
- `set -g @tilish-vsplit_split "..."` (default <kbd>v</kbd>)
|
||||
- `set -g @tilish-vsplit_only "..."` (default <kbd>V</kbd>)
|
||||
- `set -g @tilish-tiled "..."` (default <kbd>t</kbd>)
|
||||
- `set -g @tilish-zoom "..."` (default <kbd>z</kbd>)
|
||||
- `set -g @tilish-refresh "..."` (default <kbd>r</kbd>)
|
||||
- `set -g @tilish-rename "..."` (default <kbd>n</kbd>)
|
||||
|
||||
The keybindings that move panes between workspaces assume a US keyboard layout.
|
||||
However, you can configure `tilish` for international keyboards by providing a string
|
||||
`@tilish-shiftnum` prepared by pressing <kbd>Shift</kbd> +
|
||||
<kbd>1</kbd><kbd>2</kbd><kbd>3</kbd><kbd>4</kbd><kbd>5</kbd><kbd>6</kbd><kbd>7</kbd><kbd>8</kbd><kbd>9</kbd><kbd>0</kbd>.
|
||||
`@tilish-shiftnum` prepared by pressing <kbd>Shift</kbd> +
|
||||
<kbd>1</kbd><kbd>2</kbd><kbd>3</kbd><kbd>4</kbd><kbd>5</kbd><kbd>6</kbd><kbd>7</kbd><kbd>8</kbd><kbd>9</kbd><kbd>0</kbd>.
|
||||
For instance, for a UK keyboard, you would configure it as follows:
|
||||
|
||||
set -g @tilish-shiftnum '!"£$%^&*()'
|
||||
|
||||
Your terminal must support sending keycodes like `M-£` for the above to work.
|
||||
For instance, a UK keyboard layout works fine on `urxvt`, but does not work
|
||||
For instance, a UK keyboard layout works fine on `urxvt`, but does not work
|
||||
by default on `kitty` or `alacritty`, which may require additional configuration.
|
||||
|
||||
### Auto-refresh hooks
|
||||
|
||||
By default, we set hooks to auto-refresh the window layout when a pane is created/deleted. The setting can be controlled using
|
||||
`@tilish-refresh_hooks`. It's a 2-character (default is `'yy'`):
|
||||
- First character enables/disables auto-refreshing after a pane is created (`after-split-window`)
|
||||
- Second character enables/disables auto-refreshing after a pane is deleted (`pane-exited`)
|
||||
|
||||
So, for example, to disable the hooks, we would do something like this:
|
||||
|
||||
set -g @tilish-refresh_hooks 'nn'
|
||||
|
||||
### Layout keys
|
||||
|
||||
We use some keys to manipulate the window layout. The setting is controlled through the option `@tilish-layout_keys`,
|
||||
where the default value is `sSvVtz`, representing the following:
|
||||
- First character (<kbd>s</kbd>) is used to switch to layout `main-horizontal`
|
||||
- Second character (<kbd>S</kbd>) is used to switch to layout `even-vertical`
|
||||
- Third character (<kbd>v</kbd>) is used to switch to layout `main-vertical`
|
||||
- Fourth character (<kbd>V</kbd>) is used to switch to layout `even-horizontal`
|
||||
- Fifth character (<kbd>t</kbd>) is used to switch to layout `tiled`
|
||||
- Sixth character (<kbd>z</kbd>) is used to switch to layout `zoom`
|
||||
|
||||
In order to override a key, you need to specify the complete string and only change the ones you desire. For example,
|
||||
to use <kbd>i</kbd> and <kbd>I</kbd> instead of <kbd>v</kbd> and <kbd>V</kbd>, respectively, we would do something like this:
|
||||
|
||||
set -g @tilish-layout_keys 'sSiItz'
|
||||
|
||||
## Easy mode
|
||||
|
||||
To make the plugin more accessible for people who do not use `vim` as well,
|
||||
there is also an "easy mode" available, which uses arrow keys instead of
|
||||
there is also an "easy mode" available, which uses arrow keys instead of
|
||||
the `vim`-style <kbd>h</kbd><kbd>j</kbd><kbd>k</kbd><kbd>l</kbd> keys.
|
||||
This mode can be activated by putting this in your `tmux.conf`:
|
||||
|
||||
|
|
@ -183,8 +204,8 @@ The revised keybindings for the pane focus and movement then become:
|
|||
|
||||
## Prefix mode
|
||||
Note that this feature is currently only available in `tmux` v2.4+.
|
||||
The "prefix mode" uses a prefix key instead of <kbd>Alt</kbd>, and
|
||||
may be particularly interesting for users of editors like `kak` and
|
||||
The "prefix mode" uses a prefix key instead of <kbd>Alt</kbd>, and
|
||||
may be particularly interesting for users of editors like `kak` and
|
||||
`emacs` that use <kbd>Alt</kbd> key a lot. To activate this mode, you
|
||||
define a prefix keybinding in your `tmux.conf`. For instance, to use
|
||||
<kbd>Alt</kbd> + <kbd>Space</kbd> as your `tilish` prefix, add:
|
||||
|
|
@ -192,9 +213,9 @@ define a prefix keybinding in your `tmux.conf`. For instance, to use
|
|||
set -g @tilish-prefix 'M-space'
|
||||
|
||||
Actions that would usually be done by <kbd>Alt</kbd> + <kbd>key</kbd>
|
||||
are now accomplished by pressing the prefix and then <kbd>key</kbd>.
|
||||
are now accomplished by pressing the prefix and then <kbd>key</kbd>.
|
||||
For example, opening a split is usually <kbd>Alt</kbd> + <kbd>Enter</kbd>,
|
||||
but with the above prefix this becomes <kbd>Alt</kbd> + <kbd>Space</kbd>
|
||||
but with the above prefix this becomes <kbd>Alt</kbd> + <kbd>Space</kbd>
|
||||
then <kbd>Enter</kbd>. Note that the `tilish` prefix is different from
|
||||
the `tmux` prefix, and should generally be bound to a different key.
|
||||
For the prefix key, you can choose basically any keybinding that `tmux`
|
||||
|
|
@ -202,7 +223,7 @@ supports, e.g. `F12` or `C-s` or anything else you may prefer.
|
|||
|
||||
All these keybindings are `repeat`'able, so you do not have to press the
|
||||
prefix key again if you type multiple commands fast enough. Thus, pressing
|
||||
<kbd>Alt</kbd> + <kbd>Space</kbd> followed by <kbd>h</kbd><kbd>j</kbd> would
|
||||
<kbd>Alt</kbd> + <kbd>Space</kbd> followed by <kbd>h</kbd><kbd>j</kbd> would
|
||||
move to the left and then down, without requiring another prefix activation.
|
||||
The `tmux` option `repeat-time` can be used to customize this timeout.
|
||||
Personally, I find the default 500ms timeout somewhat short, and would
|
||||
|
|
@ -214,15 +235,15 @@ recommend that you increase this to at least a second if you use `tilish`:
|
|||
|
||||
In `i3wm`, the keybinding <kbd>Alt</kbd>+<kbd>d</kbd> is by default mapped to
|
||||
the application launcher `dmenu`, which can be practical to quickly open apps.
|
||||
If you have [`fzf`][5] available on your system, `tilish` can offer a similar
|
||||
application launcher using the same keyboard shortcut. To enable this
|
||||
If you have [`fzf`][5] available on your system, `tilish` can offer a similar
|
||||
application launcher using the same keyboard shortcut. To enable this
|
||||
functionality, add the following to your `~/.tmux.conf`:
|
||||
|
||||
set -g @tilish-dmenu 'on'
|
||||
|
||||
Basically, pressing <kbd>Alt</kbd>+<kbd>d</kbd> will then pop up a split
|
||||
that lets you fuzzy-search through all executables in your system `$PATH`.
|
||||
Selecting an executable runs the command in that split. When you want
|
||||
Selecting an executable runs the command in that split. When you want
|
||||
to start an interactive process, this can be more convenient than
|
||||
using <kbd>Alt</kbd>+<kbd>Enter</kbd> and typing the command name.
|
||||
This is currently only available in `tmux` v2.7+.
|
||||
|
|
@ -259,18 +280,18 @@ for a proposed solution.
|
|||
|
||||
## Usage inside i3wm
|
||||
|
||||
If you use `tilish` inside `i3wm` or `sway`, keybindings like
|
||||
If you use `tilish` inside `i3wm` or `sway`, keybindings like
|
||||
<kbd>Alt</kbd>+<kbd>Enter</kbd> may spawn a new terminal in your window manager
|
||||
instead of a new terminal pane inside `tmux`. The window manager always takes
|
||||
priority — so if both `i3wm` and `tilish` define the same keybinding,
|
||||
`i3wm` will intercept the keybinding before `tmux` sees it.
|
||||
|
||||
The best way to solve this is perhaps to change your window manager modifier key
|
||||
to <kbd>Super</kbd>, also known as the "Windows key". As described
|
||||
to <kbd>Super</kbd>, also known as the "Windows key". As described
|
||||
[in the `i3wm` user guide](https://i3wm.org/docs/userguide.html#_using_i3), this can
|
||||
be done by changing `$mod` to `Mod4` in your `i3wm` config. That way, pressing e.g.
|
||||
<kbd>Alt</kbd>+<kbd>Enter</kbd> opens a new terminal pane inside `tmux`, while
|
||||
<kbd>Super</kbd>+<kbd>Enter</kbd> opens a new terminal in `i3wm`.
|
||||
<kbd>Super</kbd>+<kbd>Enter</kbd> opens a new terminal in `i3wm`.
|
||||
|
||||
Alternatively, `tilish` also supports a [Prefix mode](#prefix-mode). This is in my opinion
|
||||
less ergonomic than the default `tilish` keybindings. However, it does not require the use
|
||||
|
|
@ -296,14 +317,14 @@ Thus a full working minimal example of a `tpm`-based `tmux.conf` would be:
|
|||
set -g @plugin 'tmux-plugins/tmux-sensible'
|
||||
set -g @plugin 'jabirali/tmux-tilish'
|
||||
set -g @plugin 'sunaku/tmux-navigate'
|
||||
|
||||
|
||||
# Plugin options.
|
||||
set -g @tilish-navigate 'on'
|
||||
|
||||
|
||||
# Install `tpm` if needed.
|
||||
if "test ! -d ~/.tmux/plugins/tpm" \
|
||||
"run 'git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm && ~/.tmux/plugins/tpm/bin/install_plugins'"
|
||||
|
||||
|
||||
# Activate the plugins.
|
||||
run -b "~/.tmux/plugins/tpm/tpm"
|
||||
|
||||
|
|
@ -315,7 +336,7 @@ the accompanying `vim` plugin; see [their website for more information][10].
|
|||
|
||||
### Navigator
|
||||
|
||||
To install `vim-tmux-navigator`, you should first install the plugin for `vim`
|
||||
To install `vim-tmux-navigator`, you should first install the plugin for `vim`
|
||||
or `nvim`, as described on [their website][3]. Then place this in your
|
||||
`~/.config/nvim/init.vim` (`nvim`) or `~/.vimrc` (`vim`):
|
||||
|
||||
|
|
@ -334,14 +355,14 @@ A minimal working example of a `~/.tmux.conf` with `tpm` would then be:
|
|||
set -g @plugin 'tmux-plugins/tpm'
|
||||
set -g @plugin 'tmux-plugins/tmux-sensible'
|
||||
set -g @plugin 'jabirali/tmux-tilish'
|
||||
|
||||
|
||||
# Plugin options.
|
||||
set -g @tilish-navigator 'on'
|
||||
|
||||
|
||||
# Install `tpm` if needed.
|
||||
if "test ! -d ~/.tmux/plugins/tpm" \
|
||||
"run 'git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm && ~/.tmux/plugins/tpm/bin/install_plugins'"
|
||||
|
||||
|
||||
# Activate the plugins.
|
||||
run -b "~/.tmux/plugins/tpm/tpm"
|
||||
|
||||
|
|
|
|||
31
tilish.tmux
31
tilish.tmux
|
|
@ -21,7 +21,7 @@
|
|||
# Read user options.
|
||||
for opt in \
|
||||
default dmenu easymode enforce navigate navigator prefix shiftnum \
|
||||
split_vsplit split_only vsplit_split vsplit_only tiled zoom refresh rename
|
||||
layout_keys refresh rename
|
||||
do
|
||||
export "$opt"="$(tmux show-option -gv @tilish-"$opt" 2>/dev/null)"
|
||||
done
|
||||
|
|
@ -32,14 +32,15 @@
|
|||
shiftnum='!@#$%^&*()'
|
||||
fi
|
||||
|
||||
if [ -z "$split_vsplit" ]; then split_vsplit="s" ; fi
|
||||
if [ -z "$split_only" ]; then split_only="S" ; fi
|
||||
if [ -z "$vsplit_split" ]; then vsplit_split="v" ; fi
|
||||
if [ -z "$vsplit_only" ]; then vsplit_only="V" ; fi
|
||||
if [ -z "$tiled" ]; then tiled="t" ; fi
|
||||
if [ -z "$zoom" ]; then zoom="z" ; fi
|
||||
if [ -z "$refresh" ]; then refresh="r" ; fi
|
||||
if [ -z "$rename" ]; then rename="n" ; fi
|
||||
# Default keys for changing layouts.
|
||||
if [ -z "$layout_keys" ]
|
||||
then
|
||||
layout_keys='sSvVtz'
|
||||
fi
|
||||
|
||||
# Miscellaneous keys.
|
||||
if [ -z "$refresh" ]; then refresh="r"; fi
|
||||
if [ -z "$rename" ]; then rename="n" ; fi
|
||||
|
||||
# Determine "arrow types".
|
||||
if [ "${easymode:-}" = "on" ]
|
||||
|
|
@ -165,12 +166,12 @@ fi
|
|||
# The keys can be overridden, but the default mnemonics are
|
||||
# `s` and `S` for layouts Vim would generate with `:split`, and `v` and `V` for `:vsplit`.
|
||||
# The remaining mappings based on `z` and `t` should be quite obvious.
|
||||
bind_layout "${mod}${split_vsplit}" 'main-horizontal'
|
||||
bind_layout "${mod}${split_only}" 'even-vertical'
|
||||
bind_layout "${mod}${vsplit_split}" 'main-vertical'
|
||||
bind_layout "${mod}${vsplit_only}" 'even-horizontal'
|
||||
bind_layout "${mod}${tiled}" 'tiled'
|
||||
bind_layout "${mod}${zoom}" 'zoom'
|
||||
bind_layout "${mod}$(char_at $layout_keys 1)" 'main-horizontal'
|
||||
bind_layout "${mod}$(char_at $layout_keys 2)" 'even-vertical'
|
||||
bind_layout "${mod}$(char_at $layout_keys 3)" 'main-vertical'
|
||||
bind_layout "${mod}$(char_at $layout_keys 4)" 'even-horizontal'
|
||||
bind_layout "${mod}$(char_at $layout_keys 5)" 'tiled'
|
||||
bind_layout "${mod}$(char_at $layout_keys 6)" 'zoom'
|
||||
|
||||
# Refresh the current layout (e.g. after deleting a pane).
|
||||
if [ -z "$legacy" ]
|
||||
|
|
|
|||
Loading…
Reference in a new issue