peco.peco/contrib/man/peco.1

'\" t
.\" Automatically generated by Pandoc 3.1.3
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "PECO" "1" "" "peco" "User Commands"
.hy
.SH peco
.PP
Simplistic interactive filtering tool
.PP
\f[I]NOTE\f[R]: If you are viewing this on GitHub, this document refers
to the state of \f[V]peco\f[R] in whatever current branch you are
viewing, \f[I]not\f[R] necessarily the state of a currently released
version.
Please make sure to checkout the Changes file for features and changes.
.RS
.PP
If you use peco, please consider sponsoring the authors of this project
from the \[lq]Sponsor\[rq] button on the project page at
https://github.com/peco/peco.
Sponsorship plans start at $1 :)
.RE
.SH Description
.PP
\f[V]peco\f[R] (pronounced \f[I]peh-koh\f[R]) is based on a python tool,
percol (https://github.com/mooz/percol).
\f[V]percol\f[R] was darn useful, but I wanted a tool that was a single
binary, and forget about python.
\f[V]peco\f[R] is written in Go, and therefore you can just grab the
binary releases (https://github.com/peco/peco/releases) and drop it in
your $PATH.
.PP
\f[V]peco\f[R] can be a great tool to filter stuff like logs, process
stats, find files, because unlike grep, you can type as you think and
look through the current results.
.PP
For basic usage, continue down below.
For more cool elaborate usage samples, please see the
wiki (https://github.com/peco/peco/wiki/Sample-Usage), and if you have
any other tricks you want to share, please add to it!
.SS Demo
.PP
Demos speak more than a thousand words!
Here\[cq]s me looking for a process on my mac.
As you can see, you can page through your results, and you can keep
changing the query:
[IMAGE: Executed \f[V]ps -ef | peco\f[R], then the query \f[V]root\f[R]
was typed.
This shows all lines containing the word
root (http://peco.github.io/images/peco-demo-ps.gif)]
Executed \f[V]ps -ef | peco\f[R], then the query \f[V]root\f[R] was
typed.
This shows all lines containing the word root
.PP
Here\[cq]s me trying to figure out which file to open:
[IMAGE: Executed \f[V]find . -name \[aq]*.go\[aq] | peco\f[R] (within
camlistore repository), then the query \f[V]camget\f[R] was typed.
This shows all lines including the word
\f[V]camget\f[R] (http://peco.github.io/images/peco-demo-filename.gif)]
Executed \f[V]find . -name \[aq]*.go\[aq] | peco\f[R] (within camlistore
repository), then the query \f[V]camget\f[R] was typed.
This shows all lines including the word \f[V]camget\f[R]
.PP
When you combine tools like zsh, peco, and
ghq (https://github.com/motemen/ghq), you can make managing/moving
around your huge dev area a piece of cake!
(this example doesn\[cq]t use zsh functions so you can see what I\[cq]m
doing)
[IMAGE: Executed
\f[V]cd $(ghq list --full-path | peco --query peco)\f[R] to show all
repositories containing the word \f[V]peco\f[R], then to change
directories into the one
selected (http://peco.github.io/images/peco-demo-ghq.gif)]
Executed \f[V]cd $(ghq list --full-path | peco --query peco)\f[R] to
show all repositories containing the word \f[V]peco\f[R], then to change
directories into the one selected
.SH Features
.SS Incremental Search
.PP
Search results are filtered as you type.
This is great to drill down to the line you are looking for
.PP
Multiple terms turn the query into an \[lq]AND\[rq] query:
[IMAGE: Executed \f[V]ps aux | peco\f[R], then the query
\f[V]root app\f[R] was typed.
This shows all lines containing both \f[V]root\f[R] and
\f[V]app\f[R] (http://peco.github.io/images/peco-demo-multiple-queries.gif)]
Executed \f[V]ps aux | peco\f[R], then the query \f[V]root app\f[R] was
typed.
This shows all lines containing both \f[V]root\f[R] and \f[V]app\f[R]
.PP
When you find that line that you want, press enter, and the resulting
line is printed to stdout, which allows you to pipe it to other tools
.SS Negative Matching
.PP
You can exclude lines from the results by prefixing a term with
\f[V]-\f[R].
For example, the query \f[V]SSO -tests -javadoc\f[R] shows lines
matching \[lq]SSO\[rq] that do NOT contain \[lq]tests\[rq] or
\[lq]javadoc\[rq].
.PP
.TS
tab(@);
l l.
T{
Query
T}@T{
Meaning
T}
_
T{
\f[V]foo -bar\f[R]
T}@T{
Lines matching \[lq]foo\[rq] but not containing \[lq]bar\[rq]
T}
T{
\f[V]-foo -bar\f[R]
T}@T{
All lines not containing \[lq]foo\[rq] or \[lq]bar\[rq]
T}
T{
\f[V]\[rs]-foo\f[R]
T}@T{
Literal match for \[lq]-foo\[rq] (escaped with backslash)
T}
T{
\f[V]-\f[R]
T}@T{
Literal match for a hyphen character
T}
.TE
.PP
Negative matching works with all built-in filters (IgnoreCase,
CaseSensitive, SmartCase, Regexp, IRegexp, and Fuzzy).
For the Fuzzy filter, negative terms use regexp-based exclusion rather
than fuzzy matching.
External custom filters receive the query as-is and are responsible for
their own parsing.
.PP
Only positive terms produce match highlighting.
Lines matched solely by negative exclusion (e.g.\ an all-negative query
like \f[V]-foo\f[R]) are shown without highlighting.
.PP
\f[B]Note:\f[R] When using the SmartCase filter with negative terms,
results may be incomplete if the query transitions from all-lowercase to
mixed-case (e.g.\ typing \f[V]foo -bar\f[R] then adding an uppercase
character).
If this happens, clearing the query and retyping it will produce the
correct results.
.SS Select Multiple Lines
.PP
You can select multiple lines!
(this example uses C-Space)
[IMAGE: Executed \f[V]ls -l | peco\f[R], then used peco.ToggleSelection
to select multiple
lines (http://peco.github.io/images/peco-demo-multiple-selection.gif)]
Executed \f[V]ls -l | peco\f[R], then used peco.ToggleSelection to
select multiple lines
.SS Select Range Of Lines
.PP
Not only can you select multiple lines one by one, you can select a
range of lines (Note: The ToggleRangeMode action is not enabled by
default.
You need to put a custom key binding in your config file)
[IMAGE: Executed \f[V]ps -ef | peco\f[R], then used peco.ToggleRangeMode
to select a range of
lines (http://peco.github.io/images/peco-demo-range-mode.gif)]
Executed \f[V]ps -ef | peco\f[R], then used peco.ToggleRangeMode to
select a range of lines
.SS Select Filters
.PP
Different types of filters are available.
Default is case-insensitive filter, so lines with any case will match.
You can toggle between IgnoreCase, CaseSensitive, SmartCase, Regexp case
insensitive, Regexp and Fuzzy filters.
.PP
The SmartCase filter uses case-\f[I]insensitive\f[R] matching when all
of the queries are lower case, and case-\f[I]sensitive\f[R] matching
otherwise.
.PP
The Regexp filter allows you to use any valid regular expression to
match lines.
.PP
The Fuzzy filter allows you to find matches using partial patterns.
For example, when searching for \f[V]ALongString\f[R], you can enable
the Fuzzy filter and search \f[V]ALS\f[R] to find it.
The Fuzzy filter uses smart case search like the SmartCase filter.
With the \f[V]FuzzyLongestSort\f[R] flag enabled in the configuration
file, it does a smarter match.
It sorts the matched lines by the following precedence: 1.
longer substring, 2.
earlier (left positioned) substring, and 3.
shorter line.
[IMAGE: Executed \f[V]ps aux | peco\f[R], then typed \f[V]google\f[R],
which matches the Chrome.app under IgnoreCase filter type.
When you change it to Regexp filter, this is no longer the case.
But you can type \f[V](?i)google\f[R] instead to toggle case-insensitive
mode (http://peco.github.io/images/peco-demo-matcher.gif)]
Executed \f[V]ps aux | peco\f[R], then typed \f[V]google\f[R], which
matches the Chrome.app under IgnoreCase filter type.
When you change it to Regexp filter, this is no longer the case.
But you can type \f[V](?i)google\f[R] instead to toggle case-insensitive
mode
.SS Multi-Stage Filtering (Freeze Results)
.PP
You can \[lq]freeze\[rq] the current filter results, clear the query,
and continue filtering on top of the frozen results.
This enables multi-stage filtering workflows \[en] for example, first
filter by file extension, freeze, then filter by filename.
.PP
Use \f[V]peco.FreezeResults\f[R] to snapshot the current results and
clear the query.
Use \f[V]peco.UnfreezeResults\f[R] to discard the frozen results and
revert to the original input.
These actions are \f[B]not bound to any key by default\f[R] \[en] you
need to add keybindings in your config file:
.IP
.nf
\f[C]
{
    \[dq]Keymap\[dq]: {
        \[dq]M-f\[dq]: \[dq]peco.FreezeResults\[dq],
        \[dq]M-u\[dq]: \[dq]peco.UnfreezeResults\[dq]
    }
}
\f[R]
.fi
.PP
You can freeze multiple times to progressively narrow down results.
Unfreezing always reverts back to the original unfiltered input.
.PP
\f[B]Example:\f[R] Given this input via \f[V]ls | peco\f[R]:
.IP
.nf
\f[C]
QUERY>
app.go
app_test.go
filter.go
filter_test.go
main.go
readme.md
\f[R]
.fi
.PP
Type \f[V]_test\f[R] to filter:
.IP
.nf
\f[C]
QUERY> _test
app_test.go
filter_test.go
\f[R]
.fi
.PP
Press \f[V]M-f\f[R] to freeze.
The two test files become the new base and the query clears:
.IP
.nf
\f[C]
QUERY>
app_test.go
filter_test.go
\f[R]
.fi
.PP
Now type \f[V]filter\f[R] to search within the frozen results:
.IP
.nf
\f[C]
QUERY> filter
filter_test.go
\f[R]
.fi
.PP
Press \f[V]Enter\f[R] to select \f[V]filter_test.go\f[R], or press
\f[V]M-u\f[R] to unfreeze and return to the original full list.
.SS Horizontal Scrolling
.PP
When input lines are longer than the terminal width, they are clipped at
the edge of the screen.
You can scroll horizontally to reveal the rest of the line using the
\f[V]peco.ScrollLeft\f[R] and \f[V]peco.ScrollRight\f[R] actions.
These actions are \f[B]not bound to any key by default\f[R] \[en] you
need to add keybindings in your config file:
.IP
.nf
\f[C]
{
    \[dq]Keymap\[dq]: {
        \[dq]ArrowLeft\[dq]: \[dq]peco.ScrollLeft\[dq],
        \[dq]ArrowRight\[dq]: \[dq]peco.ScrollRight\[dq]
    }
}
\f[R]
.fi
.PP
Each scroll moves by half the terminal width.
.PP
If your input contains very long lines (e.g.\ minified files) and they
do not appear at all, try increasing \f[V]MaxScanBufferSize\f[R] in your
config.
The default is 256 (KB), which limits the maximum length of a single
input line.
.SS ANSI Color Support
.PP
When the \f[V]--ansi\f[R] flag is enabled, peco parses ANSI SGR (Select
Graphic Rendition) escape sequences from the input and renders the
original colors in the terminal.
This lets you pipe colored output from tools like
\f[V]git log --color\f[R], \f[V]rg --color=always\f[R], or
\f[V]ls --color\f[R] through peco while preserving the visual
formatting.
.IP
.nf
\f[C]
git log --color=always | peco --ansi
rg --color=always pattern | peco --ansi
ls --color=always | peco --ansi
\f[R]
.fi
.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
.PP
When ANSI mode 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
.PP
ANSI mode can also be enabled permanently via the configuration file
(see ANSI under Global configuration).
.SS Context Lines (Zoom In/Out)
.PP
When filtering results (e.g.\ searching for \[lq]error\[rq] in a log
file), you often need to see the surrounding lines to understand the
context.
peco supports expanding filtered results to show context lines around
each match, similar to \f[V]grep -C\f[R].
.PP
Two actions are available:
.IP \[bu] 2
\f[B]\f[VB]peco.ZoomIn\f[B]\f[R] \[em] Expands the current filtered view
by showing 3 lines of context (before and after) around every matched
line.
Overlapping context ranges are merged automatically.
Context lines are displayed with the \f[V]Context\f[R] style (bold by
default) to visually distinguish them from matched lines.
.IP \[bu] 2
\f[B]\f[VB]peco.ZoomOut\f[B]\f[R] \[em] Collapses back to the original
filtered view, restoring the cursor position.
.PP
These actions are \f[B]not bound to any key by default\f[R].
Add keybindings in your config file:
.IP
.nf
\f[C]
{
    \[dq]Keymap\[dq]: {
        \[dq]C-o\[dq]: \[dq]peco.ZoomIn\[dq],
        \[dq]C-i\[dq]: \[dq]peco.ZoomOut\[dq]
    }
}
\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
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
zooming.
- 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
Styles).
.SS Selectable Layout
.PP
As of v0.2.5, if you would rather not move your eyes off of the bottom
of the screen, you can change the screen layout by either providing the
\f[V]--layout=bottom-up\f[R] command line option, or set the
\f[V]Layout\f[R] variable in your configuration file
[IMAGE: Executed \f[V]ps -ef | peco --layout=bottom-up\f[R] to toggle
inverted layout
mode (http://peco.github.io/images/peco-demo-layout-bottom-up.gif)]
Executed \f[V]ps -ef | peco --layout=bottom-up\f[R] to toggle inverted
layout mode
.SS Inline Mode (\[en]height)
.PP
By default peco takes over the entire terminal screen using the
alternate screen buffer.
With \f[V]--height\f[R], peco renders inline at the bottom of the
terminal, preserving your scroll history above.
This is similar to fzf\[cq]s \f[V]--height\f[R] option.
.IP
.nf
\f[C]
# Render with 5 result lines at the bottom of the terminal
ls | peco --height 5

# Use 40% of the terminal height
ls | peco --height 40%
\f[R]
.fi
.PP
All layout modes (\f[V]top-down\f[R], \f[V]bottom-up\f[R],
\f[V]top-down-query-bottom\f[R]) work with \f[V]--height\f[R].
See \[en]height for details.
.SS Works on Windows!
.PP
I have been told that peco even works on windows :) Look ma!
I\[cq]m not lying!
[IMAGE: Showing peco running on Windows
cmd.exe (https://gist.githubusercontent.com/taichi/26814518d8b00352693b/raw/b7745987de32dbf068e81a8308c0c5ed38138649/peco.gif)]
Showing peco running on Windows cmd.exe
.SH Installation
.SS Just want the binary?
.PP
Go to the releases page (https://github.com/peco/peco/releases), find
the version you want, and download the zip file.
Unpack the zip file, and put the binary to somewhere you want (on UNIX-y
systems, /usr/local/bin or the like).
Make sure it has execution bits turned on.
Yes, it is a single binary!
You can put it anywhere you want :)
.PP
\f[I]THIS IS THE RECOMMENDED WAY\f[R] (except for macOS homebrew users)
.SS macOS (Homebrew, Scarf)
.PP
If you\[cq]re on macOS and want to use homebrew:
.IP
.nf
\f[C]
brew install peco
\f[R]
.fi
.PP
or with Scarf:
.IP
.nf
\f[C]
scarf install peco
\f[R]
.fi
.SS Debian and Ubuntu based distributions (APT, Scarf)
.PP
There is an official Debian package that can be installed via APT:
.IP
.nf
\f[C]
apt install peco
\f[R]
.fi
.PP
or with Scarf:
.IP
.nf
\f[C]
scarf install peco
\f[R]
.fi
.SS Void Linux (XBPS)
.IP
.nf
\f[C]
xbps-install -S peco
\f[R]
.fi
.SS Arch Linux
.PP
There is an official Arch Linux package that can be installed via
\f[V]pacman\f[R]:
.IP
.nf
\f[C]
pacman -Syu peco
\f[R]
.fi
.SS Windows (Chocolatey NuGet Users)
.PP
There\[cq]s a third-party peco package
available (https://chocolatey.org/packages/peco) for Chocolatey NuGet.
.IP
.nf
\f[C]
C:\[rs]> choco install peco
\f[R]
.fi
.SS X-CMD (Linux, macOS, Windows WSL, Windows GitBash)
.PP
peco is available from x-cmd (https://www.x-cmd.com).
.PP
To install peco, run:
.IP
.nf
\f[C]
x env use peco
\f[R]
.fi
.SS Linux / macOS / Windows (Conda, Mamba, Pixi)
.PP
\f[V]conda\f[R], \f[V]mamba\f[R] and \f[V]pixi\f[R] are
platform-agnostic package managers for conda-format packages.
.PP
This means that the same command can be used to install peco across
Windows, MacOS, and Linux.
.IP
.nf
\f[C]
# conda
conda install -c conda-forge peco

# mamba
mamba install -c conda-forge peco

# install user-globally using pixi
pixi global install peco
\f[R]
.fi
.SS Using go install
.PP
If you have a Go toolchain installed, you can install peco with:
.IP
.nf
\f[C]
go install github.com/peco/peco/cmd/peco\[at]latest
\f[R]
.fi
.SS Building peco yourself
.PP
Clone the repository and run:
.IP
.nf
\f[C]
make build
\f[R]
.fi
.PP
This will build the binary into
\f[V]releases/peco_<os>_<arch>/peco\f[R].
Copy it to somewhere in your \f[V]$PATH\f[R].
.SH Command Line Options
.SS -h, \[en]help
.PP
Display a help message
.SS \[en]version
.PP
Display the version of peco
.SS \[en]query 
.PP
Specifies the default query to be used upon startup.
This is useful for scripts and functions where you can figure out
beforehand what the most likely query string is.
.SS \[en]print-query
.PP
When exiting, prints out the query typed by the user as the first line
of output.
The query will be printed even if there are no matches, if the program
is terminated normally (i.e.\ enter key).
On the other hand, the query will NOT be printed if the user exits via a
cancel (i.e.\ esc key).
.SS \[en]rcfile 
.PP
Pass peco a configuration file, which currently must be a JSON file.
If unspecified it will try a series of files by default.
See \f[V]Configuration File\f[R] for the actual locations searched.
.SS -b, \[en]buffer-size 
.PP
Limits the buffer size to \f[V]num\f[R].
This is an important feature when you are using peco against a possibly
infinite stream, as it limits the number of lines that peco holds at any
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.
Anything before the NUL character is treated as the string to be
displayed by peco and is used for matching against user query.
Anything after the NUL character is used as the \[lq]result\[rq]: i.e.,
when peco is about to exit, it displays this string instead of the
original string displayed.
.PP
Here\[cq]s a simple example of how to use this
feature (https://gist.github.com/mattn/3c7a14c1677ecb193acd)
.SS \[en]initial-index
.PP
Specifies the initial line position upon start up.
E.g.
If you want to start out with the second line selected, set it to
\[lq]1\[rq] (because the index is 0 based).
.SS \[en]initial-filter \f[V]IgnoreCase|CaseSensitive|SmartCase|IRegexp|Regexp|Fuzzy\f[R]
.PP
Specifies the initial filter to use upon start up.
You should specify the name of the filter like \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].
Default is \f[V]IgnoreCase\f[R].
.SS \[en]prompt
.PP
Specifies the query line\[cq]s prompt string.
When specified, takes precedence over the configuration file\[cq]s
\f[V]Prompt\f[R] section.
The default value is \f[V]QUERY>\f[R].
.SS \[en]layout \f[V]top-down|bottom-up|top-down-query-bottom\f[R]
.PP
Specifies the display layout.
Default is \f[V]top-down\f[R], where query prompt is at the top,
followed by the list, then the system status message line.
\f[V]bottom-up\f[R] changes this to the list first (displayed in reverse
order), the query prompt, and then the system status message line.
\f[V]top-down-query-bottom\f[R] places the list at the top with the
query prompt at the bottom.
.PP
For \f[V]percol\f[R] users, \f[V]--layout=bottom-up\f[R] is almost
equivalent of \f[V]--prompt-bottom --result-bottom-up\f[R].
.SS \[en]select-1
.PP
When specified \f[I]and\f[R] the input contains exactly 1 line, peco
skips prompting you for a choice, and selects the only line in the input
and immediately exits.
.PP
If there are multiple lines in the input, the usual selection view is
displayed.
.SS \[en]exit-0
.PP
When specified and the input is empty (zero lines), peco exits
immediately with status 1 without displaying the selection view.
.SS \[en]select-all
.PP
When specified, peco selects all input lines and immediately exits
without displaying the selection view.
.SS \[en]on-cancel \f[V]success|error\f[R]
.PP
Specifies the exit status to use when the user cancels the query
execution.
For historical and back-compatibility reasons, the default is
\f[V]success\f[R], meaning if the user cancels the query, the exit
status is 0.
When you choose \f[V]error\f[R], peco will exit with a non-zero value.
.SS \[en]selection-prefix \f[V]string\f[R]
.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.
.SS \[en]exec \f[V]string\f[R]
.PP
When specified, peco executes the specified external command (via
shell), with peco\[cq]s currently selected line(s) as its input from
STDIN.
.PP
Upon exiting from the external command, the control goes back to peco
where you can keep browsing your search buffer, and to possibly execute
your external command repeatedly afterwards.
.PP
To exit out of peco when running in this mode, you must execute the
Cancel command, usually the escape key.
.SS \[en]ansi
.PP
Enables ANSI color code support.
When this flag is set, peco parses ANSI SGR escape sequences from the
input and renders the colors in the terminal UI.
Filtering is performed against the plain text with ANSI codes stripped,
and selected output preserves the original ANSI codes.
.PP
See ANSI Color Support in the Features section for details.
.SS \[en]height \f[V]num|percentage\f[R]
.PP
When specified, peco renders inline at the bottom of the terminal using
only the requested number of lines, instead of taking over the full
screen.
This preserves your terminal scroll history above the peco interface.
.PP
The value can be:
.IP \[bu] 2
An absolute number of \f[B]result lines\f[R]
(e.g.\ \f[V]--height 5\f[R]).
The prompt and status bar are added automatically, so
\f[V]--height 5\f[R] uses 7 terminal rows total (5 result lines + prompt
+ status bar).
.IP \[bu] 2
A percentage of the terminal height (e.g.\ \f[V]--height 50%\f[R]).
This refers to the total height including prompt and status bar.
.PP
The minimum effective height is 3 rows (1 result line + prompt + status
bar).
Values that exceed the terminal height are clamped.
.IP
.nf
\f[C]
# Show 5 result lines inline
ls | peco --height 5

# Use 40% of the terminal
ls | peco --height 40%
\f[R]
.fi
.PP
Without \f[V]--height\f[R], peco uses the full terminal screen (default
behavior, unchanged).
.PP
\f[B]Note:\f[R] In inline mode, peco sets the environment variable
\f[V]TCELL_ALTSCREEN=disable\f[R] to prevent tcell from using the
alternate screen buffer, and restores the original value on exit.
If peco is killed abnormally (e.g.\ \f[V]SIGKILL\f[R]), you may need to
unset this variable manually: \f[V]unset TCELL_ALTSCREEN\f[R].
.SH Configuration File
.PP
peco by default consults a few locations for the config files.
.IP "1." 3
Location specified in \[en]rcfile.
If this doesn\[cq]t exist, peco complains and exits
.IP "2." 3
$XDG_CONFIG_HOME/peco/config.json
.IP "3." 3
$HOME/.config/peco/config.json
.IP "4." 3
for each directory listed in $XDG_CONFIG_DIRS, $DIR/peco/config.json
.IP "5." 3
If all else fails, $HOME/.peco/config.json
.PP
Below are configuration sections that you may specify in your config
file:
.IP \[bu] 2
Global
.IP \[bu] 2
Keymaps
.IP \[bu] 2
Styles
.IP \[bu] 2
CustomFilter
.IP \[bu] 2
Prompt
.IP \[bu] 2
ANSI
.SS Global
.PP
Global configurations that change the global behavior.
.SS Prompt
.PP
You can change the query line\[cq]s prompt, which is \f[V]QUERY>\f[R] by
default.
.IP
.nf
\f[C]
{
    \[dq]Prompt\[dq]: \[dq][peco]\[dq]
}
\f[R]
.fi
.SS InitialFilter
.PP
Specifies the filter name to start peco with.
You should specify the name of the filter, such as \f[V]IgnoreCase\f[R],
\f[V]CaseSensitive\f[R], \f[V]SmartCase\f[R], \f[V]Regexp\f[R] and
\f[V]Fuzzy\f[R].
.SS FuzzyLongestSort
.PP
Enables the longest substring match and sorts the output.
It affects only the Fuzzy filter.
.PP
Default value for FuzzyLongestSort is false.
.SS StickySelection
.IP
.nf
\f[C]
{
    \[dq]StickySelection\[dq]: true
}
\f[R]
.fi
.PP
StickySelection allows selections to persist even between changes to the
query.
For example, when you set this to true you can select a few lines, type
in a new query, select those lines, and then delete the query.
The result is all the lines that you selected before and after the
modification to the query are left intact.
.PP
Default value for StickySelection is false.
.SS SuppressStatusMsg
.IP
.nf
\f[C]
{
    \[dq]SuppressStatusMsg\[dq]: true
}
\f[R]
.fi
.PP
SuppressStatusMsg suppresses the status message bar at the bottom of the
screen.
When set to true, messages like \[lq]Running query\&...\[rq] will not be
displayed.
.PP
Default value for SuppressStatusMsg is false.
.SS OnCancel
.IP
.nf
\f[C]
{
    \[dq]OnCancel\[dq]: \[dq]error\[dq]
}
\f[R]
.fi
.PP
OnCancel is equivalent to \f[V]--on-cancel\f[R] command line option.
.SS MaxScanBufferSize
.IP
.nf
\f[C]
{
    \[dq]MaxScanBufferSize\[dq]: 256
}
\f[R]
.fi
.PP
Controls the buffer sized (in kilobytes) used by
\f[V]bufio.Scanner\f[R], which is responsible for reading the input
lines.
If you believe that your input has very long lines that prohibit peco
from reading them, try increasing this number.
.PP
The same time, the default MaxScanBuferSize is 256kb.
.SS ANSI
.IP
.nf
\f[C]
{
    \[dq]ANSI\[dq]: true
}
\f[R]
.fi
.PP
Enables ANSI color code support.
When set to \f[V]true\f[R], peco parses and renders ANSI SGR escape
sequences from the input.
This is equivalent to using the \f[V]--ansi\f[R] command line flag.
The command line flag takes precedence if both are specified.
.PP
Default value for ANSI is \f[V]false\f[R].
.PP
See ANSI Color Support in the Features section for details.
.SS Height
.IP
.nf
\f[C]
{
    \[dq]Height\[dq]: \[dq]10\[dq]
}
\f[R]
.fi
.PP
\f[V]Height\f[R] is equivalent to using \f[V]--height\f[R] on the
command line.
When set, peco renders inline at the bottom of the terminal instead of
using the full screen.
The value is the number of result lines (e.g.\ \f[V]\[dq]10\[dq]\f[R])
or a percentage of terminal height (e.g.\ \f[V]\[dq]50%\[dq]\f[R]).
The command line \f[V]--height\f[R] option takes precedence over this
config value.
.SS Keymaps
.PP
Example:
.IP
.nf
\f[C]
{
    \[dq]Keymap\[dq]: {
        \[dq]M-v\[dq]: \[dq]peco.ScrollPageUp\[dq],
        \[dq]C-v\[dq]: \[dq]peco.ScrollPageDown\[dq],
        \[dq]C-x,C-c\[dq]: \[dq]peco.Cancel\[dq]
    }
}
\f[R]
.fi
.SS Key sequences
.PP
As of v0.2.0, you can use a list of keys (separated by comma) to
register an action that is associated with a key sequence (instead of a
single key).
Please note that if there is a conflict in the key map, \f[I]the longest
sequence always wins\f[R].
So In the above example, if you add another sequence, say,
\f[V]C-x,C-c,C-c\f[R], then the above \f[V]peco.Cancel\f[R] will never
be invoked.
.SS Combined actions
.PP
As of v0.2.1, you can create custom combined actions.
For example, if you find yourself repeatedly needing to select 4 lines
out of the list, you may want to define your own action like this:
.IP
.nf
\f[C]
{
    \[dq]Action\[dq]: {
        \[dq]foo.SelectFour\[dq]: [
            \[dq]peco.ToggleRangeMode\[dq],
            \[dq]peco.SelectDown\[dq],
            \[dq]peco.SelectDown\[dq],
            \[dq]peco.SelectDown\[dq],
            \[dq]peco.ToggleRangeMode\[dq]
        ]
    },
    \[dq]Keymap\[dq]: {
        \[dq]M-f\[dq]: \[dq]foo.SelectFour\[dq]
    }
}
\f[R]
.fi
.PP
This creates a new combined action \f[V]foo.SelectFour\f[R] (the format
of the name is totally arbitrary, I just like to put namespaces), and
assigns that action to \f[V]M-f\f[R].
When it\[cq]s fired, it toggles the range selection mode and highlights
4 lines, and then goes back to waiting for your input.
.PP
As a similar example, a common idiom in emacs is that \f[V]C-c C-c\f[R]
means \[lq]take the contents of this buffer and accept it\[rq], whatever
that means.
This adds exactly that keybinding:
.IP
.nf
\f[C]
{
    \[dq]Action\[dq]: {
        \[dq]selectAllAndFinish\[dq]: [
            \[dq]peco.SelectAll\[dq],
            \[dq]peco.Finish\[dq]
        ]
    },
    \[dq]Keymap\[dq]: {
        \[dq]C-c,C-c\[dq]: \[dq]selectAllAndFinish\[dq]
    }
}
\f[R]
.fi
.SS Available keys
.PP
Since v0.1.8, in addition to values below, you may put a \f[V]M-\f[R]
prefix on any key item to use Alt/Option key as a mask.
.PP
You can also use \f[V]C-\f[R] and \f[V]S-\f[R] prefixes on navigation
keys to bind Ctrl and Shift modified keys.
Multiple modifiers can be combined.
For example:
.IP
.nf
\f[C]
{
    \[dq]Keymap\[dq]: {
        \[dq]C-ArrowLeft\[dq]: \[dq]peco.BackwardWord\[dq],
        \[dq]C-ArrowRight\[dq]: \[dq]peco.ForwardWord\[dq],
        \[dq]S-ArrowUp\[dq]: \[dq]peco.SelectUp\[dq],
        \[dq]C-M-Delete\[dq]: \[dq]peco.DeleteForwardWord\[dq]
    }
}
\f[R]
.fi
.PP
Note: \f[V]C-\f[R] on single characters (e.g.\ \f[V]C-a\f[R]) refers to
ASCII control codes as before.
\f[V]C-\f[R] as a modifier applies to navigation keys such as
\f[V]ArrowLeft\f[R], \f[V]Home\f[R], \f[V]Delete\f[R], etc.
.PP
.TS
tab(@);
l l.
T{
Name
T}@T{
Notes
T}
_
T{
C-a \&...
C-z
T}@T{
Control + whatever character
T}
T{
C-2 \&...
C-8
T}@T{
Control + 2..8
T}
T{
C-[
T}@T{
T}
T{
C-]
T}@T{
T}
T{
C-\[ti]
T}@T{
T}
T{
C-_
T}@T{
T}
T{
C-\[rs]\[rs]
T}@T{
Note that you need to escape the backslash
T}
T{
C-/
T}@T{
T}
T{
C-Space
T}@T{
T}
T{
F1 \&...
F12
T}@T{
T}
T{
Esc
T}@T{
T}
T{
Tab
T}@T{
T}
T{
Enter
T}@T{
T}
T{
Insert
T}@T{
T}
T{
Delete
T}@T{
T}
T{
BS
T}@T{
T}
T{
BS2
T}@T{
T}
T{
Home
T}@T{
T}
T{
End
T}@T{
T}
T{
Pgup
T}@T{
T}
T{
Pgdn
T}@T{
T}
T{
ArrowUp
T}@T{
T}
T{
ArrowDown
T}@T{
T}
T{
ArrowLeft
T}@T{
T}
T{
ArrowRight
T}@T{
T}
T{
MouseLeft
T}@T{
T}
T{
MouseMiddle
T}@T{
T}
T{
MouseRight
T}@T{
T}
.TE
.SS Key workarounds
.PP
Some keys just\&...
don\[cq]t map correctly / too easily for various reasons.
Here, we\[cq]ll list possible workarounds for key sequences that are
often asked for:
.PP
.TS
tab(@);
l l l.
T{
You want this
T}@T{
Use this instead
T}@T{
Notes
T}
_
T{
Shift+Tab
T}@T{
M-[,Z
T}@T{
Verified on macOS
T}
.TE
.PP
\f[B]Note:\f[R] Due to the tcell migration, Shift+Tab is internally
mapped to Tab.
If you need a distinct Shift+Tab binding, use the \f[V]M-[,Z\f[R] key
sequence in your config instead.
.SS Available actions
.PP
.TS
tab(@);
lw(32.3n) lw(37.7n).
T{
Name
T}@T{
Notes
T}
_
T{
peco.ForwardChar
T}@T{
Move caret forward 1 character
T}
T{
peco.BackwardChar
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
T}@T{
Move caret to the end of line
T}
T{
peco.EndOfFile
T}@T{
Delete one character forward, otherwise exit from peco with failure
status
T}
T{
peco.DeleteForwardChar
T}@T{
Delete one character forward
T}
T{
peco.DeleteBackwardChar
T}@T{
Delete one character backward
T}
T{
peco.DeleteForwardWord
T}@T{
Delete one word forward
T}
T{
peco.DeleteBackwardWord
T}@T{
Delete one word backward
T}
T{
peco.InvertSelection
T}@T{
Inverts the selected lines
T}
T{
peco.KillBeginningOfLine
T}@T{
Delete the characters under the cursor backward until the beginning of
the line
T}
T{
peco.KillEndOfLine
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
T}@T{
(DEPRECATED) Alias to ScrollPageUp
T}
T{
peco.SelectNextPage
T}@T{
(DEPRECATED) Alias to ScrollPageDown
T}
T{
peco.ScrollPageDown
T}@T{
Moves the selected line cursor for an entire page, downwards
T}
T{
peco.ScrollPageUp
T}@T{
Moves the selected line cursor for an entire page, upwards
T}
T{
peco.SelectUp
T}@T{
Moves the selected line cursor to one line above
T}
T{
peco.SelectDown
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
T}@T{
Scrolls the screen to the left
T}
T{
peco.ScrollRight
T}@T{
Scrolls the screen to the right
T}
T{
peco.ScrollFirstItem
T}@T{
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.ToggleSelection
T}@T{
Selects the current line, and saves it
T}
T{
peco.ToggleSelectionAndSelectNext
T}@T{
Selects the current line, saves it, and proceeds to the next line
T}
T{
peco.ToggleSingleKeyJump
T}@T{
Enables SingleKeyJump mode a.k.a.
\[lq]hit-a-hint\[rq]
T}
T{
peco.SelectNone
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.
T}
T{
peco.ViewAround
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
T}
T{
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
Note: If in case below keymap seems wrong, check the source code in
keymap.go (https://github.com/peco/peco/blob/master/keymap.go) (look for
NewKeymap).
.PP
.TS
tab(@);
l l.
T{
Key
T}@T{
Action
T}
_
T{
Esc
T}@T{
peco.Cancel
T}
T{
C-c
T}@T{
peco.Cancel
T}
T{
Enter
T}@T{
peco.Finish
T}
T{
C-f
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
T}
T{
BS
T}@T{
peco.DeleteBackwardChar
T}
T{
C-8
T}@T{
peco.DeleteBackwardChar
T}
T{
C-w
T}@T{
peco.DeleteBackwardWord
T}
T{
C-g
T}@T{
peco.SelectNone
T}
T{
C-n
T}@T{
peco.SelectDown
T}
T{
C-p
T}@T{
peco.SelectUp
T}
T{
C-r
T}@T{
peco.RotateFilter
T}
T{
C-t
T}@T{
peco.ToggleQuery
T}
T{
C-Space
T}@T{
peco.ToggleSelectionAndSelectNext
T}
T{
ArrowUp
T}@T{
peco.SelectUp
T}
T{
ArrowDown
T}@T{
peco.SelectDown
T}
T{
ArrowLeft
T}@T{
peco.ScrollPageUp
T}
T{
ArrowRight
T}@T{
peco.ScrollPageDown
T}
T{
Pgup
T}@T{
peco.ScrollPageUp
T}
T{
Pgdn
T}@T{
peco.ScrollPageDown
T}
.TE
.SS Styles
.PP
Styles can be customized in \f[V]config.json\f[R].
.IP
.nf
\f[C]
{
    \[dq]Style\[dq]: {
        \[dq]Basic\[dq]: [\[dq]on_default\[dq], \[dq]default\[dq]],
        \[dq]SavedSelection\[dq]: [\[dq]bold\[dq], \[dq]on_yellow\[dq], \[dq]white\[dq]],
        \[dq]Selected\[dq]: [\[dq]underline\[dq], \[dq]on_cyan\[dq], \[dq]black\[dq]],
        \[dq]Query\[dq]: [\[dq]yellow\[dq], \[dq]bold\[dq]],
        \[dq]QueryCursor\[dq]: [\[dq]white\[dq], \[dq]on_red\[dq]],
        \[dq]Matched\[dq]: [\[dq]red\[dq], \[dq]on_blue\[dq]],
        \[dq]Prompt\[dq]: [\[dq]green\[dq], \[dq]bold\[dq]],
        \[dq]Context\[dq]: [\[dq]bold\[dq]]
    }
}
\f[R]
.fi
.IP \[bu] 2
\f[V]Basic\f[R] for not selected lines
.IP \[bu] 2
\f[V]SavedSelection\f[R] for lines of saved selection
.IP \[bu] 2
\f[V]Selected\f[R] for a currently selecting line
.IP \[bu] 2
\f[V]Query\f[R] for a query line
.IP \[bu] 2
\f[V]QueryCursor\f[R] for the cursor on the query line.
If not specified, the cursor colors are derived automatically: when
\f[V]Query\f[R] has custom colors, they are swapped (fg becomes bg and
vice versa); otherwise, the terminal\[cq]s reverse video attribute is
used.
.IP \[bu] 2
\f[V]Matched\f[R] for a query matched word
.IP \[bu] 2
\f[V]Prompt\f[R] for the query prompt prefix (e.g., \f[V]QUERY>\f[R])
.IP \[bu] 2
\f[V]Context\f[R] for context lines shown by ZoomIn (default: bold)
.SS Foreground Colors
.IP \[bu] 2
\f[V]\[dq]default\[dq]\f[R] for the terminal\[cq]s default foreground
color
.IP \[bu] 2
\f[V]\[dq]black\[dq]\f[R] for \f[V]tcell.ColorBlack\f[R]
.IP \[bu] 2
\f[V]\[dq]red\[dq]\f[R] for \f[V]tcell.ColorRed\f[R]
.IP \[bu] 2
\f[V]\[dq]green\[dq]\f[R] for \f[V]tcell.ColorGreen\f[R]
.IP \[bu] 2
\f[V]\[dq]yellow\[dq]\f[R] for \f[V]tcell.ColorYellow\f[R]
.IP \[bu] 2
\f[V]\[dq]blue\[dq]\f[R] for \f[V]tcell.ColorBlue\f[R]
.IP \[bu] 2
\f[V]\[dq]magenta\[dq]\f[R] for \f[V]tcell.ColorMagenta\f[R]
.IP \[bu] 2
\f[V]\[dq]cyan\[dq]\f[R] for \f[V]tcell.ColorCyan\f[R]
.IP \[bu] 2
\f[V]\[dq]white\[dq]\f[R] for \f[V]tcell.ColorWhite\f[R]
.IP \[bu] 2
\f[V]\[dq]0\[dq]\f[R]-\f[V]\[dq]255\[dq]\f[R] for 256color
(automatically supported via tcell)
.IP \[bu] 2
\f[V]\[dq]#RRGGBB\[dq]\f[R] for 24-bit truecolor
(e.g.\ \f[V]\[dq]#ff6600\[dq]\f[R])
.SS Background Colors
.IP \[bu] 2
\f[V]\[dq]on_default\[dq]\f[R] for the terminal\[cq]s default background
color
.IP \[bu] 2
\f[V]\[dq]on_black\[dq]\f[R] for \f[V]tcell.ColorBlack\f[R]
.IP \[bu] 2
\f[V]\[dq]on_red\[dq]\f[R] for \f[V]tcell.ColorRed\f[R]
.IP \[bu] 2
\f[V]\[dq]on_green\[dq]\f[R] for \f[V]tcell.ColorGreen\f[R]
.IP \[bu] 2
\f[V]\[dq]on_yellow\[dq]\f[R] for \f[V]tcell.ColorYellow\f[R]
.IP \[bu] 2
\f[V]\[dq]on_blue\[dq]\f[R] for \f[V]tcell.ColorBlue\f[R]
.IP \[bu] 2
\f[V]\[dq]on_magenta\[dq]\f[R] for \f[V]tcell.ColorMagenta\f[R]
.IP \[bu] 2
\f[V]\[dq]on_cyan\[dq]\f[R] for \f[V]tcell.ColorCyan\f[R]
.IP \[bu] 2
\f[V]\[dq]on_white\[dq]\f[R] for \f[V]tcell.ColorWhite\f[R]
.IP \[bu] 2
\f[V]\[dq]on_0\[dq]\f[R]-\f[V]\[dq]on_255\[dq]\f[R] for 256color
(automatically supported via tcell)
.IP \[bu] 2
\f[V]\[dq]on_#RRGGBB\[dq]\f[R] for 24-bit truecolor
(e.g.\ \f[V]\[dq]on_#003366\[dq]\f[R])
.SS Attributes
.IP \[bu] 2
\f[V]\[dq]bold\[dq]\f[R] for fg: \f[V]tcell.AttrBold\f[R]
.IP \[bu] 2
\f[V]\[dq]underline\[dq]\f[R] for fg: \f[V]tcell.AttrUnderline\f[R]
.IP \[bu] 2
\f[V]\[dq]reverse\[dq]\f[R] for fg: \f[V]tcell.AttrReverse\f[R]
.IP \[bu] 2
\f[V]\[dq]on_bold\[dq]\f[R] for bg: \f[V]tcell.AttrBold\f[R] (this
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
possible to create your own custom filter.
.PP
The filter will be executed via \f[V]Command.Run()\f[R] as an external
process, and it will be passed the query values in the command line, and
the original unaltered buffer is passed via \f[V]os.Stdin\f[R].
Your filter must perform the matching, and print out to
\f[V]os.Stdout\f[R] matched lines.
Your filter MAY be called multiple times if the buffer given to peco is
big enough.
See \f[V]BufferThreshold\f[R] below.
.PP
Note that currently there is no way for the custom filter to specify
where in the line the match occurred, so matched portions in the string
WILL NOT BE HIGHLIGHTED.
.PP
The filter does not need to be a go program.
It can be a perl/ruby/python/bash script, or anything else that is
executable.
.SS Batching Behavior
.PP
Unlike the built-in filters (which process batches in parallel),
external filters are invoked \f[B]sequentially\f[R], one batch at a
time.
Each invocation receives a subset of the input lines on stdin, not the
complete input.
\f[V]BufferThreshold\f[R] controls how many lines are buffered before
each invocation.
.PP
Because of this batching, your filter \f[B]must be stateless\f[R] \[em]
it cannot assume it sees all input lines in a single invocation.
Each invocation is independent.
Filters that require global context (e.g., sorting the entire input or
counting total lines) will not work correctly, as they only see one
batch per invocation.
.PP
A larger \f[V]BufferThreshold\f[R] means fewer invocations but a longer
wait before results appear.
A smaller threshold means more invocations but faster feedback.
.PP
Note that negative query terms (e.g., \f[V]-foo\f[R]) are NOT parsed by
peco for external filters; the raw query string including any
\f[V]-\f[R] prefixes is passed as-is to the external command via
\f[V]$QUERY\f[R].
.SS Configuration
.PP
Once you have a filter, you must specify how the matcher is spawned:
.IP
.nf
\f[C]
{
    \[dq]CustomFilter\[dq]: {
        \[dq]MyFilter\[dq]: {
            \[dq]Cmd\[dq]: \[dq]/path/to/my-matcher\[dq],
            \[dq]Args\[dq]: [ \[dq]$QUERY\[dq] ],
            \[dq]BufferThreshold\[dq]: 100
        }
    }
}
\f[R]
.fi
.PP
\f[V]Cmd\f[R] specifies the command name.
This must be searchable via \f[V]exec.LookPath\f[R].
.PP
Elements in the \f[V]Args\f[R] section are string keys to array of
program arguments.
The special token \f[V]$QUERY\f[R] will be replaced with the unaltered
query as the user typed in (i.e.\ multiple-word queries will be passed
as a single string).
You may pass in any other arguments in this array.
If you omit this in your config, a default value of
\f[V][]string{\[dq]$QUERY\[dq]}\f[R] will be used.
.PP
\f[V]BufferThreshold\f[R] specifies that the filter command should be
invoked when peco has this many lines to process in the buffer.
For example, if you are using peco against a 1000-line input, and your
\f[V]BufferThreshold\f[R] is 100 (which is the default), then your
filter will be invoked 10 times.
The larger this threshold is, the faster the overall performance will
be, but the longer you will have to wait to see the filter results.
.PP
You may specify as many filters as you like in the
\f[V]CustomFilter\f[R] section.
.SS Examples
.IP \[bu] 2
An example of a simple perl regexp
matcher (https://gist.github.com/mattn/24712964da6e3112251c)
.IP \[bu] 2
An example using migemogrep Japanese grep using latin-1
chars (https://github.com/peco/peco/wiki/CustomFilter)
.SS Layout
.PP
See \[en]layout.
.SS SingleKeyJump
.IP
.nf
\f[C]
{
  \[dq]SingleKeyJump\[dq]: {
    \[dq]ShowPrefix\[dq]: true
  }
}
\f[R]
.fi
.SS SelectionPrefix
.PP
\f[V]SelectionPrefix\f[R] is equivalent to using
\f[V]--selection-prefix\f[R] in the command line.
.IP
.nf
\f[C]
{
  \[dq]SelectionPrefix\[dq]: \[dq]>\[dq]
}
\f[R]
.fi
.SH FAQ
.SS Does peco work on (msys2|cygwin)?
.PP
No.\ https://github.com/peco/peco/issues/336#issuecomment-243939696
(Updated Feb 23, 2017: \[lq]Maybe\[rq] on cygwin
https://github.com/peco/peco/issues/336#issuecomment-281912949)
.SS Non-latin fonts (e.g.\ Japanese) look weird on my Windows machine\&...?
.PP
Are you using raster fonts?
https://github.com/peco/peco/issues/341
.SS Seeing escape sequences \f[V][200\[ti]\f[R] and \f[V][201\[ti]\f[R] when pasting text?
.PP
Disable bracketed paste mode.
https://github.com/peco/peco/issues/417
.SH Hacking
.PP
First, fork this repo, and get your clone locally.
.IP "1." 3
Make sure you have go (http://golang.org) installed, with GOPATH
appropriately set
.IP "2." 3
Make sure you have \f[V]make\f[R] installed
.PP
To test, run
.IP
.nf
\f[C]
make test
\f[R]
.fi
.PP
To build, run
.IP
.nf
\f[C]
make
\f[R]
.fi
.PP
This will create a \f[V]peco\f[R] binary in
\f[V]$(RELEASE_DIR)/peco_$(GOOS)_$(GOARCH)/peco$(SUFFIX)\f[R].
Or, of course, you can just run
.IP
.nf
\f[C]
go build cmd/peco/peco.go
\f[R]
.fi
.PP
which will create the binary in the local directory.
.SH TODO
.PP
Unit test it.
.SH AUTHORS
.IP \[bu] 2
Daisuke Maki (lestrrat)
.IP \[bu] 2
mattn
.IP \[bu] 2
syohex
.SH CONTRIBUTORS
.IP \[bu] 2
HIROSE Masaaki
.IP \[bu] 2
Joel Segerlind
.IP \[bu] 2
Lukas Lueg
.IP \[bu] 2
Mitsuoka Mimura
.IP \[bu] 2
Ryota Arai
.IP \[bu] 2
Shinya Ohyanagi
.IP \[bu] 2
Takashi Kokubun
.IP \[bu] 2
Yuya Takeyama
.IP \[bu] 2
cho45
.IP \[bu] 2
cubicdaiya
.IP \[bu] 2
kei_q
.IP \[bu] 2
negipo
.IP \[bu] 2
sona_tar
.IP \[bu] 2
sugyan
.IP \[bu] 2
swdyh
.IP \[bu] 2
MURAOKA Taro (kaoriya/koron), for aho-corasick search
.IP \[bu] 2
taichi, for the gif working on Windows
.IP \[bu] 2
uobikiemukot
.IP \[bu] 2
Samuel Lemaitre
.IP \[bu] 2
Yousuke Ushiki
.IP \[bu] 2
Linda_pp
.IP \[bu] 2
Tomohiro Nishimura (Sixeight)
.IP \[bu] 2
Naruki Tanabe (narugit)
.SH Notes
.PP
Obviously, kudos to the original percol: https://github.com/mooz/percol
Much code stolen from https://github.com/mattn/gof