PathPicker accepts a wide range of input -- output from git commands, grep results, searches -- pretty much anything. After parsing the input, PathPicker presents you with a nice UI to select which files you're interested in. After that you can open them in your favorite editor or execute arbitrary commands.

Related tags



tests License: MIT

Facebook PathPicker is a simple command line tool that solves the perpetual problem of selecting files out of bash output. PathPicker will:

  • Parse all incoming lines for entries that look like files
  • Present the piped input in a convenient selector UI
  • Allow you to either:
    • Edit the selected files in your favorite $EDITOR
    • Execute an arbitrary command with them

It is easiest to understand by watching a simple demo:


After installing PathPicker, using it is as easy as piping into fpp. It takes a wide variety of input -- try it with all the options below:

  • git status | fpp
  • hg status | fpp
  • git grep "FooBar" | fpp
  • grep -r "FooBar" . | fpp
  • git diff HEAD~1 --stat | fpp
  • find . -iname "*.js" | fpp
  • arc inlines | fpp

and anything else you can dream up!


PathPicker requires Python 3.

Supported Shells

  • Bash is fully supported and works the best.
  • ZSH is supported as well, but won't have a few features like alias expansion in command line mode.
  • csh/fish/rc are supported in the latest version, but might have quirks or issues in older versions of PathPicker. Note: if your default shell and current shell is not in the same family (bash/zsh... v.s. fish/rc), you need to manually export environment variable $SHELL to your current shell.

Installing PathPicker


Installing PathPicker is easiest with Homebrew for mac:

  • brew update (to pull down the recipe since it is new)
  • brew install fpp


On Debian-based systems, run these steps: fakeroot:

$ git clone
$ cd PathPicker/debian
$ ./
$ ls ../fpp_0.7.2_noarch.deb

On Arch Linux, PathPicker can be installed from Arch User Repository (AUR). (The AUR fpp-git package.)

If you are on another system, or prefer manual installation, please follow the instructions given below.

Manual Installation

If you are on a system without Homebrew, it's still quite easy to install PathPicker, since it's essentially just a bash script that calls some Python. These steps more-or-less outline the process:

  • cd /usr/local/ # or wherever you install apps
  • git clone
  • cd PathPicker/

Here we create a symbolic link from the bash script in the repo to /usr/local/bin/ which is assumed to be in the current $PATH:

  • ln -s "$(pwd)/fpp" /usr/local/bin/fpp
  • fpp --help # should work!


For tmux users, you can additionally install tmux-fpp which adds a key combination to run PathPicker on the last received stdout. This makes jumping into file selection mode even easier. (Check it out here!)

Advanced Functionality

As mentioned above, PathPicker allows you to also execute arbitrary commands using the specified files. Here is an example showing a git checkout command executed against the selected files:

The selected files are appended to the command prefix to form the final command. If you need the files in the middle of your command, you can use the $F token instead, like:

cat $F | wc -l

Another important note is that PathPicker, by default, only selects files that exist on the filesystem. If you want to skip this (perhaps to selected deleted files in git status), just run PathPicker with the --no-file-checks (or -nfc, for short) flag.

How PathPicker works

PathPicker is a combination of a bash script and some small Python modules. It essentially has three steps:

  • Firstly, the bash script redirects all standards out into a python module that parses and extracts out filename candidates. These candidates are extracted with a series of regular expressions, since the input to PathPicker can be any stdout from another program. Rather than make specialized parsers for each program, we treat everything as noisy input, and select candidates via regexes. To limit the number of calls to the filesystem (to check existence), we are fairly restrictive on the candidates we extract.

The downside to this is that files that are single words, with no extension (like test), that are not prepended by a directory will fail to match. This is a known limitation to PathPicker, and means that it will sometimes fail to find valid files in the input.

  • Next, a selector UI built with curses is presented to the user. At this point you can select a few files to edit, or input a command to execute.

  • Lastly, the python script outputs a command to a bash file that is later executed by the original bash script.

