Merge pull request #793 from peco/update-manpage

docs: update man page
2026-09-10 07:16:29 -04:00 · 2026-02-22 11:45:43 +09:00 · 2026-02-22 11:45:43 +09:00 · e1453e217c
parent 05d06f3a48 fdf0c9040a
commit e1453e217c
1 changed files with 205 additions and 205 deletions
--- a/contrib/man/peco.1
+++ b/contrib/man/peco.1
@ -161,13 +161,14 @@ character).
 If this happens, clearing the query and retyping it will produce the
 correct results.
 .PP
-\f[B]Upgrading from v0.5.x:\f[R] This is a breaking change.
-In v0.5.x, a query like \f[V]test -v\f[R] matched lines containing both
-\[lq]test\[rq] and literal \[lq]-v\[rq].
-In v0.6.0, the same query matches \[lq]test\[rq] while
-\f[I]excluding\f[R] lines containing \[lq]v\[rq].
-If you need to search for a literal hyphen-prefixed term, escape it with
-a backslash (e.g.\ \f[V]\[rs]-v\f[R]).
+\f[B]Upgrading from v0.5.x:\f[R] In v0.5.x, a query like
+\f[V]test -v\f[R] matched lines containing both \[lq]test\[rq] and
+literal \[lq]-v\[rq].
+From v0.6.0 onwards, \f[V]-v\f[R] is treated as a negative term, so the
+query matches \[lq]test\[rq] while excluding lines containing
+\[lq]v\[rq].
+To search for a literal hyphen-prefixed term, escape it with a backslash
+(e.g.\ \f[V]\[rs]-v\f[R]).
 .SS Select Multiple Lines
 .PP
 You can select multiple lines!
@ -343,18 +344,25 @@ ls --color=always | peco
 .PP
 To disable ANSI color rendering, use \f[V]--color=none\f[R].
 .PP
-Supported ANSI features: - Basic 8 foreground and background colors
-(30-37, 40-47) - 256-color palette (38;5;N, 48;5;N) - 24-bit truecolor
-(38;2;R;G;B, 48;2;R;G;B) - Bold, underline, and reverse attributes -
-Reset sequences
+peco uses two independent color layers, both supporting 8 named colors,
+256-color, and 24-bit truecolor.
+The first is peco\[cq]s own \f[B]UI styling\f[R] \[em] selection
+highlighting, match highlighting, prompt colors, etc.
+\[em] configured via the \f[V]Style\f[R] section in the config file (see
+Styles).
+UI styling is always active and is not affected by the \f[V]--color\f[R]
+flag.
+The second is \f[B]input ANSI colors\f[R] \[em] escape sequences already
+present in the piped input from tools like \f[V]git log --color\f[R].
+This layer is controlled by the \f[V]--color\f[R] flag described above.
 .PP
-When ANSI color support is enabled: - Filtering and matching operate
+When input ANSI color support is enabled, filtering and matching operate
 against the \f[B]stripped\f[R] (plain text) version of each line, so
-escape codes do not interfere with your queries - ANSI colors are
-displayed as the \f[B]base layer\f[R]; peco\[cq]s own selection and
-match highlighting take precedence over ANSI colors - Selected
-lines\[cq] output preserves the \f[B]original\f[R] ANSI codes, so
-downstream tools receive colored text
+escape codes do not interfere with your queries.
+Input ANSI colors are displayed as the \f[B]base layer\f[R]; peco\[cq]s
+own UI styling takes precedence.
+Selected lines\[cq] output preserves the \f[B]original\f[R] ANSI codes,
+so downstream tools receive colored text.
 .PP
 ANSI color support can be controlled via the configuration file (see
 Color under Global configuration).
@ -392,16 +400,16 @@ Add keybindings in your config file:
 \f[R]
 .fi
 .PP
-Notes: - ZoomIn only works when there is an active filter query.
-If you are viewing the unfiltered source, it is a no-op.
- You cannot zoom in twice \[em] zooming in while already zoomed shows a
+ZoomIn only works when there is an active filter query; if you are
+viewing the unfiltered source, it is a no-op.
+You cannot zoom in twice \[em] zooming in while already zoomed shows a
 status message.
- The cursor position is preserved: after ZoomIn, the cursor stays on
-the same matched line; after ZoomOut, it returns to where it was before
+The cursor position is preserved: after ZoomIn, the cursor stays on the
+same matched line; after ZoomOut, it returns to where it was before
 zooming.
