Pane.split
Split this pane, putting a new one beside it.
Source and package
-
Description#
Window::split()divides whichever pane is active; this divides the one you name, which is what building a layout needs.Errors
Returns an error when tmux refuses the split, which includes a pane too small to divide.
Examples#
use libtmux::{PaneSize, SplitDirection, SplitOptions};let session = server.new_session("split-from-pane").await?;let pane = session.panes().await?.remove(0);let above = pane.split(SplitOptions::new(SplitDirection::Above).size(PaneSize::Percent(30)).command("sleep 300"),).await?;assert_ne!(above.id(), pane.id());assert_eq!(above.window_id(), pane.window_id());Create windows and split panes. Create a session and a second window, then split from a window and from a pane. Use Rust 1.85 or newer with Cargo, and tmux 3.3a or newer, on a Unix system. In an empty directory, create a project and add the published crates:
Terminal window $ cargo init --name libtmux-api-example &&cargo add libtmux@0.1.2 tempfile@3.20 &&cargo add tokio@1.40 --features macros,rt,timeReplace
src/main.rswith this complete program. It owns a private tmux socket, applies a ten-second task deadline, and reports both task and cleanup errors.Server::kill()stops its daemon;Server::shutdown()closes its client executor. Successful cleanup removes the temporary directory even when the task fails. View source//! Create a session and window, then split a window and a pane.use std::error::Error;use std::time::Duration;use libtmux::{NewSessionOptions, NewWindowOptions, Server, SplitDirection, SplitOptions};type ExampleError = Box<dyn Error>;fn check(condition: bool, message: &str) -> Result<(), ExampleError> {if condition {Ok(())} else {Err(message.into())}}async fn demonstrate(server: &Server) -> Result<(), ExampleError> {let session = server.new_session(NewSessionOptions::new("work").window_name("editor").command("cat"),).await?;let window = session.new_window(NewWindowOptions::new("logs").command("cat")).await?;let pane = window.split(SplitOptions::new(SplitDirection::Below).command("cat")).await?;pane.split(SplitOptions::new(SplitDirection::Right).command("cat")).await?;check(session.windows().await?.len() == 2,"expected two session windows",)?;check(window.panes().await?.len() == 3,"expected three panes in split window",)?;check(server.panes().await?.len() == 4,"expected four panes on server",)?;println!("creation: 2 windows, 4 panes");Ok(())}#[tokio::main(flavor = "current_thread")]async fn main() -> Result<(), ExampleError> {let root = std::path::Path::new("/tmp/libtmux-rs-dev");std::fs::create_dir_all(root)?;let directory = tempfile::Builder::new().prefix("api-creation-").tempdir_in(root)?;std::fs::write(directory.path().join("owner"),std::process::id().to_string(),)?;let server = Server::builder().socket_path(directory.path().join("tmux.sock")).config_file("/dev/null").default_timeout(Duration::from_secs(5)).build()?;let outcome = tokio::time::timeout(Duration::from_secs(10), demonstrate(&server)).await;// Stop the owned daemon before closing the client executor.let killed = server.kill().await;let closed = server.shutdown().await;let cleanup_failed = killed.is_err() || closed.is_err();let mut failures = Vec::new();match outcome {Ok(Ok(())) => {}Ok(Err(error)) => failures.push(format!("example failed: {error}")),Err(error) => failures.push(format!("example deadline: {error}")),}if let Err(error) = killed {failures.push(format!("daemon cleanup: {error}"));}if let Err(error) = closed {failures.push(format!("executor cleanup: {error}"));}if cleanup_failed {let retained = directory.keep();failures.push(format!("inspect retained directory {}", retained.display()));} else if let Err(error) = directory.close() {failures.push(format!("directory cleanup: {error}"));}if failures.is_empty() {Ok(())} else {Err(failures.join("; ").into())}}Run the consumer. Success exits with status 0; setup, operation, deadline or cleanup failures exit unsuccessfully and print diagnostics to stderr:
Terminal window $ cargo run --quietExpected output:
creation: 2 windows, 4 panes- Parameters
-
-
options(impl Into<crate::Split >) #Options
-
tmux command#
The tmux commands behind split.
tmux C API#
The C declarations in tmux that implement these commands.
Each path starts at a function a command runs, which is degree 1. The degree counts steps from there along the path, and each step is a call or a reference: degree 2 is reached from that function, degree 3 from the next, and so on.
Split a window
- 1
cmd_split_window_exec - references → 2
spawn_pane - calls → 3
window_add_pane - calls → 4
window_pane_create
In other ports#
Split a pane in two
| Language | Equivalent |
|---|---|
| Python | libtmux |
| Ruby | Lib |
| Lua | libtmux |
| Erlang | tmux |
| Haskell | No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing. |
| TypeScript | pane |
| Go | tmux |
| Java | io |
| Clojure | libtmux |
| Kotlin | io |
| Scala | io |
| C# | Lib |
| C++ | no direct pane target; Window.split splits the active pane |
| Swift | Server |
| OCaml | Libtmux |
| Perl | Lib Explicit Server operation. Captured entities remain local observations; use a new snapshot to observe changes. |
No equivalent is recorded in PowerShell, Julia, Elixir, Common Lisp or F#.