Created
November 17, 2018 12:12
-
-
Save Konfekt/d1fdc8182a3afe84863a8303daacb3ae to your computer and use it in GitHub Desktop.
peco manpage
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
.TH peco 1 "2018-11-17" "0.5.3" "https://github.com/peco/peco/" | |
.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[C]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 (./Changes) file for features | |
and changes. | |
.PP | |
This README is long and comprehensive. | |
Use the Table of Contents to navigate to the section that interests you. | |
It has been placed at the bottom of the README file because of its | |
length. | |
.SH Description | |
.PP | |
\f[C]peco\f[R] (pronounced \f[I]peh\-koh\f[R]) is based on a python | |
tool, percol (https://github.com/mooz/percol). | |
\f[C]percol\f[R] was darn useful, but I wanted a tool that was a single | |
binary, and forget about python. | |
\f[C]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[C]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: | |
.PP | |
[IMAGE: Executed \f[C]ps \-ef | peco\f[R], then the query \f[C]root\f[R] | |
was typed. This shows all lines containing the word | |
root (http://peco.github.io/images/peco-demo-ps.gif)] | |
.PP | |
Here\[cq]s me trying to figure out which file to open: | |
.PP | |
[IMAGE: Executed \f[C]find . \-name \[aq]*.go\[aq] | peco\f[R] (within | |
camlistore repository), then the query \f[C]camget\f[R] was typed. This | |
shows all lines including the word | |
\f[C]camget\f[R] (http://peco.github.io/images/peco-demo-filename.gif)] | |
.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) | |
.PP | |
[IMAGE: Executed | |
\f[C]cd $(ghq list \-\-full\-path | peco \-\-query peco)\f[R] to show | |
all repositories containing the word \f[C]peco\f[R], then to change | |
directories into the one | |
selected (http://peco.github.io/images/peco-demo-ghq.gif)] | |
.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: | |
.PP | |
[IMAGE: Executed \f[C]ps aux | peco\f[R], then the query | |
\f[C]root app\f[R] was typed. This shows all lines containing both | |
\f[C]root\f[R] and | |
\f[C]app\f[R] (http://peco.github.io/images/peco-demo-multiple-queries.gif)] | |
.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 Select Multiple Lines | |
.PP | |
You can select multiple lines! | |
.PP | |
[IMAGE: Executed \f[C]ls \-l | peco\f[R], then used peco.ToggleSelection | |
to select multiple | |
lines (http://peco.github.io/images/peco-demo-multiple-selection.gif)] | |
.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) | |
.PP | |
[IMAGE: Executed \f[C]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)] | |
.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 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[C]ALongString\f[R], you can enable | |
the Fuzzy filter and search \f[C]ALS\f[R] to find it. | |
The Fuzzy filter uses smart case search like the SmartCase filter. | |
.PP | |
[IMAGE: Executed \f[C]ps aux | peco\f[R], then typed \f[C]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[C](?i)google\f[R] instead to toggle case\-insensitive | |
mode (http://peco.github.io/images/peco-demo-matcher.gif)] | |
.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[C]\-\-layout=bottom\-up\f[R] command line option, or set the | |
\f[C]Layout\f[R] variable in your configuration file | |
.PP | |
[IMAGE: Executed \f[C]ps \-ef | peco \-\-layout=bottom\-up\f[R] to | |
toggle inverted layout | |
mode (http://peco.github.io/images/peco-demo-layout-bottom-up.gif)] | |
.SS Works on Windows! | |
.PP | |
I have been told that peco even works on windows :) Look ma! I\[cq]m not | |
lying! | |
.PP | |
[IMAGE: Showing peco running on Windows | |
cmd.exe (https://gist.githubusercontent.com/taichi/26814518d8b00352693b/raw/b7745987de32dbf068e81a8308c0c5ed38138649/peco.gif)] | |
.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 OS X homebrew users) | |
.SS Mac OS X / Homebrew | |
.PP | |
If you\[cq]re on OS X and want to use homebrew: | |
.IP | |
.nf | |
\f[C] | |
brew install 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 Building peco yourself | |
.PP | |
Make sure to clone the source code under $GOPATH | |
(i.e.\ $GOPATH/src/github.com/peco/peco). | |
This is required as the main binary refers to an internal package, which | |
requires that the the source code be located in the correct package | |
location. | |
.PP | |
Navigate to the directory above, then run: | |
.IP | |
.nf | |
\f[C] | |
make build | |
\f[R] | |
.fi | |
.PP | |
This will do the following: | |
.IP "1." 3 | |
Install glide under \f[C]_internal_bin\f[R] directory | |
.IP "2." 3 | |
Run glide install to fetch dependencies | |
.IP "3." 3 | |
Run \f[C]go build\f[R] to create \f[C]releases/$VERSION_NUMBER/peco\f[R] | |
.PP | |
You can copy the binary to somewhere in your $PATH, and it should just | |
work. | |
.PP | |
If you do not wish to have a separate installation of glide and/or want | |
more control of the build process, run the following instead: | |
.IP | |
.nf | |
\f[C] | |
glide install | |
\f[R] | |
.fi | |
.PP | |
The above installs the correct versions of peco\[cq]s dependencies. | |
Then build it: | |
.IP | |
.nf | |
\f[C] | |
go build cmd/peco/peco.go | |
\f[R] | |
.fi | |
.PP | |
This compiles a peco binary in the root of the cloned peco repository. | |
Copy this file to an appropriate location. | |
.SS go get IS NOT RECOMMENDED | |
.PP | |
Please DO NOT use \f[C]go get\f[R] to install this tool. | |
It bypasses the developers\[cq] intention of controlling the dependency | |
versioning. | |
.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 before | |
hand 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[C]Configuration File\f[R] for the actual locations searched. | |
.SS \-b, \[en]buffer\-size | |
.PP | |
Limits the buffer size to \f[C]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 (\[cq]\[rs]0\[cq]) 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[C]IgnoreCase|CaseSensitive|SmartCase|Regexp|Fuzzy\f[R] | |
.PP | |
Specifies the initial filter to use upon start up. | |
You should specify the name of the filter like \f[C]IgnoreCase\f[R], | |
\f[C]CaseSensitive\f[R], \f[C]SmartCase\f[R], \f[C]Regexp\f[R] and | |
\f[C]Fuzzy\f[R]. | |
Default is \f[C]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[C]Prompt\f[R] section. | |
The default value is \f[C]QUERY>\f[R] | |
.SS \[en]layout \f[C]top\-down|bottom\-up\f[R] | |
.PP | |
Specifies the display layout. | |
Default is \f[C]top\-down\f[R], where query prompt is at the top, | |
followed by the list, then the system status message line. | |
\f[C]bottom\-up\f[R] changes this to the list first (displayed in | |
reverse order), the query prompt, and then the system status message | |
line. | |
.PP | |
For \f[C]percol\f[R] users, \f[C]\-\-layout=bottom\-up\f[R] is almost | |
equivalent of \f[C]\-\-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]on\-cancel \f[C]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[C]success\f[R], meaning if the user cancels the query, the exit | |
status is 0. | |
When you choose \f[C]error\f[R], peco will exit with a non\-zero value. | |
.SS \[en]selection\-prefix \f[C]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[C]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. | |
.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 directories 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 | |
InitialMatcher | |
.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[C]QUERY>\f[R] by | |
default. | |
.IP | |
.nf | |
\f[C] | |
{ | |
\[dq]Prompt\[dq]: \[dq][peco]\[dq] | |
} | |
\f[R] | |
.fi | |
.SS InitialMatcher | |
.PP | |
\f[I]InitialMatcher\f[R] has been deprecated. | |
Please use \f[C]InitialFilter\f[R] instead. | |
.SS InitialFilter | |
.PP | |
Specifies the filter name to start peco with. | |
You should specify the name of the filter, such as \f[C]IgnoreCase\f[R], | |
\f[C]CaseSensitive\f[R], \f[C]SmartCase\f[R], \f[C]Regexp\f[R] and | |
\f[C]Fuzzy\f[R]. | |
.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 in tact. | |
.PP | |
Default value for StickySelection is false. | |
.SS OnCancel | |
.IP | |
.nf | |
\f[C] | |
{ | |
\[dq]OnCancel\[dq]: \[dq]error\[dq] | |
} | |
\f[R] | |
.fi | |
.PP | |
OnCancel is equivalent to \f[C]\-\-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[C]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 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[C]C\-x,C\-c,C\-c\f[R], then the above \f[C]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[C]foo.SelectFour\f[R] (the format | |
of the name is totally arbitrary, I just like to put namespaces), and | |
assigns that action to \f[C]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[C]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[C]M\-\f[R] | |
prefix on any key item to use Alt/Option key as a mask. | |
.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 OS X | |
T} | |
.TE | |
.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 filterd by query and not filterd. | |
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.RotateMatcher | |
T}@T{ | |
(DEPRECATED) Use peco.RotateFilter | |
T} | |
T{ | |
peco.RotateFilter | |
T}@T{ | |
Rotate between filters (by default, ignore\-case/no\-ignore\-case) | |
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} | |
.TE | |
.SS Styles | |
.PP | |
For now, styles of following 5 items can be customized in | |
\f[C]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]Matched\[dq]: [\[dq]red\[dq], \[dq]on_blue\[dq]] | |
} | |
} | |
\f[R] | |
.fi | |
.IP \[bu] 2 | |
\f[C]Basic\f[R] for not selected lines | |
.IP \[bu] 2 | |
\f[C]SavedSelection\f[R] for lines of saved selection | |
.IP \[bu] 2 | |
\f[C]Selected\f[R] for a currently selecting line | |
.IP \[bu] 2 | |
\f[C]Query\f[R] for a query line | |
.IP \[bu] 2 | |
\f[C]Matched\f[R] for a query matched word | |
.SS Foreground Colors | |
.IP \[bu] 2 | |
\f[C]\[dq]black\[dq]\f[R] for \f[C]termbox.ColorBlack\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]red\[dq]\f[R] for \f[C]termbox.ColorRed\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]green\[dq]\f[R] for \f[C]termbox.ColorGreen\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]yellow\[dq]\f[R] for \f[C]termbox.ColorYellow\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]blue\[dq]\f[R] for \f[C]termbox.ColorBlue\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]magenta\[dq]\f[R] for \f[C]termbox.ColorMagenta\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]cyan\[dq]\f[R] for \f[C]termbox.ColorCyan\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]white\[dq]\f[R] for \f[C]termbox.ColorWhite\f[R] | |
.SS Background Colors | |
.IP \[bu] 2 | |
\f[C]\[dq]on_black\[dq]\f[R] for \f[C]termbox.ColorBlack\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]on_red\[dq]\f[R] for \f[C]termbox.ColorRed\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]on_green\[dq]\f[R] for \f[C]termbox.ColorGreen\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]on_yellow\[dq]\f[R] for \f[C]termbox.ColorYellow\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]on_blue\[dq]\f[R] for \f[C]termbox.ColorBlue\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]on_magenta\[dq]\f[R] for \f[C]termbox.ColorMagenta\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]on_cyan\[dq]\f[R] for \f[C]termbox.ColorCyan\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]on_white\[dq]\f[R] for \f[C]termbox.ColorWhite\f[R] | |
.SS Attributes | |
.IP \[bu] 2 | |
\f[C]\[dq]bold\[dq]\f[R] for fg: \f[C]termbox.AttrBold\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]underline\[dq]\f[R] for fg: \f[C]termbox.AttrUnderline\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]reverse\[dq]\f[R] for fg: \f[C]termbox.AttrReverse\f[R] | |
.IP \[bu] 2 | |
\f[C]\[dq]on_bold\[dq]\f[R] for bg: \f[C]termbox.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[C]peco\f[R] comes with \f[C]IgnoreCase\f[R], | |
\f[C]CaseSensitive\f[R], \f[C]SmartCase\f[R], \f[C]Regexp\f[R] and | |
\f[C]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[C]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[C]os.Stdin\f[R]. | |
Your filter must perform the matching, and print out to | |
\f[C]os.Stdout\f[R] matched lines. | |
You filter MAY be called multiple times if the buffer given to peco is | |
big enough. | |
See \f[C]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. | |
.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[C]Cmd\f[R] specifies the command name. | |
This must be searcheable via \f[C]exec.LookPath\f[R]. | |
.PP | |
Elements in the \f[C]Args\f[R] section are string keys to array of | |
program arguments. | |
The special token \f[C]$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[C][]string{\[dq]$QUERY\[dq]}\f[R] will be used | |
.PP | |
\f[C]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[C]BufferThreshold\f[R] is 100 (which is the default), then your | |
filter will be invoked 10 times. | |
For obvious reasons, 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[C]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[C]SelectionPrefix\f[R] is equivalent to using | |
\f[C]\-\-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[C][200\[ti]\f[R] and \f[C][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[C]make\f[R] installed | |
.IP "3." 3 | |
Run \f[C]make installdeps\f[R] (You only need to do this once, or when | |
you update glide.yml/glide.lock) | |
.PP | |
To test, run | |
.IP | |
.nf | |
\f[C] | |
make test | |
\f[R] | |
.fi | |
.PP | |
To build, run | |
.IP | |
.nf | |
\f[C] | |
make build | |
\f[R] | |
.fi | |
.PP | |
This will create a \f[C]peco\f[R] binary in | |
\f[C]$(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 | |
Test it. | |
In doing so, we may change the repo structure | |
.PP | |
Implement all(?) of the original percol options | |
.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) | |
.SH Notes | |
.PP | |
Obviously, kudos to the original percol: https://github.com/mooz/percol | |
Much code stolen from https://github.com/mattn/gof |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment