# LibTmux.Pane.split/3

- **Module:** LibTmux
- **Package:** libtmux
- **Language:** Elixir
- **Kind:** function
- **Source:** https://github.com/libtmux/libtmux-elixir/blob/66b9b1c3f3f3186428abdfda2c76f5cf87446710/lib/libtmux/entities.ex#L266
- **Page:** https://libtmux.org/en/elixir/latest/reference/libtmux-pane-split-3/

```
split(connection, ref, options \\ [])
@spec split(LibTmux.Action.connection(), LibTmux.Ref.t(), [
        split_option()
      ]) ::
        {:ok, LibTmux.Action.result(split_value())}
        | {:error, LibTmux.Action.error()}
```

Splits an exact pane and returns its ID and optional bound reference as `value`.

A completed value contains `id` and `ref`. Qualified control binds the reference.
Use it for another action without recapturing. It identifies the pane in
that server incarnation, contains no fresh fields and does not reserve its
lifetime. Closing the connection does not invalidate the reference while
the pane and server remain. One-shot execution does not establish this
binding and returns `ref: nil`. Unsuccessful split results have `value: nil`.

Defaults: vertical split, half size, detached, after the target, and tmux's
session default shell/command and directory. `axis: :horizontal` places panes
side by side; `size: {:percent, n}` uses `-l n%` on every supported release.
Optional `cwd` is literal format text. Choose `command: :default`, `:empty`,
`{:shell, nonempty_bytes}` or `{:argv, [program | arguments]}`. Shell text
uses the session's configured shell; argv uses `execvp` semantics, including
PATH lookup and executable-text fallback. Empty argv/program and empty
explicit shell text are rejected. At most 64 argv entries and the existing
command byte bounds apply; bytes must be NUL-free.

Singleton argv uses the packaged helper to preserve exactly one argument.
It replaces itself with the pane program. tmux retains the helper path in
[`pane_start_command`](/en/tmux/latest/catalog/formats/pane_start_command/); commandless respawn requires that installation to
remain available. See [command forms](one-shot-actions.html#command-forms).
Split acknowledgement does not prove program startup or completion.

`session: session_ref` selects exact membership/context, not a WindowLink
index. `timeout` defaults to 5000ms. No snapshot is changed; capture again
when a new observation is needed. See `LibTmux.Action` for outcomes and the
one-shot identity check/use limitation.

    alias LibTmux.Pane

    {:ok, %{outcome: :completed, value: %{ref: created}}} =
      Pane.split(control, pane_ref, axis: :horizontal, size: {:percent, 30})
    Pane.send_text(control, created, "hello")

## Parameters

- `connection` (`LibTmux.Action.connection()`)
- `ref` (`LibTmux.Ref.t()`)
- `options` (`[split_option()]`)