xpanes - Man Page
Ultimate terminal divider powered by tmux
Synopsis
Normal mode
xpanes [Options] argument ...
Pipe mode
command ... | xpanes [Options] [<utility> ...]
Description
xpanes and tmux-xpanes (alias of xpanes) commands have following features.
Split tmux window into multiple panes
- Construct command lines & execute them on the panes
- Runnable from outside of tmux session
- Runnable from inside of tmux session
- Record operation log
Flexible layout arrangement for panes
- Select layout presets
- Set columns or rows as you like
- Display pane title on each pane
- Generate command lines from standard input (Pipe mode)
Options
- -h, --help
Display the help and exit.
- -V, --version
Output version information and exit.
- -B <begin-command>
Run <begin-command> before processing <command> in each pane. Multiple options are allowed.
- -c <command>
Set <command> to be executed in each pane. Default is
echo {}.- -d, --desync
Make synchronize-panes option off in new window.
- -e
Execute given arguments as is. Same as
-c '{}'- -I <repstr>
Replacing one or more occurrences of <repstr> in command provided by -c or -B. Default is
{}.- -C NUM, --cols=NUM
Number of columns of window layout.
- -R NUM, --rows=NUM
Number of rows of window layout.
-l <layout>
Set the preset of window layout. Recognized layout arguments are:
t tiled (default)
eh even-horizontal
ev even-vertical
mh main-horizontal
mv main-vertical
- -s
Speedy mode: Run command without opening an interactive shell.
- -ss
Speedy mode AND close a pane automatically at the same time as process exiting.
- -n <number>
Set the maximum number of <argument> taken for each pane.
- -r
Reuse the existing panes, or create then in the current active window.
- -S <socket-path>
Set a full alternative path to the server socket.
- -t
Display each argument on the each pane's border as their title.
- -x
Create extra panes in the current active window.
- --log[=<directory>]
Enable logging and store log files to ~/.cache/xpanes/logs or <directory>.
- --log-format=<FORMAT>
Make name of log files follow <Format>.
- --ssh
- --stay
Do not switch to new window.
- --bulk-cols=NUM1[,NUM2 ...]
Number of columns on multiple rows (i.e, "2,2,2" represents 2 cols x 3 rows).
- --interval=<*seconds*>
Set interval between each pane creation and each command execution. sleep(1) is used for the interval.
- --debug
Print debug message.
Format
Default value is "[:ARG:].log.%Y-%m-%d_%H-%M-%S".
Interpreted sequences are:
[:PID:] Process id of the tmux session. (e.g, 41531)
[:ARG:] Argument name
In addition, sequences same as date(1) command are available.
For example:
%Y year (e.g, 1960)
%m month (e.g, 01)
%d date (e.g, 31)
And etc. Other sequences are available. Please refer to date(1) manual.
Shell Variables
- TMUX_XPANES_EXEC
Preferentially used as a internal
tmuxcommand. Default value istmux.- TMUX_XPANES_LOG_DIRECTORY
Path to which log files generated by
--logoption are stored. Default value is$HOME/.cache/xpanes/logs.- TMUX_XPANES_LOG_FORMAT
Format of the log file name generated by
--logoption. Default value is[:ARG:].log.%Y-%m-%d_%H-%M-%S.- TMUX_XPANES_PANE_BORDER_FORMAT
Defines the format of pane title used in
-toption. Default value is#[bg=green,fg=black] #T #[default]. See FORMATS section in tmux(1) for further details.- TMUX_XPANES_PANE_BORDER_STATUS
Defines location of the pane's title. See FORMATS section in tmux(1) for further details. Default value is
bottom.- TMUX_XPANES_PANE_DEAD_MESSAGE
It defines the message that displayed when a process exits with
-soption enabled.Default value is
\033[41m\033[4m\033[30m Pane is dead: Press [Enter] to exit... \033[0m\033[39m\033[49m.- TMUX_XPANES_TMUX_VERSION
It forces the tmux version recognized by
xpanes. It is mainly used for testing purposes. Default value is empty.
Modes
[Normal mode1] Outside of tmux session.
When the tmux is not open and xpanes is executed on the normal terminal, the xpanes's behavior is as follows:
- It newly creates a tmux session and new window on the session.
- In addition, it separates the window into multiple panes.
- Finally, the session will be attached.
[Normal mode2] Inside of tmux session.
When the tmux is already open and xpanes is executed on the existing tmux session, the command's behavior is as follows:
- It newly creates a window on the existing active session.
- In addition, it separates the window into multiple panes.
- Finally, the window will be active.
[Pipe mode] Inside of tmux session & Accepting standard input.
When xpanes accepts standard input (i.e, xpanes follows another command and pipe |) under Normal mode2 , xpanes's behavior is going to be the special one called "Pipe mode".
Pipe mode has two features.
xpanes's argument will be the common command line which will be used within all panes (this is same as the-coption's argument in Normal mode).- Each line provided by standard input is corresponding to the each pane's command line (this is corresponding to normal argument of
xpanesin Normal mode).
Examples
Simple example
xpanes 1 2 3 4
+-------------------------------+-------------------------------+ |$ echo 1 |$ echo 2 | |1 |2 | | | | | | | | | | | | | | | | | | | +-------------------------------+-------------------------------+ |$ echo 3 |$ echo 4 | |3 |4 | | | | | | | | | | | | | | | | | | | +-------------------------------+-------------------------------+
-c option and -I option
xpanes -I@ -c 'seq @' 1 2 3 4
+-------------------------------+-------------------------------+ |$ seq 1 |$ seq 2 | |1 |1 | | |2 | | | | | | | | | | | | | | | | +-------------------------------+-------------------------------+ |$ seq 3 |$ seq 4 | |1 |1 | |2 |2 | |3 |3 | | |4 | | | | | | | | | | +-------------------------------+-------------------------------+
Ping multiple hosts
xpanes -c "ping {}" 192.168.1.{5..8}
+-------------------------------+-------------------------------+ |$ ping 192.168.1.5 |$ ping 192.168.1.6 | | | | | | | | | | | | | | | | | | | | | | +-------------------------------+-------------------------------+ |$ ping 192.168.1.7 |$ ping 192.168.1.8 | | | | | | | | | | | | | | | | | | | | | | +-------------------------------+-------------------------------+
Run commands without opening a login shell
+-------------------------------+-------------------------------+ |1 |1 | |2 |2 | |Pane is dead: Press [Enter] to |3 | |exit... |Pane is dead: Press [Enter] to | | |exit... | | | | | | | | | | | | | | | | +-------------------------------+-------------------------------+ |1 |1 | |2 |2 | |3 |3 | |4 |4 | |Pane is dead: Press [Enter] to |5 | |exit... |Pane is dead: Press [Enter] to | | |exit... | | | | | | | | | | +-------------------------------+-------------------------------+
Display host always
xpanes -t -c "ping {}" 192.168.1.{5..8}
+-------------------------------+-------------------------------+ |$ ping 192.168.1.5 |$ ping 192.168.1.6 | | | | | | | | | | | | | | | | | | | | | | +--192.168.1.5------------------+--192.168.1.6------------------+ |$ ping 192.168.1.7 |$ ping 192.168.1.8 | | | | | | | | | | | | | | | | | | | | | | +--192.168.1.7------------------+--192.168.1.8------------------+
Use SSH without key checking
xpanes --ssh myuser1@host1 myuser2@host2
+-------------------------------+-------------------------------+ |$ ssh -o StrictHostKeyChecking |$ ssh -o StrictHostKeyChecking | |=no myuser@host1 |=no myuser@host2 | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | +-------------------------------+-------------------------------+
Create new panes on existing window
+-------------------------------+-------------------------------+ |$ |$ | | | | | | | | | | | | | | | | | | | | | | +-------------------------------+-------------------------------+ | $ xpanes -x 4 5 6 | | | | | | | | | | | | | | | +-------------------------------+-------------------------------+ +-------------------------------+-------------------------------+ |$ |$ | | | | | | | | | | | | | +-------------------------------+-------------------------------+ |$ xpanes -x 4 5 6 |$ echo 4 | |$ |4 | | |$ | | | | | | | +-------------------------------+-------------------------------+ |$ echo 5 |$ echo 6 | |5 |6 | |$ |$ | | | | | | | +-------------------------------+-------------------------------+
Execute different commands on the different panes
xpanes -e "top" "vmstat 1" "watch -n 1 free"
+-------------------------------+------------------------------+ |$ top |$ vmstat 1 | | | | | | | | | | | | | | | | | | | +-------------------------------+------------------------------+ |$ watch -n 1 free | | | | | | | | | | | | | +--------------------------------------------------------------+
Change layout of panes (using presets)
xpanes -l ev -c "{}" "top" "vmstat 1" "watch -n 1 df"
+-------------------------------------------------------------+ |$ top | | | | | | | | | +-------------------------------------------------------------+ |$ vmstat 1 | | | | | | | | | +-------------------------------------------------------------+ |$ watch -n 1 df | | | | | | | | | +-------------------------------------------------------------+
Change layout of panes (Fixed number of columns)
xpanes -C 2 AAA BBB CCC DDD EEE FFF GGG HHH III
+------------------------------+------------------------------+ |$ echo AAA |$ echo BBB | | | | | | | +------------------------------+------------------------------+ |$ echo CCC |$ echo DDD | | | | | | | +------------------------------+------------------------------+ |$ echo EEE |$ echo FFF | | | | | | | +------------------------------+------------------------------+ |$ echo GGG |$ echo HHH | | | | | | | +------------------------------+------------------------------+
Pipe mode
seq 3 | xpanes
+------------------------------+------------------------------+ |$ echo 1 |$ echo 2 | |1 |2 | | | | | | | | | | | | | | | | | | | +------------------------------+------------------------------+ |$ echo 3 | |3 | | | | | | | | | | | | | +------------------------------+------------------------------+
Pipe mode with an argument
seq 4 | xpanes seq
+-------------------------------+------------------------------+ |$ seq 1 |$ seq 2 | | | | | | | | | | | | | | | | | | | | | | +-------------------------------+------------------------------+ |$ seq 3 |$ seq 4 | | | | | | | | | | | | | | | | | | | | | | +-------------------------------+------------------------------+
See Also
Author and Copyright
Copyright (c) 2023 Yamada, Yasuhiro ⟨yamada@gr3.ie⟩ Released under the MIT License. ⟨https://github.com/greymd/tmux-xpanes⟩
Acknowledgements
Thanks to Yamada, Yuka for her awesome logo ⟨https://github.com/greymd/tmux-xpanes/wiki/Image-Library⟩.
Referenced By
The man page tmux-xpanes(1) is an alias of xpanes(1).