LibTmux.Workspace\ConvertTo-TmuxWorkspace

Description#

Return one native WorkspaceFile for each captured Session received from the pipeline. The shared library preserves captured window placements and pane order, names, layouts, active window and pane flags, and pane directories. Repeated links to the same window become separate declared windows.

Capture with Get-TmuxSnapshot -Depth Panes before selecting a Session . Conversion never contacts tmux or fills unavailable relations. The captured graph remains convertible after its daemon exits. A missing field or relation is an error; a captured null pane directory remains unspecified rather than using the host's current directory.

Captured directories become unresolved declaration values with literal dollars escaped as $$. DocumentDirectory remains null. Use Resolve-TmuxWorkspace with an explicit BaseDirectory before planning, or convert the declaration to YAML or JSON and resolve it after importing. Do not interpret those escaped values as already resolved filesystem paths.

Conversion preserves session-relative window indices. It emits a warning for each successful input because it omits observed environment, options, terminal text, entity IDs, pane indices and shared-link identity. It cannot reconstruct original commands, arguments or shell intent. Foreground command names do not establish the shell command that started a pane. Original relative paths, expansion variables, comments, host scripts and pre-commands are not reconstructed. Native custom layouts can change which pane occupies a position when applied. This declaration is a starting configuration, not a checkpoint of running programs.

Notes

Tmux.WorkspaceFreezeFailed retains the original native exception and input Session as its target. IncompleteSnapshotException uses the InvalidData error category. ErrorAction Continue permits later sessions to be converted without emitting a declaration for a failed input; ErrorAction Stop terminates. The loss warning uses PowerShell's warning stream and supports WarningAction . The command performs no acquisition, execution or file write and has no WhatIf or Confirm parameters.