tmuxp ls - tmuxp.cli.ls

CLI for tmuxp ls subcommand.

List and display workspace configuration files.

Examples

>>> from tmuxp.cli.ls import WorkspaceInfo

Create workspace info from file path:

>>> import pathlib
>>> ws = WorkspaceInfo(
...     name="dev",
...     path="~/.tmuxp/dev.yaml",
...     format="yaml",
...     size=256,
...     mtime="2024-01-15T10:30:00",
...     session_name="development",
...     source="global",
... )
>>> ws["name"]
'dev'
>>> ws["source"]
'global'
class tmuxp.cli.ls.WorkspaceInfo[source]

Bases: TypedDict

Workspace file information for JSON output.

name

Workspace name (file stem without extension).

Type:

str

path

Path to workspace file (with ~ contraction).

Type:

str

format

File format (yaml or json).

Type:

str

size

File size in bytes.

Type:

int

mtime

Modification time in ISO format.

Type:

str

session_name

Session name from config if parseable.

Type:

str | None

source

Source location: “local” (cwd/parents) or “global” (~/.tmuxp/).

Type:

str

name: str
path: str
format: str
size: int
mtime: str
session_name: str | None
source: str
class tmuxp.cli.ls.CLILsNamespace(**kwargs)[source]

Bases: Namespace

Typed argparse.Namespace for tmuxp ls command.

Examples

>>> ns = CLILsNamespace()
>>> ns.color = "auto"
>>> ns.color
'auto'
color: CLIColorModeLiteral
tree: bool
output_json: bool
output_ndjson: bool
full: bool
tmuxp.cli.ls.create_ls_subparser(parser)[source]

Augment argparse.ArgumentParser with ls subcommand.

Return type:

ArgumentParser

Parameters:

parser (argparse.ArgumentParser) – The parser to augment.

Returns:

The augmented parser.

Return type:

argparse.ArgumentParser

Examples

>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> result = create_ls_subparser(parser)
>>> result is parser
True
tmuxp.cli.ls._get_workspace_info(filepath, *, source='global', include_config=False)[source]

Extract metadata from a workspace file.

Return type:

dict[str, Any]

Parameters:

  • filepath (pathlib.Path) – Path to the workspace file.

  • source (str) – Source location: “local” or “global”. Default “global”.

  • include_config (bool) – If True, include full parsed config content. Default False.

Returns:

Workspace metadata dictionary. Includes ‘config’ key when include_config=True.

Return type:

dict[str, Any]

Examples

>>> content = "session_name: test-session" + chr(10) + "windows: []"
>>> yaml_file = tmp_path / "test.yaml"
>>> _ = yaml_file.write_text(content)
>>> info = _get_workspace_info(yaml_file)
>>> info['session_name']
'test-session'
>>> info['format']
'yaml'
>>> info['source']
'global'
>>> info_local = _get_workspace_info(yaml_file, source="local")
>>> info_local['source']
'local'
>>> info_full = _get_workspace_info(yaml_file, include_config=True)
>>> 'config' in info_full
True
>>> info_full['config']['session_name']
'test-session'
tmuxp.cli.ls._render_config_tree(config, colors)[source]

Render config windows/panes as tree lines for human output.

Return type:

list[str]

Parameters:

  • config (dict[str, Any]) – Parsed config content.

  • colors (Colors) – Color manager.

Returns:

Lines of formatted tree output.

Return type:

list[str]

Examples

>>> from tmuxp.cli._colors import ColorMode, Colors
>>> colors = Colors(ColorMode.NEVER)
>>> config = {
...     "session_name": "dev",
...     "windows": [
...         {"window_name": "editor", "layout": "main-horizontal"},
...         {"window_name": "shell"},
...     ],
... }
>>> lines = _render_config_tree(config, colors)
>>> "editor" in lines[0]
True
>>> "shell" in lines[1]
True
tmuxp.cli.ls._render_global_workspace_dirs(formatter, colors, global_dir_candidates)[source]

Render global workspace directories section.

Return type:

None

Parameters:

  • formatter (OutputFormatter) – Output formatter.

  • colors (Colors) – Color manager.

  • global_dir_candidates (list[dict[str, Any]]) – List of global workspace directory candidates with metadata.

Examples

>>> from tmuxp.cli._output import OutputFormatter, OutputMode
>>> from tmuxp.cli._colors import Colors, ColorMode
>>> formatter = OutputFormatter(OutputMode.HUMAN)
>>> colors = Colors(ColorMode.NEVER)
>>> candidates = [
...     {"path": "~/.tmuxp", "source": "Legacy", "exists": True,
...      "workspace_count": 5, "active": True},
...     {"path": "~/.config/tmuxp", "source": "XDG", "exists": False,
...      "workspace_count": 0, "active": False},
... ]
>>> _render_global_workspace_dirs(formatter, colors, candidates)

Global workspace directories:
  Legacy: ~/.tmuxp (5 workspaces, active)
  XDG: ~/.config/tmuxp (not found)
tmuxp.cli.ls._output_flat(workspaces, formatter, colors, *, full=False, global_dir_candidates=None)[source]

Output workspaces in flat list format.

Groups workspaces by source (local vs global) for human output.

Return type:

None

Parameters:

  • workspaces (list[dict[str, Any]]) – Workspaces to display.

  • formatter (OutputFormatter) – Output formatter.

  • colors (Colors) – Color manager.

  • full (bool) – If True, show full config details in tree format. Default False.

  • global_dir_candidates (list[dict[str, Any]] | None) – List of global workspace directory candidates with metadata.

Examples

>>> from tmuxp.cli._output import OutputFormatter, OutputMode
>>> from tmuxp.cli._colors import Colors, ColorMode
>>> formatter = OutputFormatter(OutputMode.HUMAN)
>>> colors = Colors(ColorMode.NEVER)
>>> workspaces = [{"name": "dev", "path": "~/.tmuxp/dev.yaml", "source": "global"}]
>>> _output_flat(workspaces, formatter, colors)
Global workspaces:
  dev
tmuxp.cli.ls._output_tree(workspaces, formatter, colors, *, full=False, global_dir_candidates=None)[source]

Output workspaces grouped by directory (tree view).

Return type:

None

Parameters:

  • workspaces (list[dict[str, Any]]) – Workspaces to display.

  • formatter (OutputFormatter) – Output formatter.

  • colors (Colors) – Color manager.

  • full (bool) – If True, show full config details in tree format. Default False.

  • global_dir_candidates (list[dict[str, Any]] | None) – List of global workspace directory candidates with metadata.

Examples

>>> from tmuxp.cli._output import OutputFormatter, OutputMode
>>> from tmuxp.cli._colors import Colors, ColorMode
>>> formatter = OutputFormatter(OutputMode.HUMAN)
>>> colors = Colors(ColorMode.NEVER)
>>> workspaces = [{"name": "dev", "path": "~/.tmuxp/dev.yaml", "source": "global"}]
>>> _output_tree(workspaces, formatter, colors)

~/.tmuxp
  dev
tmuxp.cli.ls.command_ls(args=None, parser=None)[source]

Entrypoint for tmuxp ls subcommand.

Lists both local workspaces (from cwd and parent directories) and global workspaces (from ~/.tmuxp/).

Return type:

None

Parameters:

Examples

>>> # command_ls() lists workspaces from cwd/parents and ~/.tmuxp/