diff --git a/contrib/man/peco.1 b/contrib/man/peco.1 index 4385370..6520e75 100644 --- 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