PathPicker
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.
Top Related Projects
:cherry_blossom: A command-line fuzzy finder
Simplistic interactive filtering tool
Fuzzy Finder in rust!
An interactive cheatsheet tool for the command-line
ripgrep recursively searches directories for a regex pattern while respecting your gitignore
A simple, fast and user-friendly alternative to 'find'
Quick Overview
Facebook PathPicker is an interactive command-line tool that simplifies the process of selecting files and directories from command output. It allows users to easily parse, search, and select files from a terminal for various operations, enhancing productivity in command-line workflows.
Pros
- Improves efficiency in handling large sets of files and directories
- Integrates seamlessly with existing command-line tools and workflows
- Provides a user-friendly interface for file selection and manipulation
- Supports customization through configuration files
Cons
- Limited to command-line environments, may not suit users preferring graphical interfaces
- Requires initial learning curve to master all features and shortcuts
- Dependency on Python, which may not be pre-installed on all systems
- May have performance issues with extremely large file sets
Getting Started
To install and use Facebook PathPicker:
-
Install via package manager or clone the repository:
brew install fpp # or git clone https://github.com/facebook/PathPicker.git
-
Run a command and pipe its output to
fpp
:git status | fpp
-
Use arrow keys to navigate, press
f
to select files, andEnter
to confirm. -
Customize behavior by creating a
~/.fpp
configuration file.
For more advanced usage and configuration options, refer to the project's documentation on GitHub.
Competitor Comparisons
:cherry_blossom: A command-line fuzzy finder
Pros of fzf
- More versatile, can be used for general-purpose fuzzy finding beyond file paths
- Faster performance, especially for large datasets
- Extensive integration with various tools and shells
Cons of fzf
- Steeper learning curve due to more advanced features
- Requires additional setup for some integrations
Code Comparison
PathPicker:
def getFilesFromLines(lines):
return set(parse.extractFilenames(line) for line in lines)
fzf:
find * -type f | fzf > selected
Summary
PathPicker is a specialized tool for selecting files from command output, while fzf is a more general-purpose fuzzy finder. PathPicker offers a simpler, more focused experience for file selection, whereas fzf provides greater flexibility and speed at the cost of increased complexity.
PathPicker excels in scenarios where users need to quickly select files from command output, such as git status or grep results. fzf, on the other hand, shines in a broader range of use cases, including file searching, command history browsing, and process selection.
Both tools have their merits, and the choice between them depends on the specific needs of the user and their workflow preferences.
Simplistic interactive filtering tool
Pros of peco
- Written in Go, making it faster and more lightweight than PathPicker (Python)
- More flexible and customizable with various matching modes and color schemes
- Can be used as a general-purpose interactive filtering tool, not limited to file selection
Cons of peco
- Lacks some of PathPicker's advanced file manipulation features
- May require more setup and configuration to achieve similar functionality
- Less intuitive for users who are primarily focused on file selection tasks
Code Comparison
peco:
func (fs *FilterSet) Add(f Filter) {
fs.filters = append(fs.filters, f)
}
PathPicker:
def getFilesFromLines(lines):
return list(parseFilesFromLines(lines))
Summary
peco is a versatile interactive filtering tool written in Go, offering speed and customization. It excels in general-purpose filtering tasks but may require more setup for specific file selection use cases. PathPicker, on the other hand, is a Python-based tool focused on file selection and manipulation, providing a more intuitive experience for users primarily working with files. The choice between the two depends on the user's specific needs and preferences for customization versus out-of-the-box functionality.
Fuzzy Finder in rust!
Pros of skim
- Written in Rust, offering better performance and memory safety
- More versatile, can be used as a general-purpose fuzzy finder
- Actively maintained with frequent updates
Cons of skim
- Lacks specific file path picking functionality
- May require more setup for use in specific workflows
- Less integrated with version control systems out of the box
Code comparison
skim:
pub fn run(&mut self) -> i32 {
self.read_options();
self.create_model();
self.create_interface();
self.event_loop()
}
PathPicker:
def run(self):
self.processInput()
self.output()
self.doProgram()
Key differences
PathPicker is specifically designed for selecting and manipulating file paths from command output, making it ideal for tasks like git operations. skim, on the other hand, is a more general-purpose fuzzy finder that can be adapted to various use cases.
PathPicker is written in Python, which may be easier for some users to customize but could be slower for large datasets. skim's Rust implementation offers potential performance benefits, especially for handling large amounts of data.
While PathPicker has a more focused feature set, skim's flexibility allows it to be used in a wider range of scenarios, from file searching to command history filtering.
An interactive cheatsheet tool for the command-line
Pros of navi
- Interactive command-line cheatsheet tool, offering a broader range of functionality beyond file selection
- Supports multiple shells and can be customized with user-defined cheatsheets
- Actively maintained with regular updates and improvements
Cons of navi
- Steeper learning curve due to its more complex feature set
- Requires manual creation of cheatsheets for optimal use
- May be overkill for users who only need simple file selection functionality
Code comparison
PathPicker:
def getLineObjs():
inputLines = sys.stdin.readlines()
lineObjs = []
for index, line in enumerate(inputLines):
lineObj = LineMatch(line, index)
lineObjs.append(lineObj)
return lineObjs
navi:
fn main() -> Result<(), Box<dyn std::error::Error>> {
let opts: Opts = Opts::parse();
let config = config::get_config()?;
let tldr = tldr::Tldr::new(&config);
let result = tldr.find(&opts.query)?;
println!("{}", result);
Ok(())
}
Summary
PathPicker is a focused tool for selecting files from command output, while navi is a more comprehensive command-line assistant. PathPicker excels in simplicity and ease of use for file selection tasks, whereas navi offers a wider range of features for command-line productivity but requires more setup and learning.
ripgrep recursively searches directories for a regex pattern while respecting your gitignore
Pros of ripgrep
- Significantly faster search performance, especially for large codebases
- Supports searching within compressed files and archives
- Respects .gitignore rules by default, improving relevance of search results
Cons of ripgrep
- Lacks interactive file selection and opening capabilities
- Doesn't provide a visual interface for navigating search results
- Limited to searching and doesn't offer additional file manipulation features
Code Comparison
ripgrep:
use grep_regex::RegexMatcher;
use grep_searcher::Searcher;
use ignore::WalkBuilder;
let matcher = RegexMatcher::new(r"pattern").unwrap();
let walker = WalkBuilder::new("./").build();
Searcher::new().search_path(&matcher, walker, |result| {
// Handle search results
Ok(true)
}).unwrap();
PathPicker:
import curses
from pathpicker import state_printer
from pathpicker import output
def doProgram(stdscr):
output.clearFile()
lineObjs = getParsedLines()
screen = screenControl.Controller(stdscr, lineObjs)
screen.control()
While ripgrep focuses on fast and efficient searching, PathPicker provides an interactive interface for selecting and manipulating search results. ripgrep is better suited for quick searches in large codebases, while PathPicker offers more flexibility in working with search results.
A simple, fast and user-friendly alternative to 'find'
Pros of fd
- Faster performance due to being written in Rust
- More flexible search patterns, including regex support
- Cross-platform compatibility (Windows, macOS, Linux)
Cons of fd
- Less focused on interactive file selection
- Lacks integration with text editors and other tools
- May require additional setup for some advanced features
Code Comparison
fd:
let regex = RegexBuilder::new(&pattern)
.case_insensitive(case_insensitive)
.build()
.unwrap();
PathPicker:
def get_command_to_run(command):
return command.decode('utf-8').strip()
Summary
fd is a modern, fast alternative to the traditional find
command, offering improved performance and more flexible search capabilities. It excels in quickly locating files and directories based on various criteria.
PathPicker, on the other hand, focuses on interactive file selection from command output, making it particularly useful for workflows involving version control systems and command-line tools.
While fd provides powerful search functionality, PathPicker offers better integration with existing command-line tools and text editors. The choice between the two depends on specific use cases and workflow preferences.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
PathPicker
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
- Edit the selected files in your favorite
It is easiest to understand by watching a simple demo:
Examples
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!
Requirements
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
Homebrew
Installing PathPicker is easiest with Homebrew for mac:
brew update
(to pull down the recipe since it is new)brew install fpp
Linux
On Debian-based systems, run these steps: fakeroot:
$ git clone https://github.com/facebook/PathPicker.git
$ cd PathPicker/debian
$ ./package.sh
$ ls ../pathpicker_*_all.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 https://github.com/facebook/PathPicker.git
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!
Add-ons
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 CONTRIBUTING.md file for how to help out.
License
PathPicker is MIT licensed.
Top Related Projects
:cherry_blossom: A command-line fuzzy finder
Simplistic interactive filtering tool
Fuzzy Finder in rust!
An interactive cheatsheet tool for the command-line
ripgrep recursively searches directories for a regex pattern while respecting your gitignore
A simple, fast and user-friendly alternative to 'find'
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot