From 66d5e5de7ac6a81f638d1a2b2f5262368a68fee2 Mon Sep 17 00:00:00 2001
From: nicm <nicm>
Date: Mon, 6 Jul 2020 09:14:20 +0000
Subject: Add a way for control mode clients to subscribe to a format and be
 notified of changes rather than having to poll. GitHub issue 2242.

---
 tmux.1 | 48 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

(limited to 'tmux.1')

diff --git a/tmux.1 b/tmux.1
index 4d079853..1c02bdda 100644
--- a/tmux.1
+++ b/tmux.1
@@ -1255,6 +1255,7 @@ specified multiple times.
 .It Xo Ic refresh-client
 .Op Fl cDlLRSU
 .Op Fl A Ar pane:state
+.Op Fl B Ar name:what:format
 .Op Fl C Ar XxY
 .Op Fl f Ar flags
 .Op Fl t Ar target-client
@@ -1328,6 +1329,31 @@ will pause the pane.
 .Fl A
 may be given multiple times for different panes.
 .Pp
+.Fl B
+sets a subscription to a format for a control mode client.
+The argument is split into three items by colons:
+.Ar name
+is a name for the subscription;
+.Ar what
+is a type of item to subscribe to;
+.Ar format
+is the format.
+After a subscription is added, changes to the format are reported with the
+.Ic %subscription-changed
+notification, at most once a second.
+If only the name is given, the subscription is removed.
+.Ar what
+may be empty to check the format only for the attached session, or one of:
+a pane ID such as
+.Ql %0 ;
+.Ql %*
+for all panes in the attached session;
+an window ID such as
+.Ql @0 ;
+or
+.Ql @*
+for all windows in the attached session.
+.Pp
 .Fl f
 sets a comma-separated list of client flags, see
 .Ic attach-session .
@@ -5932,7 +5958,7 @@ or an error occurred.
 If present,
 .Ar reason
 describes why the client exited.
-.It Ic %extended-output Ar pane-id Ar age Ar ... : Ar value
+.It Ic %extended-output Ar pane-id Ar age Ar ... \&  : Ar value
 New form of
 .Ic %output
 sent when the
@@ -5980,6 +6006,26 @@ changed its active window to the window with ID
 .Ar window-id .
 .It Ic %sessions-changed
 A session was created or destroyed.
+.It Xo Ic %subscription-changed
+.Ar name
+.Ar session-id
+.Ar window-id
+.Ar window-index
+.Ar pane-id ... \&  :
+.Ar value
+.Xc
+The value of the format associated with subscription
+.Ar name
+has changed to
+.Ar value .
+See
+.Ic refresh-client
+.Fl B .
+Any arguments after
+.Ar pane-id
+up until a single
+.Ql \&:
+are for future use and should be ignored.
 .It Ic %unlinked-window-add Ar window-id
 The window with ID
 .Ar window-id
-- 
cgit