Tmux

How to join panes in tmux?

Quick Answer

To join panes in tmux, use Ctrl+b : followed by join-pane -s source_pane -t target_pane. The source pane will be moved and attached to the target pane's window. You can also use join-pane -s window_name.pane_index or join-pane -s session_name:window_name.pane_index for specific panes.

join-pane -s :2.1 -t :1

Detailed Explanation

The join-pane command (sometimes abbreviated as joinp) allows you to move a pane from one window to another, combining windows or reorganizing your workspace. This is particularly useful for bringing related content together or cleaning up your tmux session.

Basic Join-Pane Command

# Basic syntax
join-pane -s SOURCE -t TARGET

# Join using window and pane indices
join-pane -s :2.1 -t :1

# Join a pane from another session
join-pane -s session2:2.1 -t :1

The command takes two main parameters:

-s SOURCE: Specifies the source pane to be moved
-t TARGET: Specifies the target window or pane where the source will be attached

By default, the source pane will be added as a vertical split to the target window.

Identifying Panes and Windows

To use join-pane effectively, you need to identify panes correctly. Tmux uses this format:

# Format: session_name:window_index.pane_index
my_session:2.1    # Pane 1 of window 2 in session "my_session"
:2.1              # Pane 1 of window 2 in the current session
.1                # Pane 1 in the current window

To find the indices of your panes, you can use:

# Show all windows and panes in the current session
Ctrl+b :display-panes

# Show detailed info about panes
Ctrl+b :list-panes

Join-Pane Options

The join-pane command accepts several useful options:

# Join horizontally (side by side)
join-pane -h -s :2.1 -t :1

# Join vertically (one above the other)
join-pane -v -s :2.1 -t :1

# Join and specify the size (percentage of the window)
join-pane -p 25 -s :2.1 -t :1

# Join before the target pane
join-pane -b -s :2.1 -t :1

-h: Join horizontally (side by side)
-v: Join vertically (one above the other)
-p SIZE: Specify the size as a percentage of the window
-b: Place the joined pane before the target pane

Practical Examples

Let's look at some common use cases:

# Move the current pane to window 3
Ctrl+b :join-pane -t :3

# Bring pane 1 from window 2 to the current window
Ctrl+b :join-pane -s :2.1

# Create a 30% horizontal split with pane from another session
Ctrl+b :join-pane -h -p 30 -s othersession:1.2

# Move all panes from window 2 to window 1 (one by one)
Ctrl+b :join-pane -s :2.0 -t :1
Ctrl+b :join-pane -s :2.0 -t :1  # Repeat for each remaining pane

Note that when you don't specify a source (-s) or target (-t), tmux uses the current pane as the default.

Pro Tip

Create a custom key binding for frequently used join-pane commands:

# Add to ~/.tmux.conf
# Press Ctrl+b J to move current pane to window 1
bind J join-pane -t :1

# Press Ctrl+b M to collect all panes from window 2 into current window
bind M run-shell "for i in $(tmux list-panes -t :2 -F '#P'); do tmux join-pane -s :2.\$i; done"

Breaking Panes Out

The opposite of join-pane is break-pane, which moves a pane to its own window:

# Move current pane to a new window
Ctrl+b :break-pane

# Break pane 1 into a new window and keep focus on it
Ctrl+b :break-pane -s .1 -d

The -d flag prevents tmux from switching to the new window after the break.

←Back to FAQ Index