diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 137 |
1 files changed, 137 insertions, 0 deletions
@@ -0,0 +1,137 @@ +tilemux +======= +An i3-like tiling layer for tmux, in a single config file. No plugins, no +helper scripts, no dependencies. Design target is tmux 3.6. + +Windows are workspaces, panes are tiles, and every binding is on Alt so +no prefix is needed. Ctrl+Space is kept as the tmux prefix so nothing is +out of reach. + + +Install +------- + cp tilemux.conf ~/.tilemux.conf + +Then add an alias to your shell rc: + + alias tilemux='tmux -L tilemux -f ~/.tilemux.conf' + + tilemux new -A -s main start it, or attach if already running + tilemux ls list sessions + tilemux kill-server stop it + +tilemux runs on its own socket, so it has its own server and its own +sessions and the tmux you already use is untouched. The socket is what +does the isolating: -f is read only when a server starts, so on its own +it would be ignored by an already running tmux. + +Alt+? lists every key. The rules are commented in tilemux.conf next to +the bindings that implement them, so this file only shows what they do. + + +The model +--------- +tmux keeps a layout as a tree but exposes only pane geometry to its +formats, so the bindings work to one explicit model instead: + + a window is a row of columns, and each column is a stack of panes + +Alt+Shift+Left/Right moves a pane between columns. It leaves its own +column and joins the neighbouring one: + + +----+----+ +----+----+ + | a | C | | | a | + +----+----+ -> | +----+ + | B | D | | B | C | + +----+----+ | +----+ + | | D | + +----+----+ + +Alt+Shift+Up/Down reorders a pane inside the column it is already in: + + +----+----+ +----+----+ + | a | C | | B | C | + +----+----+ -> +----+----+ + | B | D | | a | D | + +----+----+ +----+----+ + +At the edge of the window there is no neighbour to move to, so the pane +leaves its column and becomes a column of its own, or a full-width row +going up or down. This is how a layout is restructured without presets: + + +----+----+ +--+--+----+ + | A | C | |A | | | + +----+----+ -> +--+ C| d | + | B | d | |B | | | + +----+----+ +--+--+----+ + +Alt+m and a direction is the way back in. Moving pushes panes apart, and +a pane that is a whole column swaps with its neighbours instead of +joining them, so merging needs a key of its own: + + +---+---+---+ +---+-------+ + | | | | | | B | + | A | B | c | -> | A +-------+ + | | | | | | c | + +---+---+---+ +---+-------+ + + +Debugging +--------- +Reload, then look at what a key runs and what the rules are reading: + + tilemux source-file ~/.tilemux.conf + tilemux list-keys -T root | grep 'M-L' + tilemux display -p '#{window_layout}' + tilemux list-panes -F '#{pane_index} #{pane_left},#{pane_top}' + +Watch for #{>:a,b}: it compares strings. Numbers need #{e|>:a,b}. + +To try a binding without disturbing the tmux you work in, run a second +server on its own socket and attach to it from a pane of the first. +send-keys writes to that pane, so the attached client reads the keys and +the binding fires: + + tmux -L test -f ./tilemux.conf new-session -d -s w -x 200 -y 48 + tmux -L ctl -f /dev/null new-session -d -x 200 -y 49 \ + 'tmux -L test attach -t w' + tmux -L test split-window -h + tmux -L test select-pane -t 1 + tmux -L ctl send-keys -t 0 M-L + tmux -L test list-panes -F '#{pane_index} #{pane_left} #{pane_active}' + tmux -L test kill-server + +Killing the test server ends the attach, and the ctl server with it. + + +Caveats +------- +A 2x2 built as columns of rows and one built as rows of columns look +identical on screen. Geometry cannot tell them apart, so both behave as +columns of rows. + +A pane that spans the window swaps with a neighbour instead of pushing +past it, and tmux picks which neighbour by geometry, so a full-height +column can trade places with one pane of the stack beside it. Alt+m +puts it back. + +A pane leaving a stack does not make the rest rebalance; the neighbour +absorbs the space, as it does when a pane is killed. Alt+r then = evens +a container out. + +Copy mode has its own key table. With the default emacs mode-keys it +takes seventeen of these keys for itself: Alt+1 to Alt+9, Alt+Up, +Alt+Down, Alt+b, Alt+f, Alt+l, Alt+m, Alt+r and Alt+v. Those do not +reach tilemux while a pane is in copy mode, and every other key falls +through and works. setw -g mode-keys vi avoids the clash entirely. + +Alt+? needs a terminal of at least 76x23. Below that tmux refuses the +popup and says so in the status line; there is no smaller help. + +Alt+Shift with a number assumes the shifted symbols of a US layout +(!@#$%^&*()). + + +License +------- +BSD 3-Clause. See LICENSE. |