LibTmux.Workspace\Get-TmuxWorkspace

Description#

Return native FileInfo objects for readable, seekable declaration files. Discovery does not contact tmux, run scripts, resolve declaration variables or create configuration directories. Pipe a selected file to Import-TmuxWorkspace for parsing, or Resolve-TmuxWorkspace for explicit file-relative resolution.

With no arguments, list .tmuxp.yaml, .tmuxp.yml and .tmuxp.json in the current filesystem directory, then each ancestor through HOME when it is an ancestor, otherwise through the filesystem root. Each directory uses that extension order. Append files from the first existing global configuration directory: ConfigurationDirectory, TMUXP_CONFIGDIR, XDG_CONFIG_HOME/tmuxp (or HOME/.config/tmuxp), then HOME/.tmuxp. HOME falls back to the platform user profile directory when unset. Missing default locations are skipped; an explicit missing ConfigurationDirectory is an error. AllLocations includes all existing global candidates in that order, preserving shadowed files. Global filenames sort ordinally within each location. Repeated full paths are emitted once.

Directory checks only the three local .tmuxp filenames in that exact directory. LiteralPath selects one exact filesystem file and bypasses discovery; it has no extension restriction. File symlinks retain their literal paths when the shared opener accepts the target. Directory entries are not files and are never recursively descended, including directory symlinks.

Name searches only the selected global locations. It is a literal basename, with an optional .yaml, .yml or .json suffix. Without a supported suffix, those three suffixes are tried in order. Multiple matches in one location are an ambiguity error naming the candidates; use LiteralPath to choose. A missing name emits no objects. Path separators are rejected; wildcard characters are literal. Filename suffixes are lowercase and literal; path/name identity follows the filesystem, independently of search case behavior.

Search uses literal ordinal-ignore-case substring matching on filenames by default. CaseSensitive selects ordinal matching. SearchIn selects FileName, Path, Session , Window , Command or Directory fields. Path searches the full selected path without reading file content. Any content field parses every candidate with the shared strict UTF-8 reader, accepting a UTF-8 BOM and at most 1048576 characters. Command includes before_script and all pane commands and shell_command_before entries; none are executed. Directory searches declared strings without expansion. Multiple fields combine by OR. Malformed candidate data fails content search even if its filename matches.

Traversal stops with an error after 1024 examined entries: existing local marker probes and global directory entries count, including unselected suffixes and directories. Ancestor traversal also has a 1024-directory ceiling. Narrow the request with Directory, Name or LiteralPath. Results are published only after successful discovery/search, so failures do not emit truncated lists. Filesystem contents can change between discovery and later import; FileInfo output is not a locked or atomic filesystem snapshot.

Notes

Failures write Tmux.WorkspaceDiscoveryFailed with the request as TargetObject. File read/parse errors retain the original exception and identify the failing path in Exception.Data['WorkspacePath']. Use ErrorAction Stop to terminate. Cancellation is checked between traversal, read and search operations and before publication. Stopping discovery does not delete files or stop a daemon.