Skip to content

pane:split{}

Since: Version 20220624-141144-bd1b7c5d

The functionality described in this section requires version 20220624-141144-bd1b7c5d of wezterm, or a more recent version.

Splits pane and spawns a program into the split, returning the Pane object associated with it:

local new_pane = pane:split {}

When no arguments are passed, the pane is split in half left/right and the right half has the default program spawned into it.

The following parameters are supported:

args

Specifies the argument array for the command that should be spawned. If omitted the default program for the domain will be spawned.

pane:split { args = { 'top' } }

cwd

Specify the current working directory that should be used for the program.

If unspecified, follows the rules from default_cwd

pane:split { cwd = '/tmp' }

set_environment_variables

Sets additional environment variables in the environment for this command invocation.

pane:split { set_environment_variables = { FOO = 'BAR' } }

domain

Specifies the multiplexer domain into which the program should be spawned. The default value is assumed to be "CurrentPaneDomain", which causes the default domain to be used.

You may specify the name of one of the multiplexer domains defined in your configuration using the following:

pane:split { domain = { DomainName = 'my.name' } }

Or you may use the default domain:

pane:split { domain = 'DefaultDomain' }

direction

Specifies where the new pane should be placed. Possible values are:

  • "Right" - splits the pane left/right and places the new pane on the right.
  • "Left" - splits the pane left/right and places the new pane on the left.
  • "Top" - splits the pane top/bottom and places the new pane on the top.
  • "Bottom" - splits the pane top/bottom and places the new pane on the bottom.
pane:split { direction = 'Top' }

top_level

If true, rather than splitting pane in half, the tab that contains it is split and the new pane runs the full extent of the tab dimensions.

pane:split { direction = 'Bottom', top_level = true }

size

Controls the size of the new pane.

Numeric values less than 1.0 are used to express a fraction of the available space; 0.5 means 50% of the available space, for example.

Numeric values greater or equal to 1 are used to specify the number of cells.

The default value is 0.5.

This creates two additional splits within pane, creating three total splits that each occupy 1/3 of the available space:

pane:split { direction = 'Top', size = 0.333 }
pane:split { direction = 'Top', size = 0.5 }