Branch: refs/heads/5211-fix-select-layout-list-windows
Home: https://github.com/tmux/tmux
Commit: 64db14442502bb8d9a8888918819994f874d0190
https://github.com/tmux/tmux/commit/64db14442502bb8d9a8888918819994f874d0190
Author: Michael Grant <[email protected]>
Date: 2026-06-29 (Mon, 29 Jun 2026)
Changed paths:
M cmd-select-layout.c
M layout-custom.c
M layout.c
M regress/control-client-sanity.sh
A regress/layout-custom.sh
M tmux.1
M tmux.h
M window.c
Log Message:
-----------
Update select-layout and list-windows to work with new layouts,
floating panes, and use a more modern serialization format.
## Serialization
layout-custom.c now emits a canonical current format with:
- Pane syntax: %pane-id,z-index:geometry[:flags]
- Semicolons between child cells.
- X-style geometry: WxH+X+Y
- Every pane represented inside layout_root, including floating panes.
- No legacy <...> floating-pane wrapper.
- Z-index serialized for tiled and floating panes.
- Flags:
- f: floating
- h: hidden
- z: zoomed
- Hidden panes use their saved restoration geometry.
- Single-pane windows serialize as a pane root cell.
window_layout and list-windows continue emitting a four-digit checksum.
## Geometry
Current layouts accept:
- +N: absolute positive offset
- ++N: equivalent to +N
- +-N: absolute negative offset
- -N: right/bottom-relative offset for floating panes
- Omitted offsets: +0+0
- One offset: second defaults to +0
Relative offsets are resolved immediately. Output always contains canonical
absolute
coordinates.
Widths and heights are restricted to 1..PANE_MAXIMUM; offsets and resolved
offsets are
restricted to -PANE_MAXIMUM..PANE_MAXIMUM.
## Checksums and whitespace
- The outer checksum is optional on input for current and legacy layouts.
- If supplied, it must be correct.
- Output still includes it.
- Checksums cover all non-whitespace layout text.
- Whitespace and newlines may be inserted between tokens.
- Optional nested checksums are accepted and validated but not emitted.
## Legacy compatibility
Legacy comma-separated layouts remain accepted:
WxH,x,y{cell,cell,...}
WxH,x,y,pane-id
Additional compatibility behavior includes:
- The reported e6db,113x28,... layout works and resizes existing panes
correctly.
- Older inconsistent root dimensions are corrected safely.
- Legacy layouts with surplus cells continue pruning cells until the target
pane count
matches.
- Legacy panes remain assigned in tree order.
- Legacy input is re-emitted in the current canonical format.
Mixed legacy/current syntax is rejected.
## Pane matching and counts
For current layouts:
- Pane IDs must be unique.
- With matching pane counts:
- An exact ID set maps panes by identity.
- A completely disjoint ID set maps panes in tree order.
- A partial ID match is rejected as ambiguous.
- If the target has fewer panes:
- Cells are removed from the end of the tree.
- Remaining z-indexes are compacted while preserving order.
- Existing panes are assigned in tree order.
- No panes are killed or created.
- A target with more panes than layout cells is rejected.
Layouts are therefore snapshots that rearrange existing panes and windows,
not complete
session-restoration data.
## Validation and safety
Parsing now constructs and validates a temporary tree before replacing the
active layout:
- Maximum input length: 8192 bytes.
- Maximum nesting depth: 64.
- Checked signed and unsigned numeric parsing.
- Dimension and offset bounds.
- Container size consistency.
- Exact trailing-input checks.
- Unique, contiguous z-indexes starting at zero.
- Floating panes must precede tiled panes in z-order.
- Unknown and duplicate flags are rejected.
- Hidden and zoomed flags cannot be combined.
- Only one pane may be zoomed.
- Relative positioning is accepted only for floating panes.
- Overflow-safe size aggregation.
Invalid single-window layouts are validated before the window is unzoomed.
Multi-window
layouts are all validated before any window is changed.
## Multi-window layouts
cmd-select-layout.c accepts:
@window-id:layout[@window-id:layout...]
Records may be adjacent or separated by whitespace/newlines. Unknown and
duplicate window IDs
are rejected.
This allows direct reuse of:
tmux list-windows -F '#{window_id}:#{window_layout}'
## Supporting runtime changes
- tmux.h adds parsed pane IDs, z-indexes, hidden/zoomed/relative cell flags,
and
layout_validate.
- layout.c initializes parsed metadata safely.
- window.c treats hidden cells, including saved cells, as non-visible.
## Documentation
tmux.1 now documents:
- Current and legacy grammars.
- Geometry and flags.
- Z-index and pane-ID rules.
- Optional checksums.
- Multi-window wrappers.
- Pane-count pruning.
- Snapshot versus session-restoration semantics.
The authoritative description is under select-layout; list-windows and
list-panes reference
it.
## Tests
Added regress/layout-custom.sh covering serialization, compatibility,
validation, geometry,
IDs, pruning, flags, zoom, checksums, whitespace, and multi-window
application.
Updated regress/control-client-sanity.sh for canonical output.
Verified:
- Debug build
- Layout regression
- Floating-pane geometry regression
- Control-client regression
- Man-page rendering
- git diff --check
To unsubscribe from these emails, change your notification settings at
https://github.com/tmux/tmux/settings/notifications
--
You received this message because you are subscribed to the Google Groups
"tmux-git" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion, visit
https://groups.google.com/d/msgid/tmux-git/tmux/tmux/push/refs/heads/5211-fix-select-layout-list-windows/91e30f-64db14%40github.com.
