# session.Session

- **Module:** session
- **Package:** libtmux
- **Language:** Rust
- **Kind:** struct
- **Source:** https://github.com/libtmux/libtmux-rs/blob/f0e37052c232636b61d095817046e6bfc8f2ca40/crates/libtmux/src/session.rs#L106
- **Page:** https://libtmux.org/en/rs/latest/reference/session-session/

One tmux session, together with the snapshot it was discovered with.

A `Session` is cheap to clone and shares its connection with the [`Server`]
that 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`.

## Example

```rust
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?;
```

## Members

- `from_env` (method): Find the session this process is running in.
- `from_env_value` (method): Find a session from an explicit `TMUX_PANE` value.
- `id` (method): Return the tmux session identity.
- `name` (method): Return the session name.
- `path` (method): Return the session's working directory.
- `window_count` (method): Return how many windows the session contains.
- `attached_client_count` (method): Return how many clients are attached to the session.
- `is_attached` (method): Report whether any client is attached.
- `created` (method): Return when the session was created.
- `last_attached` (method): Return when a client last attached.
- `windows` (method): List the windows linked into this session, preserving any failure.
- `search_windows` (method): The windows under this session that a matcher accepts, reporting why if the listing fails.
- `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.
- `active_window` (method): Return the session's active window.
- `panes` (method): List every pane in this session, preserving any failure.
- `refresh` (method): Replace this handle's snapshot with the session's current state.
- `refreshed` (method): Return a new handle holding the session's current state.
- `new_window` (method): Create a window in this session and return it.
- `rename` (method): Rename the session and update this handle.
- `kill` (method): Kill the session.
- `cmd` (method): Run a raw tmux command against this session.
- `format` (method): Expand a tmux format string in this session's context.
- `display` (method): Show a message on the clients viewing this session.
- `lock` (method): Lock every client attached to this session.
- `detach_clients` (method): Detach every client attached to this session.
- `with_window` (method): Create a window, run an operation with it, then kill it.
- `window` (method): Find this session's window with the given name.
- `window_at` (method): Find this session's window at the given index.
- `get` (method): Read one field of this session's snapshot, named by the handle that filters it.
- `option_names` (method): List the option names set at this session's scope.
- `options` (method): Read every option set at this session, decoded by its declared kind.
- `set_option` (method): Set one option to text, unchecked.
- `set_typed_option` (method): Set one option to a typed value, checked before it is sent.
- `append_option` (method): Append to one option rather than replacing it.
- `unset_option` (method): Remove one option, restoring whatever it inherits.
- `set_hook` (method): Set one hook to a tmux command.
- `unset_hook` (method): Remove one hook.
- `set_hooks` (method): Write a whole hook at once.
- `hooks` (method): Read every hook set at this session.
- `hook` (method): Read one hook's commands, or `None` when it holds nothing.
- `set_environment` (method): Set an environment variable for processes this session starts.
- `environment` (method): Read one variable from the session's environment.
- `environment_all` (method): Read the session's whole environment.
- `hide_environment` (method): Hide a variable from processes started in this session.
- `unset_environment` (method): Remove an environment variable from the session.
- `typed_option` (method): Read one option, decoded according to what tmux declares about it.