How to move a tmux pane with relative targets?
Short answer
tmux join-pane -h -s '{down-of}' # pane below -> split to the RIGHT of the active pane
tmux join-pane -bh -s '{down-of}' # same, inserted to the LEFT instead{down-of} resolves to the pane just below the active one, so there is no index or pane id to
look up: join-pane breaks that pane out of its slot and re-attaches it beside the active pane.
A stacked pair becomes a side-by-side pair in one command.
Details
The full set of relative pane targets: {up-of}, {down-of}, {left-of} and {right-of} are
the neighbours of the active pane; {top}, {bottom}, {left} and {right} are the panes at
the window edges; {next} and {previous} walk the panes in index order; {last} is the
previously active pane. They work anywhere a command expects a pane target, so select-pane,
swap-pane and resize-pane take them too.
Quote them: { and } mean something to the shell.
Directional targets wrap around the window edge, like moving the focus with select-pane -D
does: from the bottom pane of a stack, {down-of} is the top pane again. And when no pane lies
in that direction at all, the command fails with can't find pane instead of guessing. Both
make these targets safer in scripts than a bare pane number, which silently flips between
meaning a pane and a window depending on the current layout.
Note that join-pane reshapes the layout: the source pane leaves its slot and a new split is
created. To make two panes trade places without changing the layout, the command is
swap-pane, which accepts the same targets.
Verified on tmux 3.2a.