Session
One tmux session, together with the snapshot it was discovered with.
Source and package
-
Description#
A
Sessionis cheap to clone and shares its connection with theServerthat produced it, but owns its snapshot outright. Cloning therefore does not share observed state: refreshing one clone leaves the others as they were.Getters are synchronous because they read the owned snapshot. Anything that consults tmux is
async.What is on here
The methods on a
Sessionfall into a few groups:- Finding the session you are in
- Resolve the session this process is running in, from
TMUX_PANEor from a value you pass. Both go through the pane, reportOk(None)when tmux no longer has it, and fail when the value is absent or not a pane ID. - Reading the snapshot
- Getters are synchronous: they read the snapshot this handle owns and send nothing to tmux, so a value is as old as the snapshot. Refreshing updates this handle in place or returns a new one, leaves other handles with the snapshot they have, and fails with
Error::ObjectGoneonce the session no longer exists. With thequeryfeature, which is on by default,get()reads any snapshot field, including those with no getter. - TimesAny fieldRefresh
- Windows and panes
- List the session's windows, or every pane in it; a failed listing returns an error, not an empty list.
window()andwindow_at()reportOk(None)when nothing matches, andactive_window()does so only when the session has gone, because a session always has an active window. Moving to the next, previous or last window returns the one that became active, andOk(None)where there is none, which is not a failure;search_windows()needs thequeryfeature, which is on by default. - Find oneNarrow
- Changing things
- Create a window from
NewWindowOptionsor a bare name, or run an operation in a window that is killed afterwards. A failure to create it, to run the operation or to kill it comes back as aScopeError, and a cleanup failure carriesError::AfterEffect. If the future is dropped, the window is still killed while the Tokio runtime is alive. Renaming updates this handle and killing consumes it, so every other handle to the session goes stale; locking and detaching act on the attached clients, and detaching succeeds when none is attached. A name is sent as text, and only aTmuxArg::format()value is expanded: see [the crate documentation][crate#a-name-reaches-tmux-as-text]. - WindowsClients
- Options and hooks
- Read and set options at this session's scope: listings report what this session has set, not what it inherits, and
typed_option()readsOk(None)for an option that holds nothing here.set_typed_option()checks the value against tmux's option table before anything is sent,set_option()sends text and leaves tmux to refuse it, andOptionValuesays how the reads and writes fit together. A hook is an array option:hooks()lists only those holding something, andhook()reads one,Ok(None)when it holds nothing. - Environment
- Set variables for the processes this session starts; panes already running keep the environment they were started with. tmux can also hold a mark saying a process must not inherit a name at all, which is not the same as absence:
EnvironmentEntrykeeps value and mark apart,hide_environment()sets the mark, andunset_environment()deletes this session's own entry and lets what tmux inherited show through. A read returnsOk(None)only when tmux holds nothing under the name.
Anything tmux can do to a session that is not here is reachable through
cmd(), which runs an arbitrary command against it and hands back its result.Examples#
let guard = libtmux::test::TestServer::new().await?;let session = guard.server().new_session("work").await?;// The name is read from the snapshot this handle owns, so it costs// nothing; asking tmux for the windows is `async` because it does.assert_eq!(session.name().to_string_lossy(), "work");assert_eq!(session.windows().await?.len(), 1);guard.shutdown().await?;
Members48#
Collections and queries3#
- windows method List the windows linked into this session, preserving any failure.
- panes method List every pane in this session, preserving any failure.
- search_windows method The windows under this session that a matcher accepts, reporting why if the listing fails.
Common operations37#
- new_window method Create a window in this session and return it.
- kill method Kill the session.
- rename method Rename the session and update this handle.
- hooks method Read every hook set at this session.
- id method Return the tmux session identity.
- name method Return the session name.
- is_attached method Report whether any client is attached.
- options method Read every option set at this session, decoded by its declared kind.
- set_option method Set one option to text, unchecked.
- unset_option method Remove one option, restoring whatever it inherits.
- set_hook method Set one hook to a tmux command.
- environment method Read one variable from the session's environment.
- set_environment method Set an environment variable for processes this session starts.
- unset_environment method Remove an environment variable from the session.
- typed_option method Read one option, decoded according to what tmux declares about it.
- created method Return when the session was created.
- detach_clients method Detach every client attached to this session.
- active_window method Return the session's active window.
- unset_hook method Remove one hook.
- refresh method Replace this handle's snapshot with the session's current state.
- next_window method Move to the next window, and return it.
- previous_window method Move to the previous window, and return it.
- last_window method Move to the window that was active before this one, and return it.
- window_count method Return how many windows the session contains.
- path method Return the session's working directory.
- cmd method Run a raw tmux command against this session.
- from_env method Find the session this process is running in.
- lock method Lock every client attached to this session.
- set_hooks method Write a whole hook at once.
- last_attached method Return when a client last attached.
- environment_all method Read the session's whole environment.
- refreshed method Return a new handle holding the session's current state.
- format method Expand a tmux format string in this session's context.
- get method Read one field of this session's snapshot, named by the handle that filters it.
- hide_environment method Hide a variable from processes started in this session.
- hook method Read one hook's commands, or
Nonewhen it holds nothing. - set_typed_option method Set one option to a typed value, checked before it is sent.
Other members8#
- append_option method Append to one option rather than replacing it.
- attached_client_count method Return how many clients are attached to the session.
- display method Show a message on the clients viewing this session.
- from_env_value method Find a session from an explicit
TMUX_PANEvalue. - option_names method List the option names set at this session's scope.
- window method Find this session's window with the given name.
- window_at method Find this session's window at the given index.
- with_window method Create a window, run an operation with it, then kill it.
Guides#
Pages that discuss Session.
- Topics
In other ports#
A tmux session
| Language | Equivalent |
|---|---|
| Python | libtmux |
| Ruby | Lib |
| Lua | libtmux |
| PowerShell | Lib This cmdlet reads and returns shared .NET LibTmux.Session objects. Child windows and panes require further acquisition. |
| Julia | Lib SessionSnapshot holds captured session data. Actions use its SessionRef, a typed identity bound to an observed daemon generation. |
| Erlang | #tmux |
| Elixir | Lib Session is an immutable observation. Fields not captured read as :unloaded. |
| Haskell | No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing. |
| Common Lisp | libtmux: session is an immutable captured entity. The same name also has a relation accessor with a distinct public identity. |
| TypeScript | session |
| Go | tmux |
| Java | io |
| Clojure | libtmux Acquires a vector of captured session maps. The session value is a map, not a wrapper class. |
| Kotlin | io |
| Scala | io |
| C# | Lib |
| F# | Lib This F# module builds deferred child queries from a shared .NET LibTmux.Session and its server association. Query.list acquires their results from tmux. |
| C++ | libtmux:: |
| Swift | Session |
| OCaml | Libtmux |
| Perl | Lib A captured read-only entity; explicit Server operations accept its stable identity. |