peco

Simplistic interactive filtering tool

NOTE: If you are viewing this on GitHub, this document refers to the state of peco in whatever current branch you are viewing, not necessarily the state of a currently released version. Please make sure to checkout the Changes file for features and changes.

If you use peco, please consider sponsoring the authors of this project from the "Sponsor" button on the project page at https://github.com/peco/peco. Sponsorship plans start at $1 :)

Description

peco (pronounced peh-koh) is based on a python tool, percol. percol was darn useful, but I wanted a tool that was a single binary, and forget about python. peco is written in Go, and therefore you can just grab the binary releases and drop it in your $PATH.

peco 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.

For basic usage, continue down below. For more cool elaborate usage samples, please see the wiki, and if you have any other tricks you want to share, please add to it!

Demo

Demos speak more than a thousand words! Here'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:

Here's me trying to figure out which file to open:

When you combine tools like zsh, peco, and ghq, you can make managing/moving around your huge dev area a piece of cake! (this example doesn't use zsh functions so you can see what I'm doing)

Features

Incremental Search

Search results are filtered as you type. This is great to drill down to the line you are looking for

Multiple terms turn the query into an "AND" query:

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

Negative Matching

You can exclude lines from the results by prefixing a term with -. For example, the query SSO -tests -javadoc shows lines matching "SSO" that do NOT contain "tests" or "javadoc".

| Query | Meaning | |-------|---------| | foo -bar | Lines matching "foo" but not containing "bar" | | -foo -bar | All lines not containing "foo" or "bar" | | \-foo | Literal match for "-foo" (escaped with backslash) | | - | Literal match for a hyphen character |

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.

Only positive terms produce match highlighting. Lines matched solely by negative exclusion (e.g. an all-negative query like -foo) are shown without highlighting.

Note: 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 foo -bar then adding an uppercase character). If this happens, clearing the query and retyping it will produce the correct results.

Upgrading from v0.5.x: In v0.5.x, a query like test -v matched lines containing both "test" and literal "-v". From v0.6.0 onwards, -v is treated as a negative term, so the query matches "test" while excluding lines containing "v". To search for a literal hyphen-prefixed term, escape it with a backslash (e.g. \-v).

Select Multiple Lines

You can select multiple lines! (this example uses C-Space)

Select Range Of Lines

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)

Select Filters

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.

The SmartCase filter uses case-insensitive matching when all of the queries are lower case, and case-sensitive matching otherwise.

The Regexp filter allows you to use any valid regular expression to match lines.

The Fuzzy filter allows you to find matches using partial patterns. For example, when searching for ALongString, you can enable the Fuzzy filter and search ALS to find it. The Fuzzy filter uses smart case search like the SmartCase filter. With the FuzzyLongestSort 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.

Multi-Stage Filtering (Freeze Results)

You can "freeze" the current filter results, clear the query, and continue filtering on top of the frozen results. This enables multi-stage filtering workflows -- for example, first filter by file extension, freeze, then filter by filename.

Use peco.FreezeResults to snapshot the current results and clear the query. Use peco.UnfreezeResults to discard the frozen results and revert to the original input. These actions are not bound to any key by default -- you need to add keybindings in your config file:

{
    "Keymap": {
        "M-f": "peco.FreezeResults",
        "M-u": "peco.UnfreezeResults"
    }
}

You can freeze multiple times to progressively narrow down results. Unfreezing always reverts back to the original unfiltered input.

Example: Given this input via ls | peco:

QUERY>
app.go
app_test.go
filter.go
filter_test.go
main.go
readme.md

Type _test to filter:

QUERY> _test
app_test.go
filter_test.go

Press M-f to freeze. The two test files become the new base and the query clears:

QUERY>
app_test.go
filter_test.go

Now type filter to search within the frozen results:

QUERY> filter
filter_test.go

Press Enter to select filter_test.go, or press M-u to unfreeze and return to the original full list.

Horizontal Scrolling

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 peco.ScrollLeft and peco.ScrollRight actions. These actions are not bound to any key by default -- you need to add keybindings in your config file:

{
    "Keymap": {
        "ArrowLeft": "peco.ScrollLeft",
        "ArrowRight": "peco.ScrollRight"
    }
}

Each scroll moves by half the terminal width.

If your input contains very long lines (e.g. minified files) and they do not appear at all, try increasing MaxScanBufferSize in your config. The default is 256 (KB), which limits the maximum length of a single input line.

ANSI Color Support

By default (--color=auto), 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 git log --color, rg --color=always, or ls --color through peco while preserving the visual formatting.

git log --color=always | peco
rg --color=always pattern | peco
ls --color=always | peco

To disable ANSI color rendering, use --color=none.

peco uses two independent color layers, both supporting 8 named colors, 256-color, and 24-bit truecolor. The first is peco's own UI styling — selection highlighting, match highlighting, prompt colors, etc. — configured via the Style section in the config file (see Styles). UI styling is always active and is not affected by the --color flag. The second is input ANSI colors — escape sequences already present in the piped input from tools like git log --color. This layer is controlled by the --color flag described above.

When input ANSI color support is enabled, filtering and matching operate against the stripped (plain text) version of each line, so escape codes do not interfere with your queries. Input ANSI colors are displayed as the base layer; peco's own UI styling takes precedence. Selected lines' output preserves the original ANSI codes, so downstream tools receive colored text.

ANSI color support can be controlled via the configuration file (see Color under Global configuration).

Context Lines (Zoom In/Out)

When filtering results (e.g. searching for "error" in a log file), you often need to see the surrounding lines to understand the c