- Context lines cannot be selected \[em] only the original matched lines
+Context lines cannot be selected \[em] only the original matched lines
 participate in selection.
- The \f[V]Context\f[R] style can be customized in the config file (see
+The \f[V]Context\f[R] style can be customized in the config file (see
 Styles).
 .SS Selectable Layout
 .PP
@ -602,10 +610,6 @@ given time, preventing it from exhausting all the memory.
 By default the buffer size is unlimited.
 .SS \[en]null
 .PP
-WARNING: EXPERIMENTAL.
-This feature will probably stay, but the option name may change in the
-future.
-.PP
 Changes how peco interprets incoming data.
 When this flag is set, you may insert NUL (`\[rs]0') characters in your
 input.
@ -676,8 +680,7 @@ When you choose \f[V]error\f[R], peco will exit with a non-zero value.
 .PP
 When specified, peco uses the specified prefix instead of changing line
 color to indicate currently selected line(s).
-default is to use colors.
-This option is experimental.
+Default is to use colors.
 .SS \[en]exec \f[V]string\f[R]
 .PP
 When specified, peco executes the specified external command (via
@ -1169,9 +1172,9 @@ Notes
 T}
 _
 T{
-peco.ForwardChar
+peco.BackToInitialFilter
 T}@T{
-Move caret forward 1 character
+Switch to first filter in the list
 T}
 T{
 peco.BackwardChar
@ -1179,29 +1182,54 @@ T}@T{
 Move caret backward 1 character
 T}
 T{
-peco.ForwardWord
-T}@T{
-Move caret forward 1 word
-T}
-T{
 peco.BackwardWord
 T}@T{
 Move caret backward 1 word
 T}
 T{
-peco.BackToInitialFilter
-T}@T{
-Switch to first filter in the list
-T}
-T{
 peco.BeginningOfLine
 T}@T{
 Move caret to the beginning of line
 T}
 T{
-peco.EndOfLine
+peco.Cancel
 T}@T{
-Move caret to the end of line
+Exits from peco with failure status, or cancel select mode
+T}
+T{
+peco.CancelRangeMode
+T}@T{
+Finish selecting by range and cancel range selection
+T}
+T{
+peco.CancelSelectMode
+T}@T{
+(DEPRECATED) Alias to CancelRangeMode
+T}
+T{
+peco.DeleteAll
+T}@T{
+Delete all entered characters
+T}
+T{
+peco.DeleteBackwardChar
+T}@T{
+Delete one character backward
+T}
+T{
+peco.DeleteBackwardWord
+T}@T{
+Delete one word backward
+T}
+T{
+peco.DeleteForwardChar
+T}@T{
+Delete one character forward
+T}
+T{
+peco.DeleteForwardWord
+T}@T{
+Delete one word forward
 T}
 T{
 peco.EndOfFile
@ -1210,24 +1238,39 @@ Delete one character forward, otherwise exit from peco with failure
 status
 T}
 T{
-peco.DeleteForwardChar
+peco.EndOfLine
 T}@T{
-Delete one character forward
+Move caret to the end of line
 T}
 T{
-peco.DeleteBackwardChar
+peco.Finish
 T}@T{
-Delete one character backward
+Exits from peco with success status
 T}
 T{
-peco.DeleteForwardWord
+peco.ForwardChar
 T}@T{
-Delete one word forward
+Move caret forward 1 character
 T}
 T{
-peco.DeleteBackwardWord
+peco.ForwardWord
 T}@T{
-Delete one word backward
+Move caret forward 1 word
+T}
+T{
+peco.FreezeResults
+T}@T{
+Freeze current results and clear the query to start a new filter on top
+T}
+T{
+peco.GoToNextSelection
+T}@T{
+Jump cursor to the next saved selection
+T}
+T{
+peco.GoToPreviousSelection
+T}@T{
+Jump cursor to the previous saved selection
 T}
 T{
 peco.InvertSelection
@ -1246,25 +1289,30 @@ T}@T{
 Delete the characters under the cursor until the end of the line
 T}
 T{
-peco.DeleteAll
-T}@T{
-Delete all entered characters
-T}
-T{
 peco.RefreshScreen
 T}@T{
 Redraws the screen.
 Note that this effectively re-runs your query
 T}
 T{
-peco.SelectPreviousPage
+peco.RotateFilter
 T}@T{
-(DEPRECATED) Alias to ScrollPageUp
+Rotate between filters (by default, ignore-case/no-ignore-case)
 T}
 T{
-peco.SelectNextPage
+peco.ScrollFirstItem
 T}@T{
-(DEPRECATED) Alias to ScrollPageDown
+Scrolls to the first item (in the entire buffer, not the current screen)
+T}
+T{
+peco.ScrollLastItem
+T}@T{
+Scrolls to the last item (in the entire buffer, not the current screen)
+T}
+T{
+peco.ScrollLeft
+T}@T{
+Scrolls the screen to the left
 T}
 T{
 peco.ScrollPageDown
@ -1277,9 +1325,14 @@ T}@T{
 Moves the selected line cursor for an entire page, upwards
 T}
 T{
-peco.SelectUp
+peco.ScrollRight
 T}@T{
-Moves the selected line cursor to one line above
+Scrolls the screen to the right
+T}
+T{
+peco.SelectAll
+T}@T{
+Selects the all line, and save it
 T}
 T{
 peco.SelectDown
@ -1287,34 +1340,54 @@ T}@T{
 Moves the selected line cursor to one line below
 T}
 T{
-peco.SelectPrevious
-T}@T{
-(DEPRECATED) Alias to SelectUp
-T}
-T{
 peco.SelectNext
 T}@T{
 (DEPRECATED) Alias to SelectDown
 T}
 T{
-peco.ScrollLeft
+peco.SelectNextPage
 T}@T{
-Scrolls the screen to the left
+(DEPRECATED) Alias to ScrollPageDown
 T}
 T{
-peco.ScrollRight
+peco.SelectNone
 T}@T{
-Scrolls the screen to the right
+Remove all saved selections
 T}
 T{
-peco.ScrollFirstItem
+peco.SelectPrevious
 T}@T{
-Scrolls to the first item (in the entire buffer, not the current screen)
+(DEPRECATED) Alias to SelectUp
 T}
 T{
-peco.ScrollLastItem
+peco.SelectPreviousPage
 T}@T{
-Scrolls to the last item (in the entire buffer, not the current screen)
+(DEPRECATED) Alias to ScrollPageUp
+T}
+T{
+peco.SelectUp
+T}@T{
+Moves the selected line cursor to one line above
+T}
+T{
+peco.SelectVisible
+T}@T{
+Selects the all visible line, and save it
+T}
+T{
+peco.ToggleQuery
+T}@T{
+Toggle list between filtered by query and not filtered
+T}
+T{
+peco.ToggleRangeMode
+T}@T{
+Start selecting by range, or append selecting range to selections
+T}
+T{
+peco.ToggleSelectMode
+T}@T{
+(DEPRECATED) Alias to ToggleRangeMode
 T}
 T{
 peco.ToggleSelection
@ -1333,34 +1406,9 @@ Enables SingleKeyJump mode a.k.a.
 \[lq]hit-a-hint\[rq]
 T}
 T{
-peco.SelectNone
+peco.UnfreezeResults
 T}@T{
-Remove all saved selections
-T}
-T{
-peco.SelectAll
-T}@T{
-Selects the all line, and save it
-T}
-T{
-peco.SelectVisible
-T}@T{
-Selects the all visible line, and save it
-T}
-T{
-peco.ToggleSelectMode
-T}@T{
-(DEPRECATED) Alias to ToggleRangeMode
-T}
-T{
-peco.CancelSelectMode
-T}@T{
-(DEPRECATED) Alias to CancelRangeMode
-T}
-T{
-peco.ToggleQuery
-T}@T{
-Toggle list between filtered by query and not filtered.
+Discard frozen results and revert to the original input
 T}
 T{
 peco.ViewAround
@ -1368,41 +1416,6 @@ T}@T{
 Toggle display of context lines around each match
 T}
 T{
-peco.GoToNextSelection
-T}@T{
-Jump cursor to the next saved selection
-T}
-T{
-peco.GoToPreviousSelection
-T}@T{
-Jump cursor to the previous saved selection
-T}
-T{
-peco.ToggleRangeMode
-T}@T{
-Start selecting by range, or append selecting range to selections
-T}
-T{
-peco.CancelRangeMode
-T}@T{
-Finish selecting by range and cancel range selection
-T}
-T{
-peco.RotateFilter
-T}@T{
-Rotate between filters (by default, ignore-case/no-ignore-case)
-T}
-T{
-peco.FreezeResults
-T}@T{
-Freeze current results and clear the query to start a new filter on top
-T}
-T{
-peco.UnfreezeResults
-T}@T{
-Discard frozen results and revert to the original input
-T}
-T{
 peco.ZoomIn
 T}@T{
 Expand filtered results with context lines around each match
@ -1412,16 +1425,6 @@ peco.ZoomOut
 T}@T{
 Collapse back to the filtered view (undo ZoomIn)
 T}
-T{
-peco.Finish
-T}@T{
-Exits from peco with success status
-T}
-T{
-peco.Cancel
-T}@T{
-Exits from peco with failure status, or cancel select mode
-T}
 .TE
 .SS Default Keymap
 .PP
@ -1439,54 +1442,24 @@ Action
 T}
 _
 T{
-Esc
+ArrowDown
 T}@T{
-peco.Cancel
+peco.SelectDown
 T}
 T{
-C-c
+ArrowLeft
 T}@T{
-peco.Cancel
+peco.ScrollPageUp
 T}
 T{
-Enter
+ArrowRight
 T}@T{
-peco.Finish
+peco.ScrollPageDown
 T}
 T{
-C-f
+ArrowUp
 T}@T{
-peco.ForwardChar
-T}
-T{
-C-a
-T}@T{
-peco.BeginningOfLine
-T}
-T{
-C-b
-T}@T{
-peco.BackwardChar
-T}
-T{
-C-d
-T}@T{
-peco.DeleteForwardChar
-T}
-T{
-C-e
-T}@T{
-peco.EndOfLine
-T}
-T{
-C-k
-T}@T{
-peco.KillEndOfLine
-T}
-T{
-C-u
-T}@T{
-peco.KillBeginningOfLine
+peco.SelectUp
 T}
 T{
 BS
@ -1499,9 +1472,39 @@ T}@T{
 peco.DeleteBackwardChar
 T}
 T{
-C-w
+C-Space
 T}@T{
-peco.DeleteBackwardWord
+peco.ToggleSelectionAndSelectNext
+T}
+T{
+C-a
+T}@T{
+peco.BeginningOfLine
+T}
+T{
+C-b
+T}@T{
+peco.BackwardChar
+T}
+T{
+C-c
+T}@T{
+peco.Cancel
+T}
+T{
+C-d
+T}@T{
+peco.DeleteForwardChar
+T}
+T{
+C-e
+T}@T{
+peco.EndOfLine
+T}
+T{
+C-f
+T}@T{
+peco.ForwardChar
 T}
 T{
 C-g
@ -1509,6 +1512,11 @@ T}@T{
 peco.SelectNone
 T}
 T{
+C-k
+T}@T{
+peco.KillEndOfLine
+T}
+T{
 C-n
 T}@T{
 peco.SelectDown
@ -1529,27 +1537,27 @@ T}@T{
 peco.ToggleQuery
 T}
 T{
-C-Space
+C-u
 T}@T{
-peco.ToggleSelectionAndSelectNext
+peco.KillBeginningOfLine
 T}
 T{
-ArrowUp
+C-w
 T}@T{
-peco.SelectUp
+peco.DeleteBackwardWord
 T}
 T{
-ArrowDown
+Enter
 T}@T{
-peco.SelectDown
+peco.Finish
 T}
 T{
-ArrowLeft
+Esc
 T}@T{
-peco.ScrollPageUp
+peco.Cancel
 T}
 T{
-ArrowRight
+Pgdn
 T}@T{
 peco.ScrollPageDown
 T}
@ -1558,11 +1566,6 @@ Pgup
 T}@T{
 peco.ScrollPageUp
 T}
-T{
-Pgdn
-T}@T{
-peco.ScrollPageDown
-T}
 .TE
 .SS Styles
 .PP
@ -1669,9 +1672,6 @@ attribute actually makes the background blink on some
 platforms/environments, e.g.\ linux console, xterm\&...)
 .SS CustomFilter
 .PP
-This is an experimental feature.
-Please note that some details of this specification may change
-.PP
 By default \f[V]peco\f[R] comes with \f[V]IgnoreCase\f[R],
 \f[V]CaseSensitive\f[R], \f[V]SmartCase\f[R], \f[V]IRegexp\f[R],
 \f[V]Regexp\f[R] and \f[V]Fuzzy\f[R] filters, but since v0.1.3, it is