From 31f2ecd1781f0c128d8c19aac596cf6f6f4e915b Mon Sep 17 00:00:00 2001 From: Daisuke Maki Date: Sun, 15 Feb 2026 16:47:48 +0900 Subject: [PATCH] Add man page. fixes #467 --- .github/workflows/manpage.yml | 25 + contrib/man/generate.sh | 10 + contrib/man/peco.1 | 1660 +++++++++++++++++++++++++++++++++ 3 files changed, 1695 insertions(+) create mode 100644 .github/workflows/manpage.yml create mode 100755 contrib/man/generate.sh create mode 100644 contrib/man/peco.1 diff --git a/.github/workflows/manpage.yml b/.github/workflows/manpage.yml new file mode 100644 index 0000000..8e427a4 --- /dev/null +++ b/.github/workflows/manpage.yml @@ -0,0 +1,25 @@ +name: Update man page + +on: + push: + branches: [master] + paths: ['README.md'] + +jobs: + update-manpage: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - name: Install pandoc + run: sudo apt-get update && sudo apt-get install -y pandoc + - name: Generate man page + run: bash contrib/man/generate.sh + - name: Create Pull Request + uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676 # v7 + with: + commit-message: "docs: regenerate man page from README" + title: "docs: update man page" + body: | + Auto-generated update to `contrib/man/peco.1` from changes to `README.md`. + branch: update-manpage + delete-branch: true diff --git a/contrib/man/generate.sh b/contrib/man/generate.sh new file mode 100755 index 0000000..f1c679d --- /dev/null +++ b/contrib/man/generate.sh @@ -0,0 +1,10 @@ +#!/bin/sh +set -e +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" +pandoc -s -f markdown -t man \ + -V title=PECO -V section=1 \ + -V header="User Commands" \ + -V footer="peco" \ + -o "$SCRIPT_DIR/peco.1" \ + "$REPO_ROOT/README.md" diff --git a/contrib/man/peco.1 b/contrib/man/peco.1 new file mode 100644 index 0000000..80855a2 --- /dev/null +++ b/contrib/man/peco.1 @@ -0,0 +1,1660 @@ +'\" 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. +.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. +.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 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 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 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 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 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 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 +Run \f[V]go build\f[R] to create \f[V]releases/$VERSION_NUMBER/peco\f[R] +.PP +You can copy the binary to somewhere in your $PATH, and it should just +work. +.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[V]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 +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\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. +.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]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. +.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 +InitialMatcher +.IP \[bu] 2 +Use256Color +.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 InitialMatcher +.PP +\f[I]InitialMatcher\f[R] has been deprecated. +Please use \f[V]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[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 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 +.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.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} +T{ +Pgup +T}@T{ +peco.ScrollPageUp +T} +T{ +Pgdn +T}@T{ +peco.ScrollPageDown +T} +.TE +.SS Styles +.PP +For now, styles of following 6 items 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]Matched\[dq]: [\[dq]red\[dq], \[dq]on_blue\[dq]], + \[dq]Prompt\[dq]: [\[dq]green\[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]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]) +.SS Foreground Colors +.IP \[bu] 2 +\f[V]\[dq]black\[dq]\f[R] for \f[V]termbox.ColorBlack\f[R] +.IP \[bu] 2 +\f[V]\[dq]red\[dq]\f[R] for \f[V]termbox.ColorRed\f[R] +.IP \[bu] 2 +\f[V]\[dq]green\[dq]\f[R] for \f[V]termbox.ColorGreen\f[R] +.IP \[bu] 2 +\f[V]\[dq]yellow\[dq]\f[R] for \f[V]termbox.ColorYellow\f[R] +.IP \[bu] 2 +\f[V]\[dq]blue\[dq]\f[R] for \f[V]termbox.ColorBlue\f[R] +.IP \[bu] 2 +\f[V]\[dq]magenta\[dq]\f[R] for \f[V]termbox.ColorMagenta\f[R] +.IP \[bu] 2 +\f[V]\[dq]cyan\[dq]\f[R] for \f[V]termbox.ColorCyan\f[R] +.IP \[bu] 2 +\f[V]\[dq]white\[dq]\f[R] for \f[V]termbox.ColorWhite\f[R] +.IP \[bu] 2 +\f[V]\[dq]0\[dq]\f[R]-\f[V]\[dq]255\[dq]\f[R] for 256color (Use256Color +must be enabled) +.SS Background Colors +.IP \[bu] 2 +\f[V]\[dq]on_black\[dq]\f[R] for \f[V]termbox.ColorBlack\f[R] +.IP \[bu] 2 +\f[V]\[dq]on_red\[dq]\f[R] for \f[V]termbox.ColorRed\f[R] +.IP \[bu] 2 +\f[V]\[dq]on_green\[dq]\f[R] for \f[V]termbox.ColorGreen\f[R] +.IP \[bu] 2 +\f[V]\[dq]on_yellow\[dq]\f[R] for \f[V]termbox.ColorYellow\f[R] +.IP \[bu] 2 +\f[V]\[dq]on_blue\[dq]\f[R] for \f[V]termbox.ColorBlue\f[R] +.IP \[bu] 2 +\f[V]\[dq]on_magenta\[dq]\f[R] for \f[V]termbox.ColorMagenta\f[R] +.IP \[bu] 2 +\f[V]\[dq]on_cyan\[dq]\f[R] for \f[V]termbox.ColorCyan\f[R] +.IP \[bu] 2 +\f[V]\[dq]on_white\[dq]\f[R] for \f[V]termbox.ColorWhite\f[R] +.IP \[bu] 2 +\f[V]\[dq]on_0\[dq]\f[R]-\f[V]\[dq]on_255\[dq]\f[R] for 256color +(Use256Color must be enabled) +.SS Attributes +.IP \[bu] 2 +\f[V]\[dq]bold\[dq]\f[R] for fg: \f[V]termbox.AttrBold\f[R] +.IP \[bu] 2 +\f[V]\[dq]underline\[dq]\f[R] for fg: \f[V]termbox.AttrUnderline\f[R] +.IP \[bu] 2 +\f[V]\[dq]reverse\[dq]\f[R] for fg: \f[V]termbox.AttrReverse\f[R] +.IP \[bu] 2 +\f[V]\[dq]on_bold\[dq]\f[R] for bg: \f[V]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[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. +.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. +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[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 +.SS Use256Color +.PP +Boolean value that determines whether or not to use 256color. +The default is \f[V]false\f[R]. +.PP +Note: This has no effect on Windows because Windows console does not +support extra color modes. +.IP +.nf +\f[C] +{ + \[dq]Use256Color\[dq]: true +} +\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 +.SH Table of Contents +.IP \[bu] 2 +peco +.IP \[bu] 2 +Description +.RS 2 +.IP \[bu] 2 +Demo +.RE +.IP \[bu] 2 +Features +.RS 2 +.IP \[bu] 2 +Incremental Search +.IP \[bu] 2 +Select Multiple Lines +.IP \[bu] 2 +Select Range Of Lines +.IP \[bu] 2 +Select Filters +.IP \[bu] 2 +Selectable Layout +.IP \[bu] 2 +Works on Windows! +.RE +.IP \[bu] 2 +Installation +.RS 2 +.IP \[bu] 2 +Just want the binary? +.IP \[bu] 2 +macOS (Homebrew, Scarf) +.IP \[bu] 2 +Debian and Ubuntu based distributions (APT, Scarf) +.IP \[bu] 2 +Void Linux (XBPS) +.IP \[bu] 2 +Arch Linux +.IP \[bu] 2 +Windows (Chocolatey NuGet Users) +.IP \[bu] 2 +Building peco yourself +.IP \[bu] 2 +go get IS NOT RECOMMENDED +.RE +.IP \[bu] 2 +Command Line Options +.RS 2 +.IP \[bu] 2 +-h, \[en]help +.IP \[bu] 2 +\[en]version +.IP \[bu] 2 +\[en]query +.IP \[bu] 2 +\[en]print-query +.IP \[bu] 2 +\[en]rcfile +.IP \[bu] 2 +-b, \[en]buffer-size +.IP \[bu] 2 +\[en]null +.IP \[bu] 2 +\[en]initial-index +.IP \[bu] 2 +\[en]initial-filter +\f[V]IgnoreCase|CaseSensitive|SmartCase|IRegexp|Regexp|Fuzzy\f[R] +.IP \[bu] 2 +\[en]prompt +.IP \[bu] 2 +\[en]layout \f[V]top-down|bottom-up\f[R] +.IP \[bu] 2 +\[en]select-1 +.IP \[bu] 2 +\[en]on-cancel \f[V]success|error\f[R] +.IP \[bu] 2 +\[en]selection-prefix \f[V]string\f[R] +.IP \[bu] 2 +\[en]exec \f[V]string\f[R] +.RE +.IP \[bu] 2 +Configuration File +.RS 2 +.IP \[bu] 2 +Global +.RS 2 +.IP \[bu] 2 +Prompt +.IP \[bu] 2 +InitialMatcher +.IP \[bu] 2 +InitialFilter +.IP \[bu] 2 +FuzzyLongestSort +.IP \[bu] 2 +StickySelection +.IP \[bu] 2 +SuppressStatusMsg +.IP \[bu] 2 +OnCancel +.IP \[bu] 2 +MaxScanBufferSize +.RE +.IP \[bu] 2 +Keymaps +.RS 2 +.IP \[bu] 2 +Key sequences +.IP \[bu] 2 +Combined actions +.IP \[bu] 2 +Available keys +.IP \[bu] 2 +Key workarounds +.IP \[bu] 2 +Available actions +.IP \[bu] 2 +Default Keymap +.RE +.IP \[bu] 2 +Styles +.RS 2 +.IP \[bu] 2 +Foreground Colors +.IP \[bu] 2 +Background Colors +.IP \[bu] 2 +Attributes +.RE +.IP \[bu] 2 +CustomFilter +.RS 2 +.IP \[bu] 2 +Examples +.RE +.IP \[bu] 2 +Layout +.IP \[bu] 2 +SingleKeyJump +.IP \[bu] 2 +SelectionPrefix +.IP \[bu] 2 +Use256Color +.RE +.IP \[bu] 2 +FAQ +.RS 2 +.IP \[bu] 2 +Does peco work on (msys2|cygwin)? +.IP \[bu] 2 +Non-latin fonts (e.g.\ Japanese) look weird on my Windows machine\&...? +.IP \[bu] 2 +Seeing escape sequences \f[V][200\[ti]\f[R] and \f[V][201\[ti]\f[R] when +pasting text? +.RE +.IP \[bu] 2 +Hacking +.IP \[bu] 2 +TODO +.IP \[bu] 2 +AUTHORS +.IP \[bu] 2 +CONTRIBUTORS +.IP \[bu] 2 +Notes +.IP \[bu] 2 +Table of Contents