It's not the most elegant architecture in the world but, in our opinion, it provides a lot of utility.

Documentation & Configuration

For all documentation and configuration options, see the output of fpp --help.

Join the PathPicker community

See the file for how to help out.


PathPicker is MIT licensed.

  • Created a script for automatic creation of .deb packages from source Resolve #43

    Created a script for automatic creation of .deb packages from source Resolve #43

    As mentioned by @pcottle , I have made the necessary additions to and created all necessary files in debian directory which would facilitate the creation of the debian package. Please review.

    I have already accepted Facebook's Contributor License Agreement (CLA).

    CLA Signed 
    opened by pallavagarwal07 30
  • Linux packages

    Linux packages

    It would be good to have Linux packages available, at least .deb and .rpm versions. I don't know anyone that uses Linuxbrew, it doesn't seem ideal on Linux when better solutions exist.

    The HHVM team distribute Linux packages, you could probably see how they do it.

    help wanted 
    opened by Daniel15 29
  • Doesn't work when login shell is csh

    Doesn't work when login shell is csh

    Darwin wkoszek-macbook.local 14.5.0 Darwin Kernel Version 14.5.0: Wed Jul 29 02:26:53 PDT 2015; root:xnu-2782.40.9~1/RELEASE_X86_64 x86_64

    My login shell is CSH. To rule out CSH, I've run Bash in iTerm2 window and tested too. Same problem. I tested in Vagrant with ubuntu/trusty64. Stuff works OK there, so what I describe below seems to be MacOSX specific.

    I did:

    brew update brew install fpp.

    cd /tmp mkdir sample cd sample cal 2010 > 2010 cal 2011 > 2011 cal 2012 > 2012

    /bin/ls -1 ./* | fpp

    I select 2010, press f, select 2011, press f, press c, type 'cat', . Nothing happens. I'm dropped to fpp subshell. I'd expect to see output from cat'ed files.

    ---------------- cat ~/.fpp/ ---------------------- if type shopt > /dev/null; then shopt -s expand_aliases fi

    echo "executing command:" echo "cat './2010' './2011'"

    cat './2010' './2011'

    So selection part works OK. Execution is doing something wrong.

    I started to add some debugging code:

    opened by wkoszek 25
  • ANSI color support

    ANSI color support

    ~~This is a shitty first pass at colors that I hacked together because I couldn't sleep.~~ Now better!

    Turns out ncurses doesn't really support (AFAIK, someone please correct me...) setting foreground/background color combinations directly, so I cache and create color_pair as I go along. Most terms have at least 32 and mine on OSX seems to have 256.

    I'm also totally not a python developer, so the code here is probably quite not idomatic.

    Screencap because I don't know how to do that cool video thing: the command was git diff --color | fpp screen shot 2015-05-08 at 3 30 50 am

    Things to improve on

    • Make the chrome use colors instead of hardcoding color_pair(0).
    CLA Signed 
    opened by lastquestion 16
  • Allow specifying command as an argument to fpp

    Allow specifying command as an argument to fpp

    Would this be possible? Something like:

    git status | fpp -c 'git add'

    So that the default action is overridden and I can just hit 'enter' after selecting files to run git add on them.

    enhancement pcottle-ASAP 
    opened by xatnys 15
  • x mode

    x mode

    x mode labels lines so that files can be selected without scrolling. Enter x mode by pressing x, select lines by typing their label. Demo

    CLA Signed pending-nits 
    opened by heyitsxavier 15
  • Allow preconfigured commands through custom key bindings

    Allow preconfigured commands through custom key bindings

    For use cases where PP is used frequently with the same command, it's quite annoying to have to always type the same command (eg. rspec for Ruby testing).

    This PR allows the user to associate custom commands that can be executed through specified keys (eg. r for rspec), speeding up the PP workflow for repetitive command executions.

    Custom bindings/commands are stored in the <FPP_DIR>/.fpp.keys (in the [bindings] group) as standard text configuration file. The existing clean FPP internal interface allows such configuration functionality to be trivially extended, for example, in case FPP will implement a static configuration.

    This implementation is the simplest possible; notably, it doesn't support keys already bound (which would significantly complicate the feature).

    Due to the test framework, it's not easy to write an end-to-end test - in fact, the existing functionality for executing command hasn't this type of tests; therefore, the test have been updated to inspect the visualization of the custom keys/commands.

    CLA Signed 
    opened by saveriomiroddi 14
  • add cmd support (-c, --command)

    add cmd support (-c, --command)

    I want to add a test for this, but because it spans the whole batch script -> python thing, I want some guidance.

    Passes pep8.

    CLA Signed 
    opened by lastquestion 14
  • PathPicker pollutes user home directory

    PathPicker pollutes user home directory

    PathPicker creates multiple files in the user home directory:

    $ ls .fb*
    .fbPager.log  .fbPager.pickle  .fbPager.selection.pickle

    Normally such files are stored under $HOME/.local/share or $HOME/.config directory on Linux. Please see XDG Base Directory Specification for details.

    opened by vitaut 14
  • added test case for describe file feature

    added test case for describe file feature

    is there a better way to add a change to a PR that was already merged and closed?

    anyways, here's a passing test case, let me know if that's not what you were looking for 😄

    CLA Signed awaiting-reply 
    opened by rjdean123 12
  • Feature Request: Make man page easier to read, put each flag in its own line.

    Feature Request: Make man page easier to read, put each flag in its own line.

    Original title: Feature Request: Fpp persistent mode, for opening files in $EDITOR, one-by-one.

    This FR is a bit hard to describe, so I'll give a concrete example which is probably easier to understand.

    Consider pacman -Ql fpp which prints the list of all files installed by the fpp package in Arch Linux:

    % pacman -Ql fpp
    fpp /usr/
    fpp /usr/bin/
    fpp /usr/bin/fpp
    fpp /usr/share/
    fpp /usr/share/doc/
    fpp /usr/share/doc/fpp/
    fpp /usr/share/doc/fpp/
    fpp /usr/share/doc/fpp/
    fpp /usr/share/doc/fpp/
    fpp /usr/share/doc/fpp/assets/
    fpp /usr/share/doc/fpp/assets/ZeroClipboard.min.js
    fpp /usr/share/doc/fpp/assets/ZeroClipboard.swf
    fpp /usr/share/doc/fpp/assets/bootstrap.min.css

    Now let's say I want to use fpp against this very output:

    % pacman -Ql fpp | fpp

    This does what you expect: It opens fpp against the output above.

    Now here's my use case: I'd like to interactively navigate that output to open detected files one by one with my favorite $EDITOR:

    1. I'd navigate to /usr/bin/fpp and press Enter. That opens it in my $EDITOR.
    2. After studying the file, I quit the editor.

    Now here's my feature request:

    Observed behavior: After 2), I get back to the command prompt.

    Wanted behavior: After 2), I would like to get back to the previous fpp exec, as if I had run pacman -Ql fpp | fpp again. My next action would be to use the fpp selection tool to open another file in my $EDITOR (say, /usr/share/doc/fpp/, then close it, then open another file, and so on.

    In other words, the idea is to maintain the output of a given command fixed, and then make fpp go continuously back to that output whenever the editor is closed.

    In that scenario, it would be best if fpp didn't execute the command (pacman -Ql fpp) again, but rather just saved the output once and then kept going back to it.

    This could be used for running commands multiple times as well; in my use case above, I open my $EDITOR multiple times, but I could also want to run different commands several times in a row, with the same output.

    opened by thiagowfx 2
  • Allow configuring keyboard controls

    Allow configuring keyboard controls

    For me, using space as the selection key feels a bit more intuitive than f or A. Would be cool to have the option of configuring keyboard controls.

    feature request 
    opened by bduffany 0
  • Configuring underline

    Configuring underline

    Thanks for this great tool.

    The default method of underlining looks pretty good (slightly shaded) in the sample pictures but in my terminal (alacritty+DejaVuSansMono+tmux) is bold and pretty hard on the eyes.

    Are there any plans to make this underlining indicator configurable?

    I was looking around in and if I were to modify it I might even just colorize the selectable files as opposed to underlining them. Just an idea.


    feature request 
    opened by etogithub 1
  • Bugs in debian/

    Bugs in debian/

    Some have been previously mentioned: The script makes assumptions about system capabilities and fails to terminate when those assumptions aren't met. In particular, it assumes fakeroot is available. If fakeroot is not available, execution continues and multiple files are deleted from the working copy. This is the outcome:

    ❯ git status
    On branch fix-builder
    Your branch is up to date with 'origin/master'.
    Changes not staged for commit:
      (use "git add/rm <file>..." to update what will be committed)
      (use "git restore <file>..." to discard changes in working directory)
            modified:   DEBIAN/control
            deleted:    usr/share/doc/pathpicker/changelog

    It also assumes the script executes from debian/, so it fails when run from project root.

    I can fix this in two ways.

    1. Fix so that it terminates if any command returns a non-zero exit code.
    2. Dockerize the build process so that the end user can build and install fpp without having to understand the package build process.

    Option 1 is simpler, but 2 is preferable (as long as we assume the user has Docker running). Option 2 also automates the build process, which may be desirable if Facebook wants to host the package in a mirror.

    opened by TimSpence 2
  • UnicodeDecodeError parsing results

    UnicodeDecodeError parsing results

    I get the following error when piping to fpp, apparently some files are binary and it's breaking

    Traceback (most recent call last):
      File "/home/tulsi/PathPicker/src/", line 84, in <module>
      File "/home/tulsi/PathPicker/src/", line 53, in doProgram
        lineObjs = getLineObjs(flags)
      File "/home/tulsi/PathPicker/src/", line 20, in getLineObjs
        inputLines = sys.stdin.readlines()
      File "/usr/lib/python3.7/", line 322, in decode
        (result, consumed) = self._buffer_decode(data, self.errors, final)
    UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc1 in position 1191: invalid start byte

    python version: 2.7.17

    opened by tulsidas 9
  • Support for ~ home sing

    Support for ~ home sing

    First of all, amazing project, keep it up! Would be great to have support for relative paths like the home ~/.gitignore one. Even better if to have variables like $HOME/.gitignore.

    Any plans on the roadmap? Best

    opened by jeanCarloMachado 1
  • FPP is really slow if your zsh config takes a while to load

    FPP is really slow if your zsh config takes a while to load

    When I run fpp there's a 3 second pause between me selecting what file I want to open and the file actually opening in my editor. My editor is an already running emacs daemon, so it should be super fast to open a file.

    I'm also running zsh as my shell.

    It took me a while to figure out, but the root cause is that fpp is starting up a new instance of zsh with the -i flag, and that my .zshconfig is really big and takes a while to load.

    If I edit the fpp script and comment out these lines, then the pause goes away (and everything still works just fine):

    if [ -z "$VIMRUNTIME" -a "$NONINTERACTIVE" = false ]; then

    So this is mostly my fault -- I have too much config in my .zshrc and it takes a long time to load -- but everything works for me without the -i flag being passed to zsh. I'm assuming that there are use cases where the -i flag is necessary, but this might be causing tons of people to think that fpp is slow to open.

    Would it be possible to set an env variable or something so that the -i flag is never passed to zsh, or to not use the -i flag by default?

    opened by spatten 1
  • Wanted AGAIN: search command

    Wanted AGAIN: search command

    I don't agree discarding this feature fits unixy way. LIke vim and less also supports search too. - = -

    Thanks again!

    Search-based navigation is faster than pressing j n times. It would be great to have / command with vim like behaviour.

    Thanks for a great tool anyway!

    feature request 
    opened by YongHaoWu 2
  • Chinese language support!

    Chinese language support!

    Hey, I'm Chinese, and my system language of CentOS is Chinese yet. I use fpp with git status, but all of Chinese character are become messy code, it's very unfriendly. Is there has any solution to solve it? THX very much~

    opened by SmartBrave 3
  • Bugs in debian packaging script

    Bugs in debian packaging script

    The good news is that does seem to create a usable .deb file.

    The script reports errors:

    PathPicker-master/debian/usr/binfatal: Not a git repository (or any of the parent directories): .git
    chmod: cannot access ‘/home/optimum/Projects/FaceBook_Path_Picker_-_fpp/PathPicker-master/debian/’: No such file or directory
    Done! Check out fpp.deb13:55:53

    It also deletes files in its own git tree, including itself! (ie. deletes

    opened by Boruch-Baum 2
  • 0.9.2(Aug 30, 2019)

  • 0.8.2(Aug 8, 2019)

  • 0.7.2(Jan 2, 2017)

    Highlights from git log 0.7.1..HEAD

    • Finally support for vim splitting with the correct line numbers from @brwong
    • Add support for disabling the slash in front of filenames with home (a vestigial hack from internal Facebook infra)
    • Some nice font fixes for better readability
    • Better support for csh, fish, and rc shells from @weakish

    Thanks everyone for the support

    Source code(tar.gz)
    Source code(zip)
    fpp.0.7.2.tar.gz(26.72 KB)
  • 0.7.1(Apr 16, 2016)

    Highlights from git log 0.7.0..HEAD

    • Support for the Home, End, Page Up, and Page Down keys from @robertbachmann (PR #228 #229)
    • Fix command mode for the fish shell (PR #227)
    • Matches even .DS_STORE (PR #223)
    • Some small edits like removing unused imports, cleaning up Debian package, and a bug that would sometimes hang the UI.

    As always, big thanks to the community for their support and contributions!

    Source code(tar.gz)
    Source code(zip)
    fpp.0.7.1.tar.gz(147.00 KB)
  • 0.7.0(Nov 27, 2015)

    Another awesome community release!

    • @gsheld added an "all input" mode in #210 which allows you to use fpp to work with non-file inputs like git branches or mercurial bookmarks. Helpful for when you just want to use the selector UI and don't have another fuzzy selector installed.
    • Improves zsh and csh support. Special thanks to @benmccormick
    • Adds support for filenames with commas and spaces and parens (in any combinatino)
    • emacsclient line jump support
    Source code(tar.gz)
    Source code(zip)
    fpp.0.7.0.tar.gz(144.00 KB)
  • 0.6.2(Sep 29, 2015)

    This is mostly a community release actually! Fixed a new issues and bugs, notably:

    • @slackorama Fixed the bash exiting error for zsh in #191
    • @slackorama also fixed #192 which was an out-of-range index error
    • @alecjacobson fixed #187 which passed the -i flag only if we are not in the vim shell (so you can use FP from within vim!)
    • Few minor fixes like #182, #181
    • Expanded line support from @pallavagarwal07 in #178
    • @Shenil fixed makefile detection in #173
    • and a number of other great fixes!
    Source code(tar.gz)
    Source code(zip)
    fpp.0.6.2.tar.gz(141.00 KB)
  • 0.6.1(Jun 8, 2015)

    Fixed a number of small but important issues and introduced a few new features:

    -- #145 #149 Expand the types of files we can parse now that we have filesystem validation -- including hyphens, spaces, etc -- #137 X mode! Select files with letters rather than UI, thanks @xavierbeynon -- #143 Jump to line in sublime text, thanks @dufferzafar -- #138 Use interactive shell to run script, which should fix zsh sourcing issues, thanks @hlian

    Source code(tar.gz)
    Source code(zip)
    fpp.0.6.1.tar.gz(139.50 KB)
    fpp.deb(33.98 KB)
  • 0.6.0(May 22, 2015)

    Huge list of updates, the biggest though being filesystem validation which enables us to expand our regexes and match on many more files. Full list:

    • #135 / #118 -- long file truncation if it doesnt fit in the screen
    • #132 allow +'s in filenames for objective c
    • #128 and #127 fix some line printing bugs
    • #117 Debian packages!
    • #114 filesystem validation
    • FPP is now version aware (prints out its own version)
    Source code(tar.gz)
    Source code(zip)
    fpp.0.6.0.tar.gz(132.50 KB)
    fpp.deb(62.65 KB)
  • 0.5.7(May 15, 2015)

    • Added Travis CI integration, so master is much more stable
    • Added command line option --clean which removes the state files for script workflows #103
    • Added command line option --version which prints out the version
    • Better help command which shows all command line options
    • Adds the much-requested --command option to preset the passed-in command #99
    • Exit code updates #102
    • Color support!! #53
    • Falls back to relative dirs #47
    Source code(tar.gz)
    Source code(zip)
    fpp.0.5.7.tar.gz(124.50 KB)
    fpp.deb(60.47 KB)
  • 0.5.6(May 10, 2015)

  • 0.5.5(May 7, 2015)

  • 0.5.4(May 4, 2015)

We are working to build community through open source technology. NB: members must have two-factor auth.
Command-line program to download videos from and other video sites


youtube-dl 95.9k Jun 5, 2021
cloc counts blank lines, comment lines, and physical lines of source code in many programming languages.

cloc Count Lines of Code cloc counts blank lines, comment lines, and physical lines of source code in many programming languages. Latest release: v1.9

null 11.7k Jun 7, 2021
:mag: Google from the terminal

googler is a power tool to Google (web, news, videos and site search) from the command-line. It shows the title, URL and abstract for each result, whi

Piña Colada 5.2k Jun 6, 2021
:bookmark: Browser-independent bookmark manager

buku buku in action! Introduction buku is a powerful bookmark manager written in Python3 and SQLite3. When I started writing it, I couldn't find a fle

Piña Colada 4.5k Jun 6, 2021
Magnificent app which corrects your previous console command.

The Fuck The Fuck is a magnificent app, inspired by a @liamosaur tweet, that corrects errors in previous console commands. Is The Fuck too slow? Try t

Vladimir Iakovlev 62.3k Jun 5, 2021
:cherry_blossom: A command-line fuzzy finder

fzf is a general-purpose command-line fuzzy finder. It's an interactive Unix filter for command-line that can be used with any list; files, command hi

Junegunn Choi 37.1k Jun 6, 2021
:duck: DuckDuckGo from the terminal

ddgr ddgr is a cmdline utility to search DuckDuckGo (html version) from the terminal. While googler is extremely popular among cmdline users, in many

Piña Colada 2.1k Jun 5, 2021
:speech_balloon: Command-line translator using Google Translate, Bing Translator, Yandex.Translate, etc.

Translate Shell Translate Shell (formerly Google Translate CLI) is a command-line translator powered by Google Translate (default), Bing Translator, Y

Mort Yao 5k Jun 6, 2021
:zap: A new cd command that helps you navigate faster by learning your habits.

z.lua A command line tool which helps you navigate faster by learning your habits ⚡ An alternative to with windows and posix shells support and v

Linwei 2k Jun 6, 2021
A command-line benchmarking tool

hyperfine 中文 A command-line benchmarking tool. Demo: Benchmarking fd and find: Features Statistical analysis across multiple runs. Support for arbitra

David Peter 7.9k Jun 6, 2021
A code-searching tool similar to ack, but faster.

The Silver Searcher A code searching tool similar to ack, with a focus on speed. Do you know C? Want to improve ag? I invite you to pair with me. What

Geoff Greer 22.1k Jun 6, 2021
A fast CSV command line toolkit written in Rust.

xsv is a command line program for indexing, slicing, analyzing, splitting and joining CSV files. Commands should be simple, fast and composable: Simpl

Andrew Gallant 7.2k Jun 5, 2021
A new way to see and navigate directory trees :

Broot A better way to navigate directories Install Broot Get an overview of a directory, even a big one br -s Notice the unlisted? That's what makes i

Canop 5.4k Jun 6, 2021