From 818352c3cdc1ef137fee97534c8eda1e26ca09d0 Mon Sep 17 00:00:00 2001
From: nicm <nicm>
Date: Sun, 17 May 2026 11:12:07 +0000
Subject: [PATCH] Add some more explanatory text about targets, GitHub issue
 4850.

---
 tmux.1 | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/tmux.1 b/tmux.1
index 9bc8d8a4..56bf6386 100644
--- a/tmux.1
+++ b/tmux.1
@@ -934,6 +934,37 @@ or
 .Ic list\-panes
 commands.
 .Pp
+.Em target\-session ,
+.Em target\-window
+or
+.Em target\-pane
+each denote the
+.Ql type
+of target the command needs to work on.
+If a target is not explicitly qualified using
+.Ql \&:
+and
+.Ql \&. ,
+.Nm
+will pick what seems to be the best choice available.
+For example, if a
+.Em target-pane
+of
+.Ql 1
+is used with a current window that has only one pane,
+.Nm
+knows that the
+.Ql 1
+cannot mean a pane, so it will look for the active pane in window 1, or the
+active pane in the current window in session 1.
+Only if none of these are present will it report an error.
+If it is important that a specific pane, window or session always be used,
+such as from a script, the target should be fully qualified (for example a
+.Em target-pane
+of
+.Ql -t:.1 ) ,
+or pane, window or session IDs should be used.
+.Pp
 .Ar shell\-command
 arguments are
 .Xr sh 1