Literal text and tmux formats¶
tmux expands formats such as
#{session_name} in many command arguments, including window names, pane
titles and start directories. libtmux keeps the text you pass as plain str
exactly as you typed it, so a # in a name or path never turns into something
else. When you want tmux to expand a value, wrap it in
Format.
>>> from libtmux import Format
Plain strings are kept as typed¶
A plain str is stored exactly, even when it looks like a format:
>>> window.rename_window("build#2")
Window(...)
>>> window.window_name
'build#2'
>>> window.rename_window("#{session_name}")
Window(...)
>>> window.window_name
'#{session_name}'
This covers every name, title, start directory and file path libtmux passes to an argument tmux expands:
session and window names in
new_session(),new_window(),rename_session()andrename_window()pane titles in
set_title(), and the titles ofdisplay_popup()anddisplay_menu()start directories in
new_session,new_window,split,new_pane, the respawn methods,display_popup()andrun_shell()buffer files in
save_buffer()andload_buffer()
Ask tmux to expand a value¶
Wrap a format your program wrote in Format, and tmux expands
it as it would in tmux.conf:
>>> pane.split(start_directory=Format("#{pane_current_path}"))
Pane(...)
Each argument decides for itself, so one call can mix the two. Here the window name stays literal while the start directory is expanded:
>>> new_window = session.new_window(
... window_name="build#2",
... start_directory=Format("#{pane_current_path}"),
... )
>>> new_window.window_name
'build#2'
Type checkers see the difference too. Parameters that accept a format are
typed str | Format, so passing a Format where tmux would
store the text unchanged, such as
Pane.break_pane(window_name=...), is a type
error.
Note
tmux expands a start directory against the session’s active pane, not the pane
being split, so #{pane_current_path} is the active pane’s directory. To start
in a particular pane’s directory, pass its
pane_current_path instead.
Add text from users or files¶
Only wrap text your program wrote. Text from users, files or other programs can
contain # too, so add it with + or join(), which keep
it literal:
>>> user_text = "50% #1"
>>> window.rename_window(Format("#{session_name}: ") + user_text)
Window(...)
>>> window.window_name == f"{session.session_name}: 50% #1"
True
Plain text can only be added where tmux reads text. Adding it after a format
that ends with # or an unfinished % time field, or inside an unfinished
#{...}, #(...) or #[...], raises, because tmux would read it as format
syntax:
>>> Format("#{?pane_active,") + "yes"
Traceback (most recent call last):
...
ValueError: cannot add plain text to Format('#{?pane_active,'): ...
To place text inside an expression, such as one side of a comparison, use
Format.escape(). It writes the text so tmux
reads every character back as itself, including the , and } that would
otherwise end an argument:
>>> same_name = (
... Format("#{==:#{window_name},")
... + Format.escape(window.window_name)
... + Format("}")
... )
>>> window.active_pane.display_message(same_name, get_text=True)
['1']
Do not place text from users inside #(...). tmux finds the end of the
command by counting parentheses before the shell sees any quoting, so a ) in
the text ends the command early. Run the command from Python and pass its
output instead.
Arguments tmux always expands¶
Some arguments are formats by design:
display_message(), the commands of
run_shell(), if_shell() and
pipe(), and the filter of the search_* methods. A plain
str there reaches tmux as written and is expanded, as it always has been:
>>> pane.display_message("#{pane_id}", get_text=True) == [pane.pane_id]
True
They accept a Format too, so text from users can be shown
exactly. Some of them also expand % as a time field, which
Format.escape() keeps literal:
>>> pane.display_message(Format.escape("50%d done"), get_text=True)
['50%d done']
Menu item names given to display_menu() are formats as
well, so a name such as #{?pane_marked,Unmark,Mark} changes with the pane.
What literal means for titles¶
A literal title is not expanded as a format. tmux still reads #[...] style
sequences when it draws a title on screen, as it does for every name it draws,
so a title of #[fg=red]X is shown as a red X.
Version notes¶
tmux expands
run_shell()’scwdfrom tmux 3.8. On earlier tmux a plain path is used as given, andcwd=Format(...)raisesLibTmuxException.save_buffer()takes a plain path only: libtmux creates the file readable by its owner before tmux writes it, which needs the final path.new_session()withkill_session=Trueneeds a plain session name, because aFormatname is known only after tmux creates the session.
Raw commands¶
Server.cmd() and the other cmd() methods pass
arguments to tmux unchanged, so a # there is expanded as tmux sees fit.