hook_name is provided to allow this to set to multiple scenarios, such as ‘client-attached’ (which the user attaches the session). You may also want ‘after-switch-client’ for cases where the user loads tmuxp sessions inside tmux since tmuxp offers to switch for them.

Also, the hooks are set immediately unbind after they’re invoked via -u.

Parameters:

session (libtmux.session.Session) – session to bind hook to
hook_name (str) – hook name to bind to, e.g. ‘client-attached’

tmuxp.cli.load.load_plugins(session_config)[source]#

Load and return plugins in workspace.

Return type:: List[Any]

tmuxp.cli.load._reattach(builder)[source]#

Reattach session (depending on env being inside tmux already or not).

Return type:: None
Parameters:: builder (workspace.builder.WorkspaceBuilder) –

Notes

If TMUX environmental variable exists in the environment this script is running, that means we’re in a tmux client. So tmux switch-client will load the session.

If not, tmux attach-session loads the client to the target session.

tmuxp.cli.load._load_attached(builder, detached)[source]#

Load workspace in new session.

Return type:

None

Parameters:

builder (workspace.builder.WorkspaceBuilder) –
detached (bool) –

tmuxp.cli.load._load_detached(builder)[source]#

Load workspace in new session but don’t attach.

Return type:: None
Parameters:: builder (workspace.builder.WorkspaceBuilder) –

tmuxp.cli.load._load_append_windows_to_current_session(builder)[source]#

Load workspace as new windows in current session.

Return type:: None
Parameters:: builder (workspace.builder.WorkspaceBuilder) –

tmuxp.cli.load._setup_plugins(builder)[source]#

Execute hooks for plugins running after before_script.

Return type:: Session
Parameters:: builder (workspace.builder.WorkspaceBuilder) –

tmuxp.cli.load.load_workspace(workspace_file, socket_name=None, socket_path=None, tmux_config_file=None, new_session_name=None, colors=None, detached=False, answer_yes=False, append=False)[source]#

Entrypoint for tmuxp load, load a tmuxp “workspace” session via config file.

Return type:

Optional[Session]

Parameters:

workspace_file (list of str) – paths or session names to workspace files
socket_name (str, optional) – tmux -L <socket-name>
socket_path (str, optional) – tmux -S <socket-path>
new_session_name (str, options) – tmux new -s <new_session_name>
colors (str, optional) –

‘-2’
Force tmux to support 256 colors
detached (bool) – Force detached state. default False.
answer_yes (bool) – Assume yes when given prompt to attach in new session. Default False.
append (bool) – Assume current when given prompt to append windows in same session. Default False.

Notes

tmuxp will check and load a workspace file. The file will use ConfigReader to load a JSON/YAML into a dict. Then loader.expand() and loader.trickle() will be used to expand any shorthands, template variables, or file paths relative to where the config/script is executed from.

loader.expand() accepts the directory of the config file, so the user’s workspace can resolve absolute paths relative to where the workspace file is. In otherwords, if a workspace file at /var/moo/hi.yaml has ./ in its workspaces, we want to be sure any file path with ./ is relative to /var/moo, not the user’s PWD.

A libtmux.Server object is created. No tmux server is started yet, just the object.

The prepared workspace and its server object is passed into an instance of WorkspaceBuilder.

A sanity check against libtmux.common.which() is ran. It will raise an exception if tmux isn’t found.

If a tmux session under the same name as session_name in the tmuxp workspace exists, tmuxp offers to attach the session. Currently, tmuxp does not allow appending a workspace / incremental building on top of a current session (pull requests are welcome!).

build() will build the session in the background via using tmux’s detached state (-d).

After the session (workspace) is built, unless the user decided to load the session in the background via tmuxp -d (which is in the spirit of tmux’s -d), we need to prompt the user to attach the session.

If the user is already inside a tmux client, which we detect via the TMUX environment variable bring present, we will prompt the user to switch their current client to it.

If they’re outside of tmux client - in a plain-old PTY - we will automatically attach.

If an exception is raised during the building of the workspace, tmuxp will prompt to cleanup ($ tmux kill-session) the session on the user’s behalf. An exception raised during this process means it’s not easy to predict how broken the session is.

Changed in version tmux: 2.6+

In tmux 2.6, the way layout and proportion’s work when interfacing with tmux in a detached state (outside of a client) changed. Since tmuxp builds workspaces in a detached state, the WorkspaceBuilder isn’t able to rely on functionality requiring awarness of session geometry, e.g. set-layout.

Thankfully, tmux is able to defer commands to run after the user performs certain actions, such as loading a client via attach-session or switch-client.

Upon client switch, client-session-changed is triggered [1]_.

References

tmuxp.cli.load.create_load_subparser(parser)[source]#

Augment argparse.ArgumentParser with load subcommand.

Return type:: ArgumentParser

tmuxp.cli.load.command_load(args, parser=None)[source]#

Load a tmux workspace from each WORKSPACE_FILE.

WORKSPACE_FILE is a specifier for a workspace file.

If WORKSPACE_FILE is a path to a directory, tmuxp will search it for “.tmuxp.{yaml,yml,json}”.

If WORKSPACE_FILE is has no directory component and only a filename, e.g. “myworkspace.yaml”, tmuxp will search the users’s workspace directory for that file.

If WORKSPACE_FILE has no directory component, and only a name with no extension, e.g. “myworkspace”, tmuxp will search the users’s workspace directory for any file with the extension “.yaml”, “.yml”, or “.json” that matches that name.

If multiple workspace files that match a given WORKSPACE_FILE are found, tmuxp will warn and pick the first one found.

If multiple WORKSPACE_FILEs are provided, workspaces will be created for all of them. The last one provided will be attached. The others will be created in detached mode.

Return type:: None

tmuxp load - tmuxp.cli.load#

tmuxp load - `tmuxp.cli.load`#