Replace --track=NTH with --id-nth for cross-reload item identity

Separate item identity from cursor tracking:
- Add --id-nth=NTH to define item identity fields for cross-reload ops
- --track reverts to a simple boolean flag
- track-current action no longer accepts nth argument
- With --multi, selections are preserved across reload-sync by matching
  identity keys in the reloaded list

Close #4718
Close #4701
Close #4483
Close #4409
Close #3460
Close #2441

man/man1/fzf.1

@@ -617,28 +617,18 @@ Disable multi-line display of items when using \fB\-\-read0\fR
 .B "\-\-raw"
 Enable raw mode where non-matching items are also displayed in a dimmed color.
 .TP
-.BI "\-\-track" "[=NTH]"
+.BI "\-\-track"
 Make fzf track the current selection when the result list is updated.
 This can be useful when browsing logs using fzf with sorting disabled. It is
 not recommended to use this option with \fB\-\-tac\fR as the resulting behavior
 can be confusing.
 
-When an nth expression is explicitly given (e.g. \fB\-\-track=..\fR or
-\fB\-\-track=1\fR), fzf enables field\-based tracking across \fBreload\fRs.
-On reload, fzf extracts the tracking key from the current item using the nth
-expression and searches for a matching item in the reloaded list. While
-searching, the UI is blocked (query input and cursor movement are disabled, and
-the prompt is dimmed). With \fBreload\fR, the blocked state clears as soon as
-the match is found in the stream. With \fBreload\-sync\fR, the blocked state
-persists until the entire stream is complete. Press \fBEscape\fR or
-\fBCtrl\-C\fR to cancel the blocked state without quitting fzf.
+When \fB\-\-id\-nth\fR is also set, fzf enables field\-based tracking across
+\fBreload\fRs. See \fB\-\-id\-nth\fR for details.
 
-Without the nth expression, \fB\-\-track\fR uses index\-based tracking that
+Without \fB\-\-id\-nth\fR, \fB\-\-track\fR uses index\-based tracking that
 does not persist across reloads.
 
-The info line shows \fB+T*\fR (or \fB+t*\fR for one\-off tracking) while
-the search is in progress.
-
 .RS
 e.g.
      \fB# Index\-based tracking (does not persist across reloads)
@@ -646,10 +636,36 @@ e.g.
          fzf \-\-ansi \-\-track \-\-no\-sort \-\-layout=reverse\-list\fR
 
      \fB# Track by first field (e.g. pod name) across reloads
-     kubectl get pods | fzf \-\-track=1 \-\-header\-lines=1 \\
+     kubectl get pods | fzf \-\-track \-\-id\-nth 1 \-\-header\-lines=1 \\
          \-\-bind 'ctrl\-r:reload:kubectl get pods'\fR
 .RE
 .TP
+.BI "\-\-id\-nth=" "N[,..]"
+Define item identity fields for cross\-reload operations. When set, fzf
+uses the specified fields to identify items across \fBreload\fR and
+\fBreload\-sync\fR.
+
+With \fB\-\-track\fR, fzf extracts the tracking key from the current item
+using the nth expression and searches for a matching item in the reloaded list.
+While searching, the UI is blocked (query input and cursor movement are
+disabled, and the prompt is dimmed). With \fBreload\fR, the blocked state
+clears as soon as the match is found in the stream. With \fBreload\-sync\fR,
+the blocked state persists until the entire stream is complete. Press
+\fBEscape\fR or \fBCtrl\-C\fR to cancel the blocked state without quitting fzf.
+
+The info line shows \fB+T*\fR (or \fB+t*\fR for one\-off tracking) while
+the search is in progress.
+
+With \fB\-\-multi\fR, selected items are preserved across \fBreload\-sync\fR
+by matching their identity fields in the reloaded list.
+
+.RS
+e.g.
+     \fB# Track and preserve selections by pod name across reloads
+     kubectl get pods | fzf \-\-multi \-\-track \-\-id\-nth 1 \-\-header\-lines=1 \\
+         \-\-bind 'ctrl\-r:reload\-sync:kubectl get pods'\fR
+.RE
+.TP
 .B "\-\-tac"
 Reverse the order of the input
 
@@ -2027,7 +2043,6 @@ A key or an event can be bound to one or more of the following actions.
     \fBtoggle+down\fR                  \fIctrl\-i  (tab)\fR
     \fBtoggle+up\fR                    \fIbtab    (shift\-tab)\fR
     \fBtrack\-current\fR                (track the current item; automatically disabled if focus changes)
-    \fBtrack\-current(...)\fR           (track the current item using the given nth expression as the tracking key)
     \fBtransform(...)\fR               (transform states using the output of an external command)
     \fBtransform\-border\-label(...)\fR  (transform border label using an external command)
     \fBtransform\-ghost(...)\fR         (transform ghost text using an external command)