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.

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.

-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

Same as -t -s -c 'ssh -o StrictHostKeyChecking=no {}'.

--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 tmux command. Default value is tmux.

TMUX_XPANES_LOG_DIRECTORY

Path to which log files generated by --log option are stored. Default value is $HOME/.cache/xpanes/logs.

TMUX_XPANES_LOG_FORMAT

Format of the log file name generated by --log option. Default value is [:ARG:].log.%Y-%m-%d_%H-%M-%S.

TMUX_XPANES_PANE_BORDER_FORMAT

Defines the format of pane title used in -t option. 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 -s option 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.

  1. xpanes's argument will be the common command line which will be used within all panes (this is same as the -c option's argument in Normal mode).
  2. Each line provided by standard input is corresponding to the each pane's command line (this is corresponding to normal argument of xpanes in 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

xpanes -s -c "seq {}" 2 3 4 5

+-------------------------------+-------------------------------+
|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

tmux(1)

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).

MAR 